diff --git a/doc/harpoonline.txt b/doc/harpoonline.txt index e69de29..3d79cab 100644 --- a/doc/harpoonline.txt +++ b/doc/harpoonline.txt @@ -0,0 +1,336 @@ +*harpoonline.txt* For Neovim >= 0.9.0 Last change: 2024 March 18 + +============================================================================== +Table of Contents *harpoonline-table-of-contents* + +1. Harpoonline |harpoonline-harpoonline| + - TOC |harpoonline-harpoonline-toc| + - Demo |harpoonline-harpoonline-demo| + - Features |harpoonline-harpoonline-features| + - Requirements |harpoonline-harpoonline-requirements| + - Setup |harpoonline-harpoonline-setup| + - Configuration |harpoonline-harpoonline-configuration| + - Harpoon lists |harpoonline-harpoonline-harpoon-lists| + - Related plugins |harpoonline-harpoonline-related-plugins| + - Acknowledgements |harpoonline-harpoonline-acknowledgements| + +============================================================================== +1. Harpoonline *harpoonline-harpoonline* + +Create up-to-date harpoon2 + information to be used +in a status-line + + +TOC *harpoonline-harpoonline-toc* + +- |harpoonline-harpoonline| + - |harpoonline-demo| + - |harpoonline-features| + - |harpoonline-requirements| + - |harpoonline-setup| + - |harpoonline-using-lazy.nvim-and-lualine| + - |harpoonline-using-mini.deps-and-mini.statusline| + - |harpoonline-configuration| + - |harpoonline-formatters| + - |harpoonline-the-"short"-builtin| + - |harpoonline-the-"extended"-builtin| + - |harpoonline-modify-a-builtin| + - |harpoonline-use-a-custom-formatter| + - |harpoonline-harpoon-lists| + - |harpoonline-related-plugins| + - |harpoonline-acknowledgements| + + +DEMO *harpoonline-harpoonline-demo* + + + + + +FEATURES *harpoonline-harpoonline-features* + +- Supports multiple harpoon2 lists. +- Highly configurable: Use or modify default formatters or supply a custom formatter +- Decoupled from status-line: Can be used anywhere. +- Resilience: The formatter will return an empty string when harpoon is not present. +- Performance/efficiency: The data is cached and _only_ updated when needed. + +_Note_ + +Withoutcaching the info needed from harpoon must be retrieved whenever a +status-line updates. Typically, this happens often: + +- When navigating inside a buffer +- When editing text inside a buffer + + +REQUIREMENTS *harpoonline-harpoonline-requirements* + +- Latest stable `Neovim` version or nightly +- harpoon2 +- a statusline, for example: + - mini.statusline + - lualine + - heirline + - a custom implementation + + +SETUP *harpoonline-harpoonline-setup* + +**Important**don’t forget to call `require('harpoonline').setup()` to enable +the plugin. Without that call, the formatter will return an empty string. + + +USING LAZY.NVIM AND LUALINE ~ + +>lua + { + "nvim-lualine/lualine.nvim", + dependencies = "abeldekat/harpoonline", + config = function() + local Harpoonline = require("harpoonline").setup() -- using default config + local lualine_c = { Harpoonline.format, "filename" } + + require("lualine").setup({ + sections = { + lualine_c = lualine_c, + }, + }) + end, + } +< + + +USING MINI.DEPS AND MINI.STATUSLINE ~ + +>lua + local function config() + local MiniStatusline = require("mini.statusline") + local HarpoonLine= require("harpoonline") + + + local function isnt_normal_buffer() + return vim.bo.buftype ~= "" + end + local function harpoon_highlight() -- example using mini.hipatterns: + return Harpoonline.is_buffer_harpooned() and "MiniHipatternsHack" + or "MiniStatuslineFilename" ----> highlight when a buffer is harpooned + end + local function section_harpoon(args) + if MiniStatusline.is_truncated(args.trunc_width) + or isnt_normal_buffer() then + return "" + end + return Harpoonline.format() ----> produce the info + end + local function active() -- adding a harpoon section: + -- copy lines from mini.statusline, H.default_content_active: + -- ... + local harpoon_data = section_harpoon({ trunc_width = 75 }) + -- ... + + return MiniStatusline.combine_groups({ + -- copy lines from mini.statusline, H.default_content_active: + -- ... + { hl = H.harpoon_highlight(), strings = { harpoon_data } }, + -- ... + }) + end + + HarpoonLine.setup({ + on_update = function() + vim.wo.statusline = "%!v:lua.MiniStatusline.active()" + end + }) + MiniStatusline.setup({ + set_vim_settings = false, + content = { active = active }, + }) + end + + local MiniDeps = require("mini.deps") + local add, now = MiniDeps.add, MiniDeps.now + now(function() + add({ source = "echasnovski/mini.statusline", depends = {"abeldekat/harpoonline"}}) + config() + end +< + + +CONFIGURATION *harpoonline-harpoonline-configuration* + +The following configuration is implied when calling `setup` without arguments: + +>lua + ---@class HarpoonLineConfig + Harpoonline.config = { + ---@type string|nil + icon = '󰀱', + + -- As harpoon's default list is retrieved without a name, + -- default_list_name configures the name to be displayed + ---@type string + default_list_name = '', + + ---@type string + formatter = 'extended', -- use a builtin formatter + + ---@type fun():string|nil + custom_formatter = nil, -- use this formatter when supplied + ---@type fun()|nil + on_update = nil, -- optional action to perform after update + } +< + +_Note_The icon does not display properly in the browser… + + +FORMATTERS ~ + +Scenario’s: + +- A: 3 harpoons, the current buffer is not harpooned +- B: 3 harpoons, the current buffer is harpooned on mark 2 + + +THE “SHORT” BUILTIN + +>lua + Harpoonline.config = { + formatter = 'short', + } +< + +Output A: `[3]` + +Output B: `[2|3]` + + +THE “EXTENDED” BUILTIN + +The default + +Output A: `1 2 3 -` + +Output B: `1 [2] 3 -` + + +MODIFY A BUILTIN + +Builtin formatters: `Harpoonline.formatters` The corresponding formatter +specific options: `Harpoonline.formatter_opts` + +Modify "extended" + +>lua + local Harpoonline = require("harpoonline") + Harpoonline.setup({ + custom_formatter = Harpoonline.gen_override("extended", { + indicators = { "j", "k", "l", "h" }, + active_indicators = { "J", "K", "L", "H" }, + }), + }) +< + +OutputA: `j k l -` + +Output B: `j K l -` + + +USE A CUSTOM FORMATTER + +The following data is kept up-to-date internally to be consumed by formatters: + +>lua + ---@class HarpoonLineData + H.data = { + --- @type string|nil + list_name = nil, -- the name of the list in use + --- @type number + list_length = 0, -- the length of the list + --- @type number|nil + buffer_idx = nil, -- the harpoon index of the current buffer if harpooned + } +< + +Example: + +>lua + local Harpoonline = require("harpoonline") + Harpoonline.setup({ + custom_formatter = Harpoonline.gen_formatter( + function(data, _) + return string.format( + "%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, + {} + ), + }) +< + +Output A: `-` + +Output B: `2` + + +HARPOON LISTS *harpoonline-harpoonline-harpoon-lists* + +This plugin provides support for working with multiple harpoon lists. + +The list in use when Neovim is started is assumed to be the default list + +When switching to another list, the plugin needs to be notified using its +custom `HarpoonSwitchedList` event: + +>lua + local list_name = nil -- starts with the default + + vim.keymap.set("n", "J", function() + -- toggle between the current 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 }) + end, { desc = "Switch harpoon list", silent = true }) +< + +For a more complete example using two harpoon lists, see +ak.config.editor.harpoon + +in my Neovim configuration. + + +RELATED PLUGINS *harpoonline-harpoonline-related-plugins* + +harpoon-lualine + +- Dedicated to lualine +- A single, customizable formatting algorithm +- No caching +- No support for other lists than the default + +grapple.nvim + +- Has a similar dedicated lualine component as harpoon-lualine + + +ACKNOWLEDGEMENTS *harpoonline-harpoonline-acknowledgements* + +- @theprimeagenHarpoon is the most important part of my workflow. +- @echasnovskiThe structure of this plugin is heavily based on mini.nvim +- @letieuThe `extended` formatter is inspired by plugin harpoon-lualine + +============================================================================== +2. Links *harpoonline-links* + +1. *@theprimeagen*: +2. *@echasnovski*: +3. *@letieu*: + +Generated by panvimdoc + +vim:tw=78:ts=8:noet:ft=help:norl: