mini.nvim/lua/mini/bracketed.lua at main · isti115/mini.nvim

Repository navigation

--- *mini.bracketed* Go forward/backward with square brackets
--- *MiniBracketed*
--- MIT License Copyright (c) 2023 Evgeni Chasnovski
--- ==============================================================================
--- Features:
--- - Configurable Lua functions to go forward/backward to a certain target.
---   Each function can be customized with:
---     - Direction. One of "forward", "backward", "first" (forward starting
---       from first one), "last" (backward starting from last one).
---     - Number of times to go.
---     - Whether to wrap on edges (going forward on last one goes to first).
---     - Some other target specific options.
--- - Mappings using square brackets. They are created using configurable
---   target suffix and can be selectively disabled.
---   Each mapping supports |[count]|. Mappings are created in Normal mode; for
---   targets which move cursor in current buffer also Visual and
---   Operator-pending (with dot-repeat) modes are supported.
---   Using `lower-suffix` and `upper-suffix` (lower and upper case suffix) for
---   a single target the following mappings are created:
---     - `[` + `upper-suffix` : go first.
---     - `[` + `lower-suffix` : go backward.
---     - `]` + `lower-suffix` : go forward.
---     - `]` + `upper-suffix` : go last.
--- - Supported targets (for more information see help for corresponding Lua
---   function):
---   `Target`                           `Mappings`         `Lua function`
---   Buffer.......................... `[B` `[b` `]b` `]B` .... |MiniBracketed.buffer()|
---   Comment block................... `[C` `[c` `]c` `]C` .... |MiniBracketed.comment()|
---   Conflict marker................. `[X` `[x` `]x` `]X` .... |MiniBracketed.conflict()|
---   Diagnostic...................... `[D` `[d` `]d` `]D` .... |MiniBracketed.diagnostic()|
---   File on disk.................... `[F` `[f` `]f` `]F` .... |MiniBracketed.file()|
---   Indent change................... `[I` `[i` `]i` `]I` .... |MiniBracketed.indent()|
---   Jump from |jumplist|
---   inside current buffer........... `[J` `[j` `]j` `]J` .... |MiniBracketed.jump()|
---   Location from |location-list|..... `[L` `[l` `]l` `]L` .... |MiniBracketed.location()|
---   Old files....................... `[O` `[o` `]o` `]O` .... |MiniBracketed.oldfile()|
---   Quickfix entry from |Quickfix|.... `[Q` `[q` `]q` `]Q` .... |MiniBracketed.quickfix()|
---   Tree-sitter node and parents.... `[T` `[t` `]t` `]T` .... |MiniBracketed.treesitter()|
---   Undo states from specially
---   tracked linear history.......... `[U` `[u` `]u` `]U` .... |MiniBracketed.undo()|
---   Window in current tab........... `[W` `[w` `]w` `]W` .... |MiniBracketed.window()|
---   Yank selection replacing
---   latest put region............... `[Y` `[y` `]y` `]Y` .... |MiniBracketed.yank()|
--- - The `undo` target remaps |u| and |<C-R>| keys to register undo state
---   after undo and redo respectively. If this conflicts with your setup,
---   either disable `undo` target or make your remaps after calling
---   |MiniBracketed.setup()|. To use `undo` target, remap your undo/redo keys
---   to call |MiniBracketed.register_undo_state()| after the action.
--- # Setup ~
--- This module needs a setup with `require('mini.bracketed').setup({})` (replace
--- `{}` with your `config` table). It will create global Lua table `MiniBracketed`
--- which you can use for scripting or manually (with `:lua MiniBracketed.*`).
--- See |MiniBracketed.config| for available config settings.
--- You can override runtime config settings (like target options) locally
--- to buffer inside `vim.b.minibracketed_config` which should have same structure
--- as `MiniBracketed.config`. See |mini.nvim-buffer-local-config| for more details.
--- # Comparisons ~
--- - 'tpope/vim-unimpaired':
---     - Supports buffer, conflict, file, location, and quickfix targets mostly
---       via built-in commands (like |:bprevious|, etc.) without configuration.
---     - Supports files from argument list and tags. This module does not.
---     - Doesn't support most other this module's targets (comment, indent, ...).
--- - 'mini.indentscope':
---     - Target |MiniBracketed.indent()| target can go to "first" and "last"
---       indent change. It also can go not only to line with smaller indent,
---       but also bigger or different one.
---     - Mappings from 'mini.indentscope' have more flexibility in computation of
---       indent scope, like how to treat empty lines near border or whether to
---       compute indent at cursor.
--- # Disabling ~
--- To disable, set `vim.g.minibracketed_disable` (globally) or
--- `vim.b.minibracketed_disable` (for a buffer) to `true`. Considering high
--- number of different scenarios and customization intentions, writing exact
--- rules for disabling module's functionality is left to user. See
--- |mini.nvim-disabling-recipes| for common recipes.
---@diagnostic disable:luadoc-miss-type-name
---@alias __bracketed_direction string One of "first", "backward", "forward", "last".
---@alias __bracketed_add_to_jumplist - <add_to_jumplist> (`boolean`) - Whether to add current position to jumplist.
---     Default: `false`.
---@alias __bracketed_opts table|nil Options. A table with fields:
---   - <n_times> `(number)` - Number of times to advance. Default: |v:count1|.
---   - <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.
---@diagnostic disable:undefined-field
-- Module definition ==========================================================
local MiniBracketed = {}
local H = {}
--- Module setup
---@param config table|nil Module config table. See |MiniBracketed.config|.
---@usage >lua
---   require('mini.bracketed').setup() -- use default config
---   -- OR
---   require('mini.bracketed').setup({}) -- replace {} with your config table
MiniBracketed.setup = function(config)
  -- Export module
  _G.MiniBracketed = MiniBracketed
  -- Setup config
  config = H.setup_config(config)
  -- Apply config
  H.apply_config(config)
  -- Define behavior
  H.create_autocommands()
