Utilities

Types
Rabbit.Mem.RelPath: table
Relative filepath details
key type description
dir string Dir name, eg .../rel/to/
file string Base name, eg foo.txt
merge string The merged path, eg .../rel/to/foo.txt
parts string[] All parts to the path, eg
{ "..", "..", "rel", "to", "foo.txt" }
source string Real, absolute path of the source file
target string Real, absolute path of the target file
[integer] Rabbit.Mem.RelPath Recalculate the relative path with a new maximum display width. Eg, [80] recalculates the path with a maximum width of 80 characters
Rabbit.Writeable: table
JSON data that you can save with ease
key type description
[any] any Actual data
__Dest string Destination file path
__Save function A function that takes no arguments to save the current data.

Memory API
local MEM = require("rabbit.util.mem")
MEM.rel_path(target)
  1. Rabbit.Mem.RelPath
Returns the relative path to the target file from the current file. Also handles trimming and overflows.

Parameters
param type details
target string /path/to/target

Returns
type details
→ Rabbit.Mem.RelPath Calculated file path
MEM.Read(src)
  1. Set: Rabbit.Writeable
  2. success: boolean
Reads a JSON file


Parameters
param type details
src string File path

Returns
type details
→ Set: Rabbit.Writeable File contents. If the file doesn't exist, returns an empty Rabbit.Writeable
2 success: boolean If the file exists
MEM.Write(data, dest)
  1. nil
Writes a JSON file, creating the necessary parent directories if they don't exist

Parameters
param type details
data table File contents
WARNING: Cannot be Rabbit.Writeable
dest string File path
MEM.next_name(names, name, suffix)
  1. new_name: string
Add +# to the end of the name until it's unique

Parameters
param type details
names table<string, true> Taken names. The keys are names to ensure no duplicates
string[] Taken names. Converted to table<string, true> to ensure uniqueness
suffix string Suffix to append after the corrected name. Eg, ".lua" -> "new_file+1.lua"

Returns
type details
→ new_name: string New, unique name

Notes
MEM.exists(path)
  1. boolean
Checks if a file exists

Parameters
param type details
path string File path

Returns
type details
→ boolean Whether the file exists
MEM.is_type(path, ...)
  1. boolean
Checks if a file is a type

Parameters
param type details
path string File path
... "file" File
"directory" Directory
"socket" Socket
"fifo" FIFO
"char" Character device
"block" Block device

Returns
type details
→ boolean Whether the target file is any of the types provided

Notes
  1. This function automatically resolves links. You may NOT check if a file is a link.
  2. If the file does not exist, it returns false
  3. If there are no types to check, but the file exists, it returns true
MEM.stat(path)
  1. stat: uv.fs_stat.result
  2. err: string
  3. err_name: string
Shorthand for vim.uv.fs_stat(...) , but automatically resolves links



Parameters
param type details
path string File path

Returns
type details
→ stat: uv.fs_stat.result Stat result, resolving any links. nil if err
2 err: string Error message
3 err_name: string Error name

Set API
local SET = require("rabbit.util.set")
SET.keys(t)
  1. any[]
Returns the keys of a table

Parameters
param type details
t table Table

Returns
type details
→ any[] Table keys
SET.extend(...)
  1. Set<T>
Returns a new set with all the elements from the other tables

Parameters
param type details
... T[] Tables

Returns
type details
→ Set<T> New set
local Set = SET.new(arr) Creates a new Set object from an array

Parameters
param type details
arr any [] Array of values. This array is deep-copied, and any duplicate values are immediately dropped
Set:add(elem, idx)
  1. self
Adds a value to the set

Parameters
param type details
elem T Value to add
T[] Values to add
idx integer Index to insert at
  • If negative, the value is inserted at the end. Eg, -1 = last, -2 = second to last
  • Default: 1

Returns
type details
→ self Itself for chaining multiple operations

Notes
Set:pop(idx)
  1. elem: T
Pops an element at index idx and returns it

Parameters
param type details
idx integer Index to pop
  • If negative, the value is popped from the end. Eg, -1 = last, -2 = second to last
  • Default: 1

Returns
type details
→ T Popped element
Set:del(elem)
  1. self
  2. count: integer
Removes elements from the set


Parameters
param type details
elem T Element to remove
T[] Elements to remove

Returns
type details
→ self Itself for chaining
2 count: integer Number of elements removed
Set:tog(elem, include)
  1. state: boolean
Toggles an element in the set

Parameters
param type details
elem T Element to toggle
include true Include the element
false Exclude the element
nil Toggle the element

