diff --git a/doc/harpoonline.txt b/doc/harpoonline.txt index 6bf9e48..53bc945 100644 --- a/doc/harpoonline.txt +++ b/doc/harpoonline.txt @@ -1,4 +1,4 @@ -*harpoonline.txt* For Neovim >= 0.9.0 Last change: 2024 March 20 +*harpoonline.txt* For Neovim >= 0.9.0 Last change: 2024 March 21 ============================================================================== Table of Contents *harpoonline-table-of-contents* @@ -34,9 +34,9 @@ TOC *harpoonline-harpoonline-toc* - |harpoonline-using-mini.deps-and-mini.statusline| - |harpoonline-configuration| - |harpoonline-formatters| - - |harpoonline-the-"short"-builtin| - |harpoonline-the-"extended"-builtin| - - |harpoonline-modify-a-builtin| + - |harpoonline-the-"short"-builtin| + - |harpoonline-customize-a-builtin| - |harpoonline-use-a-custom-formatter| - |harpoonline-harpoon-lists| - |harpoonline-recipes| @@ -96,7 +96,7 @@ USING LAZY.NVIM AND LUALINE ~ "nvim-lualine/lualine.nvim", dependencies = { "abeldekat/harpoonline", version = "*" }, config = function() - local Harpoonline = require("harpoonline").setup() -- using default config + local Harpoonline = require("harpoonline").setup() -- using defaults local lualine_c = { Harpoonline.format, "filename" } require("lualine").setup({ sections = { lualine_c = lualine_c } }) end, @@ -159,18 +159,18 @@ The following configuration is implied when calling `setup` without arguments: ---@class HarpoonLineConfig Harpoonline.config = { ---@type string|nil - icon = '󰀱', + icon = '󰀱', -- Disable with empty string - -- Harpoon:list() retrieves the default list: The name of the list is nil. - -- The name to display can be configured by using default_list_name + -- Harpoon:list() retrieves the default list: The name of that list is nil. + -- default_list_name: Configures the display name for the default list. ---@type string default_list_name = '', ---@type string - formatter = 'extended', -- use a builtin formatter + formatter = 'extended', -- short -- use a builtin formatter ---@type fun():string|nil - custom_formatter = nil, -- use this formatter when supplied + custom_formatter = nil, -- use this formatter when configured ---@type fun()|nil on_update = nil, -- optional action to perform after update } @@ -187,63 +187,83 @@ Scenario’s: - B: 3 marks, the current buffer is harpooned on mark 2 -THE “SHORT” BUILTIN +THE “EXTENDED” BUILTIN + +This is the default formatter. >lua - Harpoonline.config = { - formatter = 'short', + ---@class HarpoonlineBuiltinOptionsExtended + H.builtin_options_extended = { + + -- An indicator corresponds to a position in the harpoon list + indicators = { '1', '2', '3', '4' }, + active_indicators = { '[1]', '[2]', '[3]', '[4]' }, + separator = ' ', -- how to separate the indicators + + -- 1 More indicators than items in the harpoon list: + empty_slot = '·', -- a middledot. Disable with empty string + + -- 2 Less indicators than items in the harpoon list + more_marks_indicator = '…', -- a horizontal elipsis. Disable with empty string + more_marks_active_indicator = '[…]', -- Disable with empty string } < -Output A: :anchor: `[3]` - -Output B: :anchor: `[2|3]` +Output A: :anchor: `1 2 3 ·` +Output B: :anchor: `1 [2] 3 ·` -THE “EXTENDED” BUILTIN -The default +THE “SHORT” BUILTIN -Output A: :anchor: `1 2 3 -` +Add to the config: `{ formatter = 'short'}` -Output B: :anchor: `1 [2] 3 -` +>lua + ---@class HarpoonlineBuiltinOptionsShort + H.builtin_options_short = { + inner_separator = '|', + } +< +Output A: :anchor: `[3]` -MODIFY A BUILTIN +Output B: :anchor: `[2|3]` -Builtin formatters: `Harpoonline.formatters` The corresponding formatter -specific options: `Harpoonline.formatter_opts` -Modify "extended": +CUSTOMIZE A BUILTIN >lua local Harpoonline = require("harpoonline") + ---@type HarpoonlineBuiltinOptionsExtended + local opts = { + indicators = { "j", "k", "l", "h" }, + active_indicators = { "", "", "", "" }, + empty_slot = "", -- disabled + } Harpoonline.setup({ - custom_formatter = Harpoonline.gen_override("extended", { - indicators = { "j", "k", "l", "h" }, - active_indicators = { "J", "K", "L", "H" }, - }), + custom_formatter = Harpoonline.gen_override("extended", opts), }) < -Output A: :anchor: `j k l -` +Output A: :anchor: `j k l` -Output B: :anchor: `j K l -` +Output B: :anchor: `j l` USE A CUSTOM FORMATTER -The following data is kept up-to-date internally to be consumed by formatters: +The following data is kept up-to-date internally, to be processed by +formatters: >lua ---@class HarpoonLineData H.data = { --- @type string|nil - list_name = nil, -- the name of the list in use + list_name = nil, -- the name of the current list --- @type number - list_length = 0, -- the length of the list + list_length = 0, -- the length of the current list --- @type number|nil - buffer_idx = nil, -- the harpoon index of the current buffer if harpooned + buffer_idx = nil, -- the mark of the current buffer if harpooned } < @@ -253,15 +273,16 @@ Example: local Harpoonline = require("harpoonline") Harpoonline.setup({ custom_formatter = Harpoonline.gen_formatter( - function(data, _) - return string.format( + ---@param data HarpoonLineData + ---@return string + function(data) + return string.format( -- very short, without the length of the harpoon list "%s%s%s", "➡️ ", data.list_name and string.format("%s ", data.list_name) or "", data.buffer_idx and string.format("%d", data.buffer_idx) or "-" ) - end, - {} + end ), }) < @@ -276,18 +297,20 @@ example recipe for NvChad. HARPOON LISTS *harpoonline-harpoonline-harpoon-lists* -This plugin provides support for working with multiple harpoon lists. +This plugin supports working with multiple harpoon lists. The list in use when +Neovim is started is assumed to be the default list -The list in use when Neovim is started is assumed to be the default list +**Important**: The plugin needs to be notified when switching to another list using its custom `HarpoonSwitchedList` event: >lua - local list_name = nil -- starts with the default + -- Starts with the default. Use this variable in harpoon:list(list_name) + local list_name = nil vim.keymap.set("n", "J", function() - -- toggle between the current list and list "custom" + -- toggle between the default list and list "custom" list_name = list_name ~= "custom" and "custom" or nil vim.api.nvim_exec_autocmds("User", { pattern = "HarpoonSwitchedList", modeline = false, data = list_name })