Breaking changes in v3

[abeldekat]

Breaking changes in v3

There are breaking changes if the config of the user:

• Uses a custom_formatter function
• Changed property empty_slots ( default empty )
• Contains { formatter = "extended" }
• Changed options in formatter_opts.extended

Changes in the custom formatter

Previously:

Harpoonline.setup({
  custom_formatter = Harpoonline.gen_formatter(
    ---@param data HarpoonLineData
    ---@return string
    function(data)
      -- create and return the line
    end
  ),
})

Now:

1. The gen_formatter wrapper has been removed
2. A second argument has been added: opts of type HarpoonlineConfig

Harpoonline.setup({
  ---@param data HarpoonlineData
  ---@param opts HarpoonLineConfig
  ---@return string
  custom_formatter = function(data, opts)
      -- create and return the line
  end,
})

HarpoonLineData is also changed

Changed the name into HarpoonlineData(lower l)

The data parameter for the custom_formatter used to contain:

---@class HarpoonLineData
H.data = {
  -- Harpoon's default list is in use when list_name = nil
  --- @type string|nil
  list_name = nil, -- the name of the current list
  --- @type number
  list_length = 0, -- the length of the current list
  --- @type number|nil
  buffer_idx = nil, -- the mark of the current buffer if harpooned
}

For more flexibility, the actual items in the harpoon list are now provided.
The length of the list can be inferred using #data.items

---@class HarpoonlineData
---@field list_name string|nil -- the name of the current list
---@field items HarpoonItem[] -- the items of the current list
---@field active_idx number|nil -- the harpoon index of the current buffer

See the examples in the readme.

Changes in the extended formatter

Previously, the default formatter to use when not overridden in the config:

---@type "extended" | "short"
formatter = 'extended', -- use a builtin formatter
-- Corresponding opts: formatter_opts.extended

The name of the default formatter is now just "default"

---@type "default" | "short"
formatter = 'default', -- use a builtin formatter
-- Corresponding opts: formatter_opts.default

Options

Empty slots

The config option for the extended formatter was already disabled:

formatter_opts = {
  extended = {
    -- 1 More indicators than items in the harpoon list:
    empty_slot = '', -- ' · ', -- middledot. Disable using empty string
  },
},

The option has been removed.

Indicators

Previously:

 -- formatter_opts.extended
 {
    -- An indicator corresponds to a position in the harpoon list
    -- Suggestion: Add an indicator for each configured "select" keybinding
    indicators = { ' 1 ', ' 2 ', ' 3 ', ' 4 ' },
    active_indicators = { '[1]', '[2]', '[3]', '[4]' },

    -- Less indicators than items in the harpoon list
    more_marks_indicator = ' … ', -- horizontal elipsis. Disable using empty string
    more_marks_active_indicator = '[…]', -- Disable using empty string
}

Now:

-- formatter_opts.default
{
  inactive = ' %s ', -- including spaces
  active = '[%s]',
  -- Number of slots to display:
  max_slots = 4, -- Suggestion: as many as there are "select" keybindings
  -- The number of items in the harpoon list exceeds max_slots:
  more = '…', -- horizontal elipsis. Disable using empty string
}

The output is the same.

Chapter "custom formatters" in the readme includes an extra example displaying letters.