Custom Plugin

Note

All typing information is in the luadoc folder

Warning

You should only call rabbit.attach(...) after you run rabbit.setup(...)

Rabbit Plugin Spec

param	type	example	description
color	string	#d7827e	Border color
name	string	"history"	Unique Plugin name
switch	string	"r"	Key-press to switch to this plugin
empty_msg	string	"Empty!"	Message displayed when the listing is empty
skip_same	boolean	true	Whether to skip the first entry if it's the same as the current file
memory	string|nil	nil	Set to "" to generate a persistent storage file; will automatically be set to filename on load
opts	table	{}	Any other configurable options This will be set by rabbit.opts.plugin_opts[plugin].opts
keys	keys spec	{}	Default keybinds for custom functions
func	func spec	{}	Extra functions needed for operation
evt	evt spec	{}	Autocmd event functions
listing	list spec	{}	Listing details
init	fun(p: Rabbit.Plugin)	function(_) end	Init function, for whatever you need

See builtin plugins for a few examples

Rabbit Keys Spec

---@class Rabbit.Plugin.Keymap
---@field select? string[] Keys to select the current entry
---@field close? string[] Keys to close the window
---@field file_add? string[] Keys to add a file, like in Harpoon
---@field file_del? string[] Keys to delete a file, like in Harpoon
---@field [string] string[]

{
    select = { "<CR>" },
    quit = { "<Esc>", "q", "<leader>" },
}

The key, eg select or quit should be defined in plugin.func or rabbit.func.

If the user has any keybinds set for a particular function, they take priority over these.

Rabbit Func Spec

---@class Rabbit.Plugin.Functions
---@field select? fun(ln: integer) Select the current entry
---@field close? fun(ln: integer) Close Rabbit
---@field file_add? fun(ln: integer) Add a file, like in Harpoon
---@field file_del? fun(ln: integer) Delete a file, like in Harpoon
---@field [string] fun(ln: integer)

-- Example of a custom function
---@param ln integer Highlighted line number
function plugin.func.select(ln)
    vim.cmd("b " .. M.listing[0][ln])
    require("rabbit").func.close()
end

Default function names:

• select - When the user selects an entry
  • You should close Rabbit in here
• close - When the user closes Rabbit
• file_add - When the user wants to add the current file to the listing
  • You should call require("rabbit").Redraw() to refresh the listing
• file_del - When the user wishes to delete the currently highlighted entry
  • You should call require("rabbit").Redraw() to refresh the listing

Any functions defined in your plugin will overwrite the default ones provided by Rabbit

Rabbit Evt Spec

---@class Rabbit.Plugin.Event
---@field BufEnter? fun(evt: NvimEvent, winid: integer) Autocmd on BufEnter
---@field BufDelete? fun(evt: NvimEvent, winid: integer) Autocmd on BufDelete
---@field RabbitEnter? fun(winid: integer) Called whenever Rabbit is opened
---@field [string] fun(evt: NvimEvent, winid: integer) Extra autocmd

-- Add the current buffer to the listing
---@param evt NvimEvent
---@param winid integer
function plugin.evt.BufEnter(evt, winid)
    set.add(plugin.listing[winid], evt.buf)
end

BufEnter is a valid Neovim event. The only difference is that Rabbit will add the winid parameter for your convenience

There is also a RabbitEnter event, but it only accepts the winid parameter. It is called before the window is drawn in case you need to initialize a listing for viewing.

Rabbit Listing spec

---@class Rabbit.Plugin.Listing
---@field [0] Rabbit.Plugin.Listing.Window Listing shown to the user
---@field persist? Rabbit.Plugin.Listing.Persist Internal persistent listing
---@field opened? Rabbit.Plugin.Listing.Window Tracks open files
---@field [integer] Rabbit.Plugin.Listing.Window
---@field [string] Rabbit.Plugin.Listing.Window

---@class Rabbit.Plugin.Listing.Window
---@field [integer] integer | string

---@class Rabbit.Plugin.Listing.Persist
---@field [string] Rabbit.Plugin.Listing.Persist.Table `Directory Name : Table` table

---@class Rabbit.Plugin.Listing.Persist.Table
---@field [integer] string Just the filename; no Oxide details
---@field [string] Rabbit.Plugin.Listing.Persist.Entry `File Name : Entry` table

---@class Rabbit.Plugin.Listing.Persist.Entry
---@field age integer The last time the file was accessed
---@field count integer The total number of times this file was accessed

The key, any is normally the window ID, although there is nothing stopping you from creating custom listings. Just note that 0 is the default. If set, it is always shown.