Added plugin support

README.md

@@ -1,7 +1,19 @@
 # Rabbit.nvim
-![logo](/rabbit.png)
+<img src="/rabbit.png" width="512" alt="logo"/>
 Quickly jump between buffers
 
+- [Rabbit.nvim](#rabbitnvim)
+  - [Why](#why)
+  - [Install](#install)
+  - [Usage](#usage)
+  - [Configuration](#configuration)
+  - [Preview](#preview)
+- [API](#api)
+  - [Using Rabbit](#using-rabbit)
+  - [Internals](#internals)
+  - [Create your own Rabbit listing](#create-your-own-rabbit-listing)
+
+
 ---
 
 This tool tracks the history of buffers opened in an individual window. With a quick
@@ -25,23 +37,27 @@ Lazy:
 return {
     "voxelprismatic/rabbit.nvim",
     config = function()
-        require("rabbit").setup("<leader>r")  -- Any keybind you like
+        require("rabbit").setup({{opts}})     -- Detailed below
     end,
 }
 ```
 
 ### Usage
-Just run your keybind!
+Just run your keybind! (or `:Rabbit {{mode}}`)
+
+Currently available modes:
+- `history` - Current window's buffer history
+- `reopen` - Current window's recently closed buffers
 
-With Rabbit open, you can hit a number 1-0 (1-10) to jump to that buffer. You can
+With Rabbit open, you can hit a number 1-9 to jump to that buffer. You can
 also move your cursor down to a specific line and hit enter to jump to that buffer.
 
 If you hit `<CR>` immediately after launching Rabbit, it'll open your previous buffer.
 You can hop back and forth between buffers very quickly, almost like a rabbit...
 
-If you click away from the Rabbit window, it'll close.
+By default, you can switch to the opposite mode mode by pressing `r`
+
 
-If you try to modify the Rabbit buffer, it'll close.
 
 ### Configuration
 ```lua
@@ -101,6 +117,10 @@ require("rabbit").setup({
         open = {                -- Open Rabbit
             "<leader>r",
         },
+        to = {
+            history = "r",      -- Change to 'History' panel
+            reopen = "r",       -- Change to 'Reopen' panel
+        },
     },
 
     paths = {
@@ -111,32 +131,153 @@ require("rabbit").setup({
 
     colors = {                  -- These should all be highlight group names
         title = "Statement",    -- I don't feel like making a color API for this, just :hi and deal with it
-        box = "Function",
+        box = {
+            history = "Function",
+            reopen = "Macro",
+        },
         index = "Comment",
         dir = "NonText",
         file = "",
         noname = "Error",
+        shell = "MoreMsg",
     },
 })
 ```
 
+### Preview
+
+https://github.com/VoxelPrismatic/rabbit.nvim/assets/45671764/da149bd5-4f6d-4c83-b6cb-67f1be762e2a
 
-### API
+---
+
+# API
 ```lua
 local rabbit = require("rabbit")
+```
 
-rabbit.Window()                 -- Toggle Rabbit window
-rabbit.Close()                  -- Force close window; will NOT throw error
+### Using Rabbit
+
+`mode` is any of the available modes. `history` and `reopen` are included.
+```lua
+rabbit.Window(mode)             -- Close rabbit window, or open with mode
+rabbit.Switch(mode)             -- Open with mode
+rabbit.Close()                  -- Close rabbit window
 rabbit.Select(n)                -- Select an entry
+rabbit.Setup(opts)              -- Setup options
+```
+
+### Internals
+```lua
+rabbit.MakeBuf(mode)            -- Create the buffer and window
+rabbit.ShowMessage(msg)         -- Clear and show a message
 rabbit.RelPath(src, target)     -- Return the relative path object for highlighting
+rabbit.ensure_listing(winid)    -- Ensure that the window has a table for all listings
+rabbit.ensure_autocmd(evt)      -- Return winid if it's a valid event. Also calls rabbit.ensure_listing
 ```
 
+### Create your own Rabbit listing
+Calling `require("rabbit")` returns the following structure:
+```lua
+{
+    rab = {
+        win = 0,                -- Winnr for the Rabbit window
+        buf = 0,                -- Bufnr for the Rabbit buffer
+        ns = 0,                 -- Highlight namespace (used for CursorLine)
+    },
+
+    usr = {
+        win = 0,                -- Winnr for your window
+        buf = 0,                -- Bufnr for your buffer
+        ns = 0,                 -- Highlight namespace (unused)
+    },
 
-### Preview
+    ctx = {
+        border_color = "",      -- Border color for this session
+        listing = {},           -- Listing for this session
+        mode = "",              -- Mode for this session
+    },
 
-https://github.com/VoxelPrismatic/rabbit.nvim/assets/45671764/da149bd5-4f6d-4c83-b6cb-67f1be762e2a
+    opts = {},                  -- Options, as detailed above
+
+    listing = {
+        history = {},           -- History listing
+        reopen = {},            -- Reopen listing
+    },
+
+    messages = {
+        history = "",           -- Message displayed when empty
+        reopen = "",            -- Message displayed when empty
+    },
+
+    autocmd = {
+        BufEnter = function(evt) end,
+        BufDelete = function(evt) end,
+    },
+}
+```
+
+When adding your own plugin, you should add the following details *before* running `rabbit.setup(...)`,
+as setup binds the autocmds globally, which can lead to conflicts if called multiple times.
+
+1. Initialize `rabbit.listing.plugin_name = {}`
+   - This is how Rabbit knows your plugin exists and can be opened.
+2. Create your message strings in `rabbit.messages.plugin_name`
+   - There is a default message just in case.
+3. Set up your autocmds. The function name is the autocmd event, eg BufEnter or BufDelete
+```lua
+-- Default autocmds, so you make your own.
+function table.set_subtract(t1, e)
+    for i, v in ipairs(t1) do
+        if v == e then
+            table.remove(t1, i)
+            return true
+        end
+    end
+    return false
+end
+
+function table.set_insert(t1, e)
+    table.set_subtract(t1, e)
+    table.insert(t1, 1, e)
+end
+
+
+function rabbit.autocmd.BufEnter(evt)
+    -- Grab current winid, and return if it's rabbit
+    local winid = rabbit.ensure_autocmd(evt)
+    if winid == nil then
+        return
+    end
+
+    -- Put current buffer ID at top of history
+    table.set_insert(rabbit.listing.history[winid], evt.buf)
+
+    -- Remove if reopened
+    table.set_subtract(rabbit.listing.reopen[winid], evt.file)
+end
+
+
+function rabbit.autocmd.BufDelete(evt)
+    -- Grab current winid, and return if it's rabbit
+    local winid = rabbit.ensure_autocmd(evt)
+    if winid == nil then
+        return
+    end
+
+    -- Remove current buffer ID from history
+    local exists = table.set_subtract(rabbit.listing.history[winid], evt.buf)
+
+    -- Only add to reopen if it's not blank and not a plugin (oil, shell, etc)
+    if exists and #evt.file > 0 and evt.file:sub(1, 1) ~= "/" then
+        table.set_insert(rabbit.listing.reopen[winid], evt.file)
+    end
+end
+```
+
+**NOTE:** You can use buffer IDs or file names in your listing table. The first listing will only
+be removed if the filename or buffer ID matches. Do NOT store buffer IDs on BufDelete, as the
+buffer ID no longer exist and an error will be thrown.
+
+Buffers without a filename will be shown as `#nil ID`, where ID is the buffer ID.
 
-### DISCLAIMER
-This is my first project in Lua, and my first plugin for Neovim.
-Instead of shaming me for bad choices, let me know how I can
-improve instead. I greatly appreciate it.
+Shell buffers, like Term will be shown like `#bash ID` or `#zsh ID`

lua/rabbit/defaults.lua

@@ -46,11 +46,15 @@ local box = {
 local options = {
     color = {
         title = "Statement",
-        box = "Function",
+        box = {
+            history = "Function",
+            reopen = "Macro",
+        },
         index = "Comment",
         dir = "NonText",
         file = "",
         noname = "Error",
+        shell = "MoreMsg",
     },
     box = box.rounded,
     window = {
@@ -68,6 +72,10 @@ local options = {
         quit = { "<Esc>", "q", "<leader>" },
         confirm = { "<CR>" },
         open = { "<leader>r" },
+        to = {
+            history = "r",
+            reopen = "r",
+        },
     },
     paths = {
         min_visible = 3,

lua/rabbit/doc.lua

@@ -4,21 +4,32 @@
 
 ---@class RabbitColor
 ---@field title VimHighlight Vim highlight group name.
----@field box VimHighlight Vim highlight group name.
+---@field box RabbitBoxColor
 ---@field index VimHighlight Vim highlight group name.
 ---@field dir VimHighlight Vim highlight group name.
 ---@field file VimHighlight Vim highlight group name.
 ---@field noname VimHighlight Vim highlight group name.
+---@field shell VimHighlight Vim highlight group name.
+--.
+
+
+---@class RabbitBoxColor
+---@field [ValidMode] VimHighlight Vim highlight group name.
 --.
 
 
 ---@class RabbitKeys
 ---@field quit string[]
 ---@field confirm string[]
 ---@field open string[]
+---@field to RabbitModeKeys
 --.
 
 
+---@class RabbitModeKeys
+---@field [ValidMode] string
+--.
+
 ---@class RabbitWindow
 ---@field title string
 ---@field emphasis_width number
@@ -82,6 +93,12 @@
 --.
 
 
+---@class RabbitReopen
+---@field [winnr] filepath[]
+--.
+
+
+
 ---@class RabbitCornerPin
 ---@field [1] "bottom" | "top"
 ---@field [2] "left" | "right"
@@ -92,3 +109,19 @@
 ---@field top integer
 ---@field left integer
 --.
+
+
+---@class RabbitContext
+---@field border_color VimHighlight Vim highlight group name
+---@field listing RabbitHistory | RabbitReopen
+---@field mode ValidMode
+--.
+
+
+---@alias ValidMode "history" | "reopen"
+
+
+---@class RabbitListing
+---@field history RabbitHistory
+---@field reopen RabbitReopen
+--.