From 7a356bfb1291e2b2872ff7ea676bc94aa5d660db Mon Sep 17 00:00:00 2001 From: mpaulson Date: Thu, 30 Nov 2023 20:42:31 -0700 Subject: [PATCH] feat: more extensive read me and `add` now comes with `config` ref --- README.md | 36 +++++++++++++++++++++++++++++++++++- lua/harpoon/config.lua | 17 +++++++++++------ lua/harpoon/init.lua | 14 +++++--------- lua/harpoon/list.lua | 6 +++--- 4 files changed, 54 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 7111271..719dcd4 100644 --- a/README.md +++ b/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", "a", function() harpoon:list():append() end) vim.keymap.set("n", "", 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) diff --git a/lua/harpoon/config.lua b/lua/harpoon/config.lua index bfb1d48..429443b 100644 --- a/lua/harpoon/config.lua +++ b/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) diff --git a/lua/harpoon/init.lua b/lua/harpoon/init.lua index 8811d51..a2e0718 100644 --- a/lua/harpoon/init.lua +++ b/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) diff --git a/lua/harpoon/list.lua b/lua/harpoon/list.lua index 6303025..77f92a3 100644 --- a/lua/harpoon/list.lua +++ b/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)