--stylua: ignore
--- Module config
--- Default values:
---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
---@text Options ~
--- Each entry configures target with the same name and can have data configuring
--- mapping suffix and target options.
--- Example of configuration: >lua
---   require('mini.bracketed').setup({
---     -- Map [N, [n, ]n, ]N for conflict marker like in 'tpope/vim-unimpaired'
---     conflict = { suffix = 'n' },
---     -- Make diagnostic advance only by errors
---     diagnostic = { options = { severity = vim.diagnostic.severity.ERROR } },
---     -- Disable creation of mappings for `indent` target (for example,
---     -- in favor of ones from |mini.indentscope|)
---     indent = { suffix = '' },
---     -- Disable mappings for `window` target in favor of custom ones
---     window = { suffix = '' },
---   -- Create custom `window` mappings
---   local map = vim.keymap.set
---   map('n', '<Leader>wH', "<Cmd>lua MiniBracketed.window('first')<CR>")
---   map('n', '<Leader>wh', "<Cmd>lua MiniBracketed.window('backward')<CR>")
---   map('n', '<Leader>wl', "<Cmd>lua MiniBracketed.window('forward')<CR>")
---   map('n', '<Leader>wL', "<Cmd>lua MiniBracketed.window('last')<CR>")
--- ## Suffix ~
--- The `suffix` key is used to create target mappings.
--- Supply empty string to disable mapping creation for that particular target.
--- To create a completely different mapping (like with |<Leader>|) use target
--- function manually.
--- Using `lower-suffix` and `upper-suffix` (lower and upper case suffix) for
--- a single target the following mappings are created:
--- - `[` + `upper-suffix` : go first.
--- - `[` + `lower-suffix` : go backward.
--- - `]` + `lower-suffix` : go forward.
--- - `]` + `upper-suffix` : go last.
--- When supplied with a non-letter, only forward/backward mappings are created.
--- ## Options ~
--- The `options` key is directly forwarded as `opts` to corresponding Lua function.
MiniBracketed.config = {
  -- First-level elements are tables describing behavior of a target:
  -- - <suffix> - single character suffix. Used after `[` / `]` in mappings.
  --   For example, with `b` creates `[B`, `[b`, `]b`, `]B` mappings.
  --   Supply empty string `''` to not create mappings.
  -- - <options> - table overriding target options.
  -- See `:h MiniBracketed.config` for more info.
  buffer     = { suffix = 'b', options = {} },
  comment    = { suffix = 'c', options = {} },
  conflict   = { suffix = 'x', options = {} },
  diagnostic = { suffix = 'd', options = {} },
  file       = { suffix = 'f', options = {} },
  indent     = { suffix = 'i', options = {} },
  jump       = { suffix = 'j', options = {} },
  location   = { suffix = 'l', options = {} },
  oldfile    = { suffix = 'o', options = {} },
  quickfix   = { suffix = 'q', options = {} },
  treesitter = { suffix = 't', options = {} },
  undo       = { suffix = 'u', options = {} },
  window     = { suffix = 'w', options = {} },
  yank       = { suffix = 'y', options = {} },
--minidoc_afterlines_end
--- Listed buffer
--- Go to next/previous listed buffer. Order by their number (see |bufnr()|).
--- Direction "forward" increases number, "backward" - decreases.
---@param direction __bracketed_direction
---@param opts __bracketed_opts
MiniBracketed.buffer = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'buffer')
    vim.tbl_deep_extend('force', { n_times = vim.v.count1, wrap = true }, H.get_config().buffer.options, opts or {})
  -- Define iterator that traverses all valid listed buffers
  -- (should be same as `:bnext` / `:bprev`)
  local buf_list = vim.api.nvim_list_bufs()
  local is_listed = function(buf_id) return vim.api.nvim_buf_is_valid(buf_id) and vim.bo[buf_id].buflisted end
  local iterator = {}
  iterator.next = function(buf_id)
    for id = buf_id + 1, buf_list[#buf_list] do
      if is_listed(id) then return id end
  iterator.prev = function(buf_id)
    for id = buf_id - 1, buf_list[1], -1 do
      if is_listed(id) then return id end
  iterator.state = vim.api.nvim_get_current_buf()
  iterator.start_edge = buf_list[1] - 1
  iterator.end_edge = buf_list[#buf_list] + 1
  -- Iterate
  local res_buf_id = MiniBracketed.advance(iterator, direction, opts)
  if res_buf_id == iterator.state then return end
  vim.api.nvim_set_current_buf(res_buf_id)
--- Comment block
--- Go to next/previous comment block. Only linewise comments using
--- 'commentsring' are recognized.
--- Direction "forward" increases line number, "backward" - decreases.
---@param direction __bracketed_direction
---@param opts __bracketed_opts
---   __bracketed_add_to_jumplist
---   - <block_side> `(string)` - which side of comment block to use. One of
---     "near" (default; use nearest side), "start" (use first line), "end"
---     (use last line), "both" (use both first and last lines).
MiniBracketed.comment = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'comment')
  opts = vim.tbl_deep_extend(
    'force',
    { add_to_jumplist = false, block_side = 'near', n_times = vim.v.count1, wrap = true },
    H.get_config().comment.options,
    opts or {}
  -- Compute loop data to traverse target commented lines in current buffer
  local is_commented = H.make_comment_checker()
  if is_commented == nil then return end
  local predicate = ({
    near = function(_, cur, _, recent) return cur and not recent end,
    start = function(above, cur, _, _) return cur and not above end,
    ['end'] = function(_, cur, below, _) return cur and not below end,
    both = function(above, cur, below, _) return cur and not (above and below) end,
  })[opts.block_side]
  if predicate == nil then return end
  -- Define iterator
  local iterator = {}
  local n_lines = vim.api.nvim_buf_line_count(0)
  iterator.next = function(line_num)
    local above, cur = is_commented(line_num), is_commented(line_num + 1)
    for lnum = line_num + 1, n_lines do
      local below = is_commented(lnum + 1)
      if predicate(above, cur, below, above) then return lnum end
      above, cur = cur, below
  iterator.prev = function(line_num)
    local cur, below = is_commented(line_num - 1), is_commented(line_num)
    for lnum = line_num - 1, 1, -1 do
      local above = is_commented(lnum - 1)
      if predicate(above, cur, below, below) then return lnum end
      below, cur = cur, above
  iterator.state = vim.fn.line('.')
  iterator.start_edge = 0
  iterator.end_edge = n_lines + 1
  -- Iterate
  local res_line_num = MiniBracketed.advance(iterator, direction, opts)
  local is_outside = res_line_num <= 0 or n_lines < res_line_num
  if res_line_num == nil or res_line_num == iterator.state or is_outside then return end
  -- Possibly add current position to jumplist
  if opts.add_to_jumplist then H.add_to_jumplist() end
  -- Apply. Open just enough folds and put cursor on first non-blank.
  H.set_cursor(res_line_num, 0)
  vim.cmd('normal! zv^')
--- Git conflict marker
--- Go to next/previous lines containing Git conflict marker. That is, if it
--- starts with "<<<<<<< ", ">>>>>>> ", or is "=======".
--- Direction "forward" increases line number, "backward" - decreases.
--- - Using this target in Operator-pending mode allows the following approach
---   at resolving merge conflicts:
---     - Place cursor on `=======` line.
---     - Execute one of these: `d]x[xdd` (choose upper part) or
---       `d[x]xdd` (choose lower part).
---@param direction __bracketed_direction
---@param opts __bracketed_opts
---   __bracketed_add_to_jumplist
MiniBracketed.conflict = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'conflict')
  opts = vim.tbl_deep_extend(
    'force',
    { add_to_jumplist = false, n_times = vim.v.count1, wrap = true },
    H.get_config().conflict.options,
    opts or {}
  -- Define iterator that traverses all conflict markers in current buffer
  local n_lines = vim.api.nvim_buf_line_count(0)
  local iterator = {}
  iterator.next = function(line_num)
    for lnum = line_num + 1, n_lines do
      if H.is_conflict_mark(lnum) then return lnum end
  iterator.prev = function(line_num)
    for lnum = line_num - 1, 1, -1 do
      if H.is_conflict_mark(lnum) then return lnum end
  iterator.state = vim.fn.line('.')
  iterator.start_edge = 0
  iterator.end_edge = n_lines + 1
  -- Iterate
  local res_line_num = MiniBracketed.advance(iterator, direction, opts)
  local is_outside = res_line_num <= 0 or n_lines < res_line_num
  if res_line_num == nil or res_line_num == iterator.state or is_outside then return end
  -- Possibly add current position to jumplist
  if opts.add_to_jumplist then H.add_to_jumplist() end
  -- Apply. Open just enough folds and put cursor on first non-blank.
  H.set_cursor(res_line_num, 0)
  vim.cmd('normal! zv^')
--- Diagnostic
--- Go to next/previous diagnostic. This is mostly similar to
--- |vim.diagnostic.goto_next()| and |vim.diagnostic.goto_prev()| for
--- current buffer which supports |[count]| and functionality to go to
--- first/last diagnostic entry.
--- Direction "forward" increases line number, "backward" - decreases.
--- - Using `severity` option, this target can be used in mappings like "go to
---   next/previous error" (), etc. Using code similar to this: >lua
---   local severity_error = vim.diagnostic.severity.ERROR
---   -- Use these inside custom mappings
---   MiniBracketed.diagnostic('forward', { severity = severity_error })
---   MiniBracketed.diagnostic('backward', { severity = severity_error })
---@param direction __bracketed_direction
---@param opts __bracketed_opts
---   - <float> `(boolean|table)` - control floating window after movement.
---     For available values see |vim.diagnostic.goto_next()|.
---   - <severity> `(string|table)` - which severity to use.
---     For available values see |diagnostic-severity|.
MiniBracketed.diagnostic = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'diagnostic')
  opts = vim.tbl_deep_extend(
    'force',
    { float = nil, n_times = vim.v.count1, severity = nil, wrap = true },
    H.get_config().diagnostic.options,
    opts or {}
  -- Define iterator that traverses all diagnostic entries in current buffer
  local is_position = function(x) return type(x) == 'table' and #x == 2 end
  local diag_pos_to_cursor_pos = function(pos) return { pos[1] + 1, pos[2] } end
  local iterator = {}
  iterator.next = function(position)
    local goto_opts = { cursor_position = diag_pos_to_cursor_pos(position), severity = opts.severity, wrap = false }
    local new_pos = vim.diagnostic.get_next_pos(goto_opts)
    if not is_position(new_pos) then return end
    return new_pos
  iterator.prev = function(position)
    local goto_opts = { cursor_position = diag_pos_to_cursor_pos(position), severity = opts.severity, wrap = false }
    local new_pos = vim.diagnostic.get_prev_pos(goto_opts)
    if not is_position(new_pos) then return end
    return new_pos
  -- - Define states with zero-based indexing as used in `vim.diagnostic`.
  -- - Go outside of proper buffer position for `start_edge` and `end_edge` to
  --   correctly spot diagnostic entry right and start and end of buffer.
  local cursor_pos = vim.api.nvim_win_get_cursor(0)
  iterator.state = { cursor_pos[1] - 1, cursor_pos[2] }
  iterator.start_edge = { 0, -1 }
  local last_line = vim.api.nvim_buf_line_count(0)
  iterator.end_edge = { last_line - 1, vim.fn.col({ last_line, '$' }) - 1 }
  -- Iterate
  local res_pos = MiniBracketed.advance(iterator, direction, opts)
  if res_pos == nil or res_pos == iterator.state then return end
  -- Apply. Use `goto_next()` with offsetted cursor position to make it respect
  -- `vim.diagnostic.config()`.
  vim.diagnostic.goto_next({
    cursor_position = { res_pos[1] + 1, res_pos[2] - 1 },
    float = opts.float,
    severity = opts.severity,
--- File on disk
--- Go to next/previous file on disk alphabetically. Files are taken from
--- directory of file in current buffer (or current working directory if buffer
--- doesn't contain a readable file). Only first-level files are used, i.e. it
--- doesn't go inside subdirectories.
--- Direction "forward" goes forward alphabetically, "backward" - backward.
---@param direction __bracketed_direction
---@param opts __bracketed_opts
MiniBracketed.file = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'file')
  opts = vim.tbl_deep_extend('force', { n_times = vim.v.count1, wrap = true }, H.get_config().file.options, opts or {})
  -- Get file data
  local file_data = H.get_file_data()
  if file_data == nil then return end
  local file_basenames, directory = file_data.file_basenames, file_data.directory
  -- Define iterator that traverses all found files
  local iterator = {}
  local n_files = #file_basenames
  iterator.next = function(ind)
    -- Allow advance in untrackable current buffer
    if ind == nil then return 1 end
    if n_files <= ind then return end
    return ind + 1
  iterator.prev = function(ind)
    -- Allow advance in untrackable current buffer
    if ind == nil then return n_files end
    if ind <= 1 then return end
    return ind - 1
  -- - Find filename array index of current buffer
  local cur_basename = vim.fn.fnamemodify(vim.api.nvim_buf_get_name(0), ':t')
  local cur_basename_ind
  if cur_basename ~= '' then
    for i, f in ipairs(file_basenames) do
      if cur_basename == f then
        cur_basename_ind = i
        break
  iterator.state = cur_basename_ind
  iterator.start_edge = 0
  iterator.end_edge = n_files + 1
  -- Iterate
  local res_ind = MiniBracketed.advance(iterator, direction, opts)
  if res_ind == iterator.state then return end
  -- Apply. Open target_path.
  local path_sep = package.config:sub(1, 1)
  local target_path = directory .. path_sep .. file_basenames[res_ind]
  vim.cmd('edit ' .. target_path)
--- Indent change
--- Go to next/previous line with different indent (see |indent()|).
--- Can be used to go to lines with smaller, bigger, or different indent.
--- - Directions "first" and "last" work differently from most other targets
---   for performance reasons. They are essentially "backward" and "forward"
---   with very big `n_times` option.
--- - For similar reasons, `wrap` is not supported.
--- - Blank line inherit indent from near non-blank line in direction of movement.
--- Direction "forward" increases line number, "backward" - decreases.
---@param direction __bracketed_direction
---@param opts table|nil Options. A table with fields:
---   - <n_times> `(number)` - Number of times to advance. Default: |v:count1|.
---   __bracketed_add_to_jumplist
---   - <change_type> `(string)` - which type of indent change to use.
---     One of "less" (default; smaller indent), "more" (bigger indent),
---     "diff" (different indent).
MiniBracketed.indent = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'indent')
  opts = vim.tbl_deep_extend(
    'force',
    { add_to_jumplist = false, change_type = 'less', n_times = vim.v.count1 },
    H.get_config().indent.options,
    opts or {}
  opts.wrap = false
  if direction == 'first' then
    -- For some reason using `n_times = math.huge` leads to infinite loop
    direction, opts.n_times = 'backward', vim.api.nvim_buf_line_count(0) + 1
  if direction == 'last' then
    direction, opts.n_times = 'forward', vim.api.nvim_buf_line_count(0) + 1
  -- Compute loop data to traverse target commented lines in current buffer
  local predicate = ({
    less = function(new, cur) return new < cur or cur == 0 end,
    more = function(new, cur) return new > cur end,
    diff = function(new, cur) return new ~= cur end,
  })[opts.change_type]
  if predicate == nil then return end
  -- Define iterator
  local iterator = {}
  iterator.next = function(cur_lnum)
    -- Correctly process empty current line
    cur_lnum = vim.fn.nextnonblank(cur_lnum)
    local cur_indent = vim.fn.indent(cur_lnum)
    local new_lnum, new_indent = cur_lnum, cur_indent
    -- Check with `new_lnum > 0` because `nextnonblank()` returns -1 if line is
    -- outside of line range
    while new_lnum > 0 do
      new_indent = vim.fn.indent(new_lnum)
      if predicate(new_indent, cur_indent) then return new_lnum end
      new_lnum = vim.fn.nextnonblank(new_lnum + 1)
  iterator.prev = function(cur_lnum)
    cur_lnum = vim.fn.prevnonblank(cur_lnum)
    local cur_indent = vim.fn.indent(cur_lnum)
    local new_lnum, new_indent = cur_lnum, cur_indent
    while new_lnum > 0 do
      new_indent = vim.fn.indent(new_lnum)
      if predicate(new_indent, cur_indent) then return new_lnum end
      new_lnum = vim.fn.prevnonblank(new_lnum - 1)
  -- - Don't add first and last states as there is no wrapping around edges
  iterator.state = vim.fn.line('.')
  -- Iterate
  local res_line_num = MiniBracketed.advance(iterator, direction, opts)
  if res_line_num == nil or res_line_num == iterator.state then return end
  -- Possibly add current position to jumplist
  if opts.add_to_jumplist then H.add_to_jumplist() end
  -- Apply. Open just enough folds and put cursor on first non-blank.
  H.set_cursor(res_line_num, 0)
  vim.cmd('normal! zv^')
--- Jump inside current buffer
--- Go to next/previous jump from |jumplist| which is inside current buffer.
--- - There are no Visual mode mappings due to implementation problems.
--- Direction "forward" increases jump number, "backward" - decreases.
---@param direction __bracketed_direction
---@param opts __bracketed_opts
MiniBracketed.jump = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'jump')
  opts = vim.tbl_deep_extend('force', { n_times = vim.v.count1, wrap = true }, H.get_config().jump.options, opts or {})
  -- Define iterator that traverses all jumplist entries inside current buffer
  local cur_buf_id = vim.api.nvim_get_current_buf()
  local jump_list, cur_jump_num = unpack(vim.fn.getjumplist())
  local n_list = #jump_list
  if n_list == 0 then return end
  -- - Correct for zero-based indexing
  cur_jump_num = cur_jump_num + 1
  local iterator = {}
  local is_jump_num_from_current_buffer = function(jump_num)
    local jump_entry = jump_list[jump_num]
    if jump_entry == nil then return end
    return jump_entry.bufnr == cur_buf_id
  iterator.next = function(jump_num)
    for num = jump_num + 1, n_list do
      if is_jump_num_from_current_buffer(num) then return num end
  iterator.prev = function(jump_num)
    for num = jump_num - 1, 1, -1 do
      if is_jump_num_from_current_buffer(num) then return num end
  iterator.state = cur_jump_num
  iterator.start_edge = 0
  iterator.end_edge = n_list + 1
  -- Iterate
  local res_jump_num = MiniBracketed.advance(iterator, direction, opts)
  if res_jump_num == nil then return end
  -- Apply. Make jump. Allow jumping to current jump entry as it might be
  -- different from current cursor position.
  H.make_jump(jump_list, cur_jump_num, res_jump_num)
--- Location from location list
--- Go to next/previous location from |location-list|. This is similar to
--- |:lfirst|, |:lprevious|, |:lnext|, and |:llast| but with support of
--- wrapping around edges and |[count]| for "first"/"last" direction.
--- Direction "forward" increases location number, "backward" - decreases.
---@param direction __bracketed_direction
---@param opts __bracketed_opts
MiniBracketed.location = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'location')
    vim.tbl_deep_extend('force', { n_times = vim.v.count1, wrap = true }, H.get_config().location.options, opts or {})
  H.qf_loc_implementation('location', direction, opts)
--- Old files from previous and current sessions
--- Go to older/newer readable file either from previous session (see |v:oldfiles|)
--- or the current one (updated automatically after |MiniBracketed.setup()| call).
--- Direction "forward" goes to more recent files, "backward" - to older.
--- - In current session it tracks only normal buffers (see |'buftype'|) for
---   some readable file.
--- - No new file is tracked when advancing this target. Only after buffer
---   change is done not through this target (like with |MiniBracketed.buffer()|),
---   it updates recency of last advanced and new buffers.
---@param direction __bracketed_direction
---@param opts __bracketed_opts
MiniBracketed.oldfile = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'oldfile')
    vim.tbl_deep_extend('force', { n_times = vim.v.count1, wrap = true }, H.get_config().oldfile.options, opts or {})
  -- Define iterator that traverses all old files
  local cur_path = vim.api.nvim_buf_get_name(0)
  H.oldfile_normalize()
  local oldfile_arr = H.oldfile_get_array()
  local n_oldfiles = #oldfile_arr
  local iterator = {}
  iterator.next = function(ind)
    -- Allow advance in untrackable current buffer
    if ind == nil then return 1 end
    if n_oldfiles <= ind then return end
    return ind + 1
  iterator.prev = function(ind)
    -- Allow advance in untrackable current buffer
    if ind == nil then return n_oldfiles end
    if ind <= 1 then return end
    return ind - 1
  iterator.state = H.cache.oldfile.recency[cur_path]
  iterator.start_edge = 0
  iterator.end_edge = n_oldfiles + 1
  -- Iterate
  local res_arr_ind = MiniBracketed.advance(iterator, direction, opts)
  if res_arr_ind == nil or res_arr_ind == iterator.state then return end
  -- Apply. Edit file at path while marking it not for tracking.
  H.cache.oldfile.is_advancing = true
  vim.cmd('edit ' .. oldfile_arr[res_arr_ind])
--- Quickfix from quickfix list
--- Go to next/previous entry from |quickfix| list. This is similar to
--- |:cfirst|, |:cprevious|, |:cnext|, and |:clast| but with support of
--- wrapping around edges and |[count]| for "first"/"last" direction.
--- Direction "forward" increases location number, "backward" - decreases.
---@param direction __bracketed_direction
---@param opts __bracketed_opts
MiniBracketed.quickfix = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'quickfix')
    vim.tbl_deep_extend('force', { n_times = vim.v.count1, wrap = true }, H.get_config().quickfix.options, opts or {})
  H.qf_loc_implementation('quickfix', direction, opts)
--- Tree-sitter node
--- Go to end/start of current tree-sitter node and its parents (except root).
--- - Requires |get_node_at_pos()| from |lua-treesitter| (present in Neovim=0.8)
---   or |vim.treesitter.get_node()| (present in Neovim>=0.9) along with loaded
---   tree-sitter parser in current buffer.
--- - Directions "first" and "last" work differently from most other targets
---   for performance reasons. They are essentially "backward" and "forward"
---   with very big `n_times` option.
--- - For similar reasons, `wrap` is not supported.
--- Direction "forward" moves cursor forward to node's end, "backward" - backward
--- to node's start.
---@param direction __bracketed_direction
---@param opts table|nil Options. A table with fields:
---   - <n_times> `(number)` - Number of times to advance. Default: |v:count1|.
---   __bracketed_add_to_jumplist
MiniBracketed.treesitter = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'treesitter')
  opts = vim.tbl_deep_extend(
    'force',
    { add_to_jumplist = false, n_times = vim.v.count1 },
    H.get_config().treesitter.options,
    opts or {}
  opts.wrap = false
  if direction == 'first' then
    direction, opts.n_times = 'backward', math.huge
  if direction == 'last' then
    direction, opts.n_times = 'forward', math.huge
  -- Define iterator that traverses current node and its parents (except root)
  local is_bad_node = function(node) return node == nil or node:parent() == nil end
  local is_after = function(row_new, col_new, row_ref, col_ref)
    return row_ref < row_new or (row_ref == row_new and col_ref < col_new)
  local is_before = function(row_new, col_new, row_ref, col_ref) return is_after(row_ref, col_ref, row_new, col_new) end
  local iterator = {}
  -- Traverse node and parents until node's end is after current position
  iterator.next = function(node_pos)
    local node = node_pos.node
    if is_bad_node(node) then return nil end
    local init_row, init_col = node_pos.pos[1], node_pos.pos[2]
    local cur_row, cur_col, cur_node = init_row, init_col, node
      if is_bad_node(cur_node) then break end
      cur_row, cur_col = cur_node:end_()
      -- Correct for end-exclusiveness
      cur_col = cur_col - 1
      cur_node = cur_node:parent()
    until is_after(cur_row, cur_col, init_row, init_col)
    if not is_after(cur_row, cur_col, init_row, init_col) then return end
    return { node = cur_node, pos = { cur_row, cur_col } }
  -- Traverse node and parents until node's start is before current position
  iterator.prev = function(node_pos)
    local node = node_pos.node
    if is_bad_node(node) then return nil end
    local init_row, init_col = node_pos.pos[1], node_pos.pos[2]
    local cur_row, cur_col, cur_node = init_row, init_col, node
      if is_bad_node(cur_node) then break end
      cur_row, cur_col = cur_node:start()
      cur_node = cur_node:parent()
    until is_before(cur_row, cur_col, init_row, init_col)
    if not is_before(cur_row, cur_col, init_row, init_col) then return end
    return { node = cur_node, pos = { cur_row, cur_col } }
  local cur_pos = vim.api.nvim_win_get_cursor(0)
  local ok, node = pcall(H.get_treesitter_node, cur_pos[1] - 1, cur_pos[2])
  if not ok then
    H.error(
      'In `treesitter()` target can not find tree-sitter node under cursor.'
        .. ' Do you have tree-sitter enabled in current buffer?'
  iterator.state = { pos = { cur_pos[1] - 1, cur_pos[2] }, node = node }
  -- Iterate
  local res_node_pos = MiniBracketed.advance(iterator, direction, opts)
  if res_node_pos == nil then return end
  -- Possibly add current position to jumplist
  if opts.add_to_jumplist then H.add_to_jumplist() end
  H.set_cursor(res_node_pos.pos[1] + 1, res_node_pos.pos[2])
--- Undo along a tracked linear history
--- In a nutshell:
--- - Keys |u| and |<C-R>| (although remapped) can be used as usual, but every
---   their execution new state is recorded in this module's linear undo history.
--- - Advancing this target goes along linear undo history revealing undo states
---   **in order they actually appeared**.
--- - One big difference with built-in methods is that tracked linear history
---   can repeat undo states (not consecutively, though).
--- Neovim's default way of managing undo history is through branches (see
--- |undo-branches|). Basically it means that if you undo several changes and then
--- make new ones, it creates new undo branch while usually (see |'undolevels'|)
--- saving previous buffer states in another branch. While there are commands
--- to navigate by time of undo state creation (like |:earlier| and |:later|),
--- there is no intuitive way to cycle through them. Existing |g-| and |g+|
--- cycle through undo states **based on their creation time**, which often
--- gets confusing really guickly in extensively edited buffer.
--- This `undo()` target provides a way to cycle through linear undo history
--- **in order states actually appeared**. It does so by registering any new undo
--- states plus every time |MiniBracketed.register_undo_state()| is called. To have
--- more "out of the box" experience, |u| and |<C-R>| are remapped to call it after
--- they perform their undo/redo.
--- Example ~
--- To show more clearly the difference between advancing this target and using
--- built-in functionality, here is an example:
--- - Create undo history in a new buffer (|:new|):
---     - Enter `one two three` text.
---     - Delete first word with `daw` and undo the change with `u`.
---     - Delete second word with `daw` and undo the change with `u`.
---     - Delete third word with `daw` and undo the change with `u`.
--- - Now try one of the following (each one after performing previous steps in
---   separate new buffer):
---     - Press `u`. It goes back to empty buffer. Press `<C-R>` twice and it
---       goes to the latest change (`one two`). No way to get to other states
---       (like `two three` or `one three`) with these two keys.
---     - Press `g-`. It goes to an empty buffer. Press `g+` 4 times. It cycles
---       through all available undo states **in order they were created**.
---     - Finally, press `[u`. It goes back to `one two` - state which was
---       **previously visited** by the user. Another `[u` restores `one two three`.
---       Use `]U` to go to latest visited undo state.
---@param direction __bracketed_direction
---@param opts __bracketed_opts
MiniBracketed.undo = function(direction, opts)
  if H.is_disabled() then return end
  H.validate_direction(direction, { 'first', 'backward', 'forward', 'last' }, 'undo')
  opts = vim.tbl_deep_extend('force', { n_times = vim.v.count1, wrap = true }, H.get_config().undo.options, opts or {})
  -- Define iterator that traverses undo states in order they appeared
  local buf_id = vim.api.nvim_get_current_buf()
  H.undo_sync(buf_id, vim.fn.undotree())
  local iterator = {}
  local buf_history = H.cache.undo[buf_id]
  local n = #buf_history
  iterator.next = function(id)
    if id == nil or n <= id then return end
    return id + 1
  iterator.prev = function(id)
    if id == nil or id <= 1 then return end
    return id - 1
  iterator.state = buf_history.current_id
  iterator.start_edge = 0
  iterator.end_edge = n + 1
  -- Iterate
  local res_id = MiniBracketed.advance(iterator, direction, opts)
  if res_id == nil or res_id == iterator.state then return end

View remainder of file in raw view

FilesExpand file tree

bracketed.lua

Latest commit

History

bracketed.lua

File metadata and controls