feat: more extensive read me and add now comes with config ref

README.md

@@ -49,7 +49,7 @@ You will want to add your style of remaps and such to your neovim dotfiles with
 the shortcuts you like.  My shortcuts are for me.  Me alone.  Which also means
 they are designed with dvorak in mind (My layout btw, I use dvorak btw).
 
-### harpoon:setup
+### harpoon:setup() IS REQUIRED
 it is a requirement to call `harpoon:setup()`.  This is required due to
 autocmds setup.
 
@@ -59,7 +59,9 @@ Here is my basic setup
 ```lua
 local harpoon = require("harpoon")
 
+-- REQUIRED
 harpoon:setup()
+-- REQUIRED
 
 vim.keymap.set("n", "<leader>a", function() harpoon:list():append() end)
 vim.keymap.set("n", "<C-e>", function() harpoon.ui:toggle_quick_menu(harpoon:list()) end)
@@ -126,6 +128,38 @@ harpoon:setup({
 
 ```
 
+### Config
+There is quite a bit of behavior you can configure via `harpoon:setup()`
+
+* `settings`: is the global settings.  as of now there isn't a global setting in use, but once we have some custom behavior i'll put them here
+* `default`: the default configuration for any list.  it is simply a file harpoon
+* `[name] = HarpoonPartialConfigItem`: any named lists config.  it will be merged with `default` and override any behavior
+
+**HarpoonPartialConfigItem Definition**
+```
+---@class HarpoonPartialConfigItem
+---@field encode? (fun(list_item: HarpoonListItem): string)
+---@field decode? (fun(obj: string): any)
+---@field display? (fun(list_item: HarpoonListItem): string)
+---@field select? (fun(list_item: HarpoonListItem, options: any?): nil)
+---@field equals? (fun(list_line_a: HarpoonListItem, list_line_b: HarpoonListItem): boolean)
+---@field add? fun(item: any?): HarpoonListItem
+---@field BufLeave? fun(evt: any, list: HarpoonList): nil
+---@field VimLeavePre? fun(evt: any, list: HarpoonList): nil
+---@field get_root_dir? fun(): string
+```
+
+**Detailed Definitions**
+* `encode`: how to encode the list item to the harpoon file.  if encode is `false`, then the list will not be saved to disk (think terminals)
+* `decode`: how to decode the list
+* `display`: how to display the list item in the ui menu
+* `select`: the action taken when selecting a list item. called from `list:select(idx, options)`
+* `equals`: how to compare two list items for equality
+* `add`: called when `list:append()` or `list:prepend()` is called.  called with an item, which will be a string, when adding through the ui menu
+* `BufLeave`: this function is called for every list on BufLeave.  if you need custom behavior, this is the place
+* `VimLeavePre`: this function is called for every list on VimLeavePre.
+* `get_root_dir`: used for creating relative paths.  defaults to `vim.loop.cwd()`
+
 ## ⇁ Social
 For questions about Harpoon, there's a #harpoon channel on [the Primeagen's Discord](https://discord.gg/theprimeagen) server.
 * [Discord](https://discord.gg/theprimeagen)

lua/harpoon/config.lua

@@ -1,9 +1,12 @@
 local Path = require("plenary.path")
-local function normalize_path(buf_name)
-    return Path:new(buf_name):make_relative(vim.loop.cwd())
+local function normalize_path(buf_name, root)
+    return Path:new(buf_name):make_relative(root)
 end
 
+
 local M = {}
+local DEFAULT_LIST = "__harpoon_files"
+M.DEFAULT_LIST = DEFAULT_LIST
 
 ---@alias HarpoonListItem {value: any, context: any}
 ---@alias HarpoonListFileItem {value: string, context: {row: number, col: number}}
@@ -15,7 +18,7 @@ local M = {}
 ---@field display? (fun(list_item: HarpoonListItem): string)
 ---@field select? (fun(list_item: HarpoonListItem, options: any?): nil)
 ---@field equals? (fun(list_line_a: HarpoonListItem, list_line_b: HarpoonListItem): boolean)
----@field add? fun(item: any?): HarpoonListItem
+---@field add? fun(config: HarpoonPartialConfigItem, item: any?): HarpoonListItem
 ---@field BufLeave? fun(evt: any, list: HarpoonList): nil
 ---@field VimLeavePre? fun(evt: any, list: HarpoonList): nil
 ---@field get_root_dir? fun(): string
@@ -123,9 +126,10 @@ function M.get_default_config()
                 return vim.loop.cwd()
             end,
 
-            ---@param name any
+            ---@param config HarpoonPartialConfigItem
+            ---@param name? any
             ---@return HarpoonListItem
-            add = function(name)
+            add = function(config, name)
                 name = name
                     -- TODO: should we do path normalization???
                     -- i know i have seen sometimes it becoming an absolute
@@ -135,7 +139,8 @@ function M.get_default_config()
                     or normalize_path(
                         vim.api.nvim_buf_get_name(
                             vim.api.nvim_get_current_buf()
-                        )
+                        ),
+                        config.get_root_dir()
                     )
 
                 local bufnr = vim.fn.bufnr(name, false)

lua/harpoon/init.lua

@@ -5,14 +5,6 @@ local List = require("harpoon.list")
 local Listeners = require("harpoon.listeners")
 local HarpoonGroup = require("harpoon.autocmd")
 
--- setup
--- read from a config file
---
-
--- TODO: rename lists into something better...
-
-local DEFAULT_LIST = "__harpoon_files"
-
 ---@class Harpoon
 ---@field config HarpoonConfig
 ---@field ui HarpoonUI
@@ -75,7 +67,7 @@ end
 ---@param name string?
 ---@return HarpoonList
 function Harpoon:list(name)
-    name = name or DEFAULT_LIST
+    name = name or Config.DEFAULT_LIST
 
     local key = self.config.settings.key()
     local lists = self.lists[key]
@@ -119,6 +111,10 @@ end
 function Harpoon:sync()
     local key = self.config.settings.key()
     self:_for_each_list(function(list, _, list_name)
+        if list.encode == false then
+            return
+        end
+
         local encoded = list:encode()
         self.data:update(key, list_name, encoded)
     end)

lua/harpoon/list.lua

@@ -48,7 +48,7 @@ end
 
 ---@return HarpoonList
 function HarpoonList:append(item)
-    item = item or self.config.add()
+    item = item or self.config.add(self.config)
 
     local index = index_of(self.items, item, self.config)
     if index == -1 then
@@ -64,7 +64,7 @@ end
 
 ---@return HarpoonList
 function HarpoonList:prepend(item)
-    item = item or self.config.add()
+    item = item or self.config.add(self.config)
     local index = index_of(self.items, item, self.config)
     if index == -1 then
         Listeners.listeners:emit(
@@ -139,7 +139,7 @@ function HarpoonList:resolve_displayed(displayed)
                 Listeners.event_names.ADD,
                 { list = self, item = v, idx = i }
             )
-            new_list[i] = self.config.add(v)
+            new_list[i] = self.config.add(self.config, v)
         else
             local index_in_new_list =
                 index_of(new_list, self.items[index], self.config)