Returns
type details
→ boolean If the element is in the set

Notes
Set:idx(elem)
  1. idx: integer
Returns the index of an element

Parameters
param type details
elem T Element to get the index of

Returns
type details
→ integer Index of the element. nil if the element is not in the set
Set:sub(elem, new)
  1. self
Substitutes an element for another

Parameters
param type details
elem T Element to substitute
T[] Elements to substitute
new T New element

Returns
type details
→ self Itself for chaining

Notes
  1. When substituting multiple elements, only the first will be substituted, the rest will be removed
  2. If the new element is already in the set, it will be moved to the first match
Set:AND(other)
  1. intersection: Set<T>
Returns a new set in which all elements are present in both sets

Parameters
param type details
other Set<T> Other set

Returns
type details
→ intersection: Set<T> New set
Set:OR(other)
  1. union: Set<T>
Returns a new set in which all elements are present in either set

Parameters
param type details
other Set<T> Other set

Returns
type details
→ union: Set<T> New set
Set:XOR(other)
  1. difference: Set<T>
Returns a new set in which all elements are present in exactly one of the sets

Parameters
param type details
other Set<T> Other set

Returns
type details
→ difference: Set<T> New set
Set:map(fn)
  1. mapped: Set<R>
Returns a new set in which all elements are mapped by the function

Parameters
param type details
fn fun(key, elem: T) → R Mapping function. If the function returns nil, the element is removed

Returns
type details
→ mapped: Set<R> New set

Notes
Set:sort(fn)
  1. self
Sorts the set

Parameters
param type details
fn fun(a: T, b: T) → boolean Sorting function

Returns
type details
→ self Itself for chaining
Set:put(idx, elem)
  1. self
Puts an element into the slot

Purpose
table.insert does not work on integer keys that are out of range. Eg, if #tbl returns 10, but you have an element at 100, then table.insert(tbl, 100, elem) will overwrite the element at 100. This function implements table . insert for integer keys out of bounds.

This is incredibly useful for priority calculations for things like highlight groups, since previous elements are retained even for priorities greater than the length of the list.

Parameters
param type details
idx integer Index of the element
elem T Element to put

Returns
type details
→ self Itself for chaining

Notes
  1. This does not remove duplicate elements
  2. For negative indexes, elements are made more negative. Eg, if you insert an element (new) at -1, but an element (old) is already there, then old is moved to -2 before new is inserted at -1.
  3. inb4 Set:put(99999999, elem) , you filthy web devs
Set:compact()
  1. Set<T>
Removes all empty slots. For use with Set:put

Returns
type details
→ Set<T> Compacted set

Notes

Term API
local TERM = require("rabbit.util.term")
TERM.feed(keys)
  1. nil
Feeds keys and escape codes to the terminal

Purpose
Shorthand for:
vim . fn . feedkeys ( vim . api . nvim_replace_termcodes ( keys , true , true , true ), "n" )

Parameters
key type details
keys string Keys to feed to the terminal
TERM.realcol()
  1. column: integer
Returns the current column, accounting for UTF-8 characters

Returns
type details
→ column: integer Current column, accounting for UTF-8 characters. Eg, although of a nerd-font character consumes three bytes, it only consumes one column. This returns the 0-indexed real column.
TERM . realplace ( row , col , win )
  1. nil
Places the cursor at a specific position, accounting for UTF-8 characters

Parameters
key type details
row integer 1-indexed row
col integer 1-indexed column. If out of bounds, it will be truncated to the line length
win integer Window ID. If nil, the current window is used. This is used to retrieve the current buffer ID
TERM.win_config(win)
  1. Rabbit.Stack.WinConfig
Returns the configuration of a window, including position and width

Parameters
key type details
win integer Window ID

Returns
key type details
config Rabbit.Stack.WinConfig Window configuration
nil Window does not exist

Notes
TERM.get_yank(escape)
  1. start_idx: integer
  2. end_idx: integer
Returns the start and end lines of the current visual selection

Parameters
key type details
escape boolean Whether to exit visual mode after getting the selection details. Defaults to true

Returns
type details
→ start_idx: integer Start line (1-indexed)
2 end_idx: integer End line (1-indexed)

Notes
  1. Sorting start_idx and end_idx is handled automatically
  2. The clipboard is not touched. This only provides the start and end lines of the selection
TERM.syllables[word]
  1. syllables: string[]
A table which contains the syllables of a given word.

Parameters
key type details
word string The word to get the syllables of

Returns
type details
→ syllables: string[] A list of syllables

Notes