Skip to content

API Documentation

Jump to bottom Edit New page
PRIZ ;] edited this page Feb 22, 2025 · 17 revisions

Note

All typing information is in the luadoc folder

Rabbit API

---@type Rabbit.Instance
local rabbit = require("rabbit")

Basic Interface

rabbit.Window(plugin)

Closes Rabbit if it's open. Opens Rabbit if it's closed.

  • Parameters
    param type description
    plugin string Plugin name



rabbit.Switch(plugin)

Always opens Rabbit to a particular plugin

  • Parameters
    param type description
    plugin string Plugin name
  • Returns
    idx type description
    - Rabbit.Instance For chaining

    Example of chaining:

    -- Opens the plugin and immediately selects the first entry
require("rabbit").Switch(...).func.select(1)



rabbit.Redraw()

Actually draws contents to the screen





Drawing Routine

rabbit.ShowMessage(text)

Clears screen, displays text, and handles wrapping

  • Parameters
    param type description
    text string Message to display



rabbit.RelPath(source, target)

Generates a relative path object for highlighting

  • Parameters
    param type description
    source string Origin file (where from)
    target string Destination file (where to)
  • Returns
    key type description
    dir string Directory portion; automatically shortened to fit on screen
    name string File name portion; unchanged



rabbit.Legend(plugin, line)

Sets keybinds and draws keymap legend for quick reference

  • Parameters
    param type description
    plugin ? string Plugin name
    line ? integer Which line to start drawing on



rabbit.MakeBuf(plugin)

Creates the buffer and stores context for drawing. Also calls the RabbitEnter event.

  • Parameters
    param type description
    plugin string Plugin name
  • Returns
    key type description
    nr integer Buffer ID
    w integer Calculated window width
    h integer Calculated window height
    fs false Rabbit is windowed

    Rabbit.Screen.Spec

    		 Empty line
    pos integer Column the cursor should land on



rabbit.BufHighlight()

Simply highlights the cursor's current line, if the position is a valid selection





Plugins & Setup

rabbit.setup(opts)

Sets up configuration and loads selected plugins

  • Parameters
    param type description
    opts

    Rabbit.Options

    		 Options
    string Keybind to open rabbit



rabbit.attach(plugin, default)

Attaches a plugin to Rabbit.

NOTICE

  1. Plugins should never share a name
  2. Plugins should never bind an autocmd
  • Parameters
    param type description
    plugin string Built-in plugin name
    (harpoon, oxide, reopen, history)

    Rabbit.Plugin

    		 Custom plugin
    default ? boolean If true, this will be the new default plugin (the one that's opened first)



rabbit.make_mem(name)

Creates a persistent memory file and returns the filepath

  • Parameters
    param type description
    name string File name, generally the plugin name
  • Returns
    idx type description
    - string The real file path



rabbit.func[...]

Each plugin has its own implementation of these functions. The only default ones are the following:

  • rabbit.func.select(ln)
    • Selects the current entry
  • rabbit.func.close()
    • Closes the Rabbit window
param type description
ln integer The current line number (not bounded)

IMPORTANT: Double-check the plugin-specific API documentation, as it may override the default functionality. For example, harpoon.func.select(...) will check if the current entry is a collection. If not, it will revert to the default rabbit.func.select(...)





Event Propagation

rabbit.autocmd(evt)

Propagates an event to all plugins

  • Parameters
    param type description
    evt NvimEvent The event to propagate


rabbit.ensure_listing(winid)

Creates an associated listing for a particular window in all plugins, so the plugin doesn't have to do it manually.

  • Parameters
    param type description
    winid integer Window ID



rabbit.path_key(plugin)

Returns the path key that the plugin will use.

  • Parameters
    param type description
    plugin ? Rabbit.Plugin The target plugin. Falls back to rabbit.ctx.plugin
  • Returns
    idx type description
    - string The resulting path_key







Input API

local input = require("rabbit.input")

Free input

input.prompt(title, callback, check)

Provides a text-box input

image

  • Parameters
    param type description
    title string The question/prompt input
    callback fun(str) Callback for when the input is accepted
    The parameter is the user's input string
    check ? fun(str)->bool Check function to validate user input.
    Returns false when input is invalid





Choices

input.menu(title, desc, default, finally, entries)

Creates a menu in which the user can select from multiple options

image

  • Parameters
    param type description
    title string Window title
    desc ? string Description. Usually extra context about the popup
    default ? string If matched, then the entry's callback is run without the menu ever being shown.
    This is useful for user's default actions
    finally ? fun() A callback for when the menu is closed for any reason
    entries Rabbit.Input.Menu.Entry[] A list of menu entries





Popup

input.warn(title, msg, color)

Shows a popup to the user. The popup is closed upon any interaction.

image

  • Parameters
    param type description
    title string Message box title
    msg string Actual content message
    color ? string Border color highlight group





Set API

local set = require("rabbit.plugins.util")

Set/Array

set.index(tbl, elem)

Finds the first index of an entry in the table

  • Parameters
    param type description
    tbl { [int] : 🇪 } The array of elements
    elem 🇪 The element to remove
  • Returns
    idx type description
    - integer The index of the entry
    nil The entry was not found



set.sub(tbl, elem)

Removes all instances of an entry in the table

  • Parameters
    param type description
    tbl { [int] : 🇪 } The array of elements
    elem 🇪 The element to remove
  • Returns
    idx type description
    - boolean Whether anything was removed



set.add(tbl, elem)

Removes all instances of an entry in the table, and adds a new one as the first element

  • Parameters
    param type description
    tbl { [int] : 🇪 } The array of elements
    elem 🇪 The element to add




Files & Memory

set.read(name)

Reads a JSON file and returns the table; returns an empty table if the file doesn't exist

  • Parameters
    param type description
    name string The file name to load
  • Returns
    idx type description
    - table The parsed JSON object



set.save(name, tbl)

Saves a table to a file as JSON

  • Parameters
    param type description
    name string File name to write to
    tbl table The table to save as JSON
  • Returns
    idx type description
    - boolean Whether or not the save was successful



set.clean(tbl, only_children)

Cleans a listing table to remove any deleted files & folders

  • Parameters
    param type description
    tbl { [int] : str } An array of file names
    { [str] : any } A dictionary of { [filename] : any } objects
    only_children ? boolean If true, the first set of keys will NOT be touched. Useful for custom path_key functions
  • Returns
    idx type description
    - table The cleaned up table







Internal flags

scope flag type description
Rabbit path_key str These are set from the last RabbitEnter event
value description
unset Rabbit has not been called yet
plugin:func Custom path key function set at the plugin level
plugin:str Custom path key string set at the plugin level
global:func Custom path key function set at the global (Rabbit) level
global:str Custom path key string set at the global (Rabbit) level
fallback No custom path key function has been set
Rabbit last_path str The path value from the last RabbitEnter event
Rabbit path_debug str For developer use only. Rabbit will never touch this. It will be printed underneath, like so
Plugin.sys path_key bool If set, then this plugin uses a custom path_key function or string.
Use with the set.clean function: set.clean(tbl, p.flags.sys.path_key)

*note: this is only set upon plugin initialization

Be sure to register your Neovim config on Dotfyle to passively promote this plugin!

Feeling generous? I also have a Patreon
Add a custom sidebar
Clone this wiki locally