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(evt: NvimEvent, winid: integer) Called whenever Rabbit is opened
---@field RabbitInvalid? fun(evt: NvimEvent, winid: integer) Called whenever an entry should be discarded
---@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

Rabbit Events

These are all mock events, meaning they are structured like other Neovim events.

• RabbitEnter

  This event is thrown whenever your plugin is opened. Use it whenever you need to set up additional or persistent listings, like in Harpoon.

  local RabbitEnter = { ---@type Rabbit.Event.Enter
      -- The currently active buffer ID
      buf = rabbit.user.buf,
  
      -- Event type
      event = "RabbitEnter",
  
      -- The currently active window ID
      id = rabbit.user.win,
  
      -- The currently active buffer's filename
      file = vim.fn.expand("%:p"),
  
      -- The currently scoped directory, as defined by the user's `path_key` preferences
      match = rabbit.func.path_key()
  }

• RabbitInvalid

  This event is thrown whenever a buffer or filename is found to be invalid. Eg, a buffer was closed, or a file was deleted. Use it to delete from any listings. rabbit.ctx.listing will reflect the final listing shown to the user.

  local RabbitInvalid = { ---@type Rabbit.Event.Invalid
      -- Currently active buffer ID
      buf = rabbit.user.buf,
  
      -- Event type
      event = "RabbitInvalid",
  
      -- Currently active window ID
      id = rabbit.user.win,
  
      -- Target Bufnr (as string) or filename
      file = "15" | "/home/user/git/repo/deleted.txt",
  
      -- How to parse the file property above
      match = "bufnr" | "filename"
  }

• RabbitFileRename

  This is called in place of Neovim's existing BufFilePre and BufFilePost events. Use it to rename any filenames in your listings, especially persistent ones. Please don't hesitate to listen to this event instead of BufFilePre and BufFilePost. Keep in mind, no events will be thrown if anything is renamed outside of Neovim.

  local RabbitFileRename = { ---@type Rabbit.Event.FileRename
      -- Affected buffer ID
      buf = (BufFilePost).buf,
  
      -- Event type
      event = "RabbitFileRename",
  
      -- NEW filename
      file = (BufFilePost).file,
  
      -- Current window ID
      id = rabbit.user.win,
  
      -- OLD filename
      match = (BufFilePre).file
  }

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.

Additional Notes

The RabbitEnter event provides the user's scoped directory for you. It is recommended that you cache this (as Plugin._dir or something) or call require("rabbit").path_key() if necessary.