mini.nvim/lua/mini/indentscope.lua at sync · vivi-et/mini.nvim

Repository navigation

-- MIT License Copyright (c) 2022 Evgeni Chasnovski
-- Documentation ==============================================================
--- Visualize and operate on indent scope
--- Indent scope (or just "scope") is a maximum set of consecutive lines which
--- contains certain reference line (cursor line by default) and every member
--- has indent not less than certain reference indent ("indent at cursor" by
--- default: minimum between cursor column and indent of cursor line).
--- Features:
--- - Visualize scope with animated vertical line. It is very fast and done
---   automatically in a non-blocking way (other operations can be performed,
---   like moving cursor). You can customize debounce delay and animation rule.
--- - Customization of scope computation options can be done on global level
---   (in |MiniIndentscope.config|), for a certain buffer (using
---   `vim.b.miniindentscope_config` buffer variable), or within a call (using
---   `opts` variable in |MiniIndentscope.get_scope|).
--- - Customizable notion of a border: which adjacent lines with strictly lower
---   indent are recognized as such. This is useful for a certain filetypes
---   (for example, Python or plain text).
--- - Customizable way of line to be considered "border first". This is useful
---   if you want to place cursor on function header and get scope of its body.
--- - There are textobjects and motions to operate on scope. Support |count|
---   and dot-repeat (in operator pending mode).
--- # Setup~
--- This module needs a setup with `require('mini.indentscope').setup({})`
--- (replace `{}` with your `config` table). It will create global Lua table
--- `MiniIndentscope` which you can use for scripting or manually (with `:lua
--- MiniIndentscope.*`).
--- See |MiniIndentscope.config| for available config settings.
--- You can override runtime config settings locally to buffer inside
--- `vim.b.miniindentscope_config` which should have same structure as
--- `MiniIndentscope.config`. See |mini.nvim-buffer-local-config| for more details.
--- # Comparisons~
--- - 'lukas-reineke/indent-blankline.nvim':
---     - Its main functionality is about showing static guides of indent levels.
---     - Implementation of 'mini.indentscope' is similar to
---       'indent-blankline.nvim' (using |extmarks| on first column to be shown
---       even on blank lines). They can be used simultaneously, but it will
---       lead to one of the visualizations being on top (hiding) of another.
--- # Highlight groups~
--- * `MiniIndentscopeSymbol` - symbol showing on every line of scope.
--- To change any highlight group, modify it directly with |:highlight|.
--- # Disabling~
--- To disable autodrawing, set `g:miniindentscope_disable` (globally) or
--- `b:miniindentscope_disable` (for a buffer) to `v: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.
---@tag mini.indentscope
---@tag MiniIndentscope
--- Drawing of scope indicator
--- Draw of scope indicator is done as iterative animation. It has the
--- following design:
--- - Draw indicator on origin line (where cursor is at) immediately. Indicator
---   is visualized as `MiniIndentscope.config.symbol` placed to the right of
---   scope's border indent. This creates a line from top to bottom scope edges.
--- - Draw upward and downward concurrently per one line. Progression by one
---   line in both direction is considered to be one step of animation.
--- - Before each step wait certain amount of time, which is decided by
---   "animation function". It takes next and total step numbers (both are one
---   or bigger) and returns number of milliseconds to wait before drawing next
---   step. Comparing to a more popular "easing functions" in animation (input:
---   duration since animation start; output: percent of animation done), it is
---   a discrete inverse version of its derivative. Such interface proved to be
---   more appropriate for kind of task at hand.
--- Special cases~
--- - When scope to be drawn intersects (same indent, ranges overlap) currently
---   visible one (at process or finished drawing), drawing is done immediately
---   without animation. With most common example being typing new text, this
---   feels more natural.
--- - Scope for the whole buffer is not drawn as it is isually redundant.
---   Technically, it can be thought as drawn at column 0 (because border
---   indent is -1) which is not visible.
---@tag MiniIndentscope-drawing
-- Module definition ==========================================================
local MiniIndentscope = {}
local H = {}
--- Module setup
---@param config table Module config table. See |MiniIndentscope.config|.
---@usage `require('mini.indentscope').setup({})` (replace `{}` with your `config` table)
MiniIndentscope.setup = function(config)
  -- Export module
  _G.MiniIndentscope = MiniIndentscope
  -- Setup config
  config = H.setup_config(config)
  -- Apply config
  H.apply_config(config)
  -- Module behavior
  vim.api.nvim_exec(
    [[augroup MiniIndentscope
        au!
        au CursorMoved,CursorMovedI                          * lua MiniIndentscope.auto_draw({ lazy = true })
        au TextChanged,TextChangedI,TextChangedP,WinScrolled * lua MiniIndentscope.auto_draw()
      augroup END]],
  if vim.fn.exists('##ModeChanged') == 1 then
    vim.api.nvim_exec(
      -- Call `auto_draw` on mode change to respect `miniindentscope_disable`
      [[augroup MiniIndentscope
          au ModeChanged *:* lua MiniIndentscope.auto_draw({ lazy = true })
        augroup END]],
      false
  -- Create highlighting
  vim.api.nvim_exec('hi default link MiniIndentscopeSymbol Delimiter', false)
--- Module config
--- Default values:
---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
---@text # Options ~
--- - Options can be supplied globally (from this `config`), locally to buffer
---   (via `options` field of `vim.b.miniindentscope_config` buffer variable),
---   or locally to call (as argument to |MiniIndentscope.get_scope()|).
--- - Option `border` controls which line(s) with smaller indent to categorize
---   as border. This matters for textobjects and motions.
---   It also controls how empty lines are treated: they are included in scope
---   only if followed by a border. Another way of looking at it is that indent
---   of blank line is computed based on value of `border` option.
---   Here is an illustration of how `border` works in presense of empty lines:
---                              |both|bottom|top|none|
---   1|function foo()           | 0  |  0   | 0 | 0  |
---   3|    print('Hello world') | 4  |  4   | 4 | 4  |
---   5|  end                    | 2  |  2   | 2 | 2  |
---   Numbers inside a table are indent values of a line computed with certain
---   value of `border`. So, for example, a scope with reference line 3 and
---   right-most column has body range depending on value of `border` option:
---     - `border` is "both":   range is 2-4, border is 1 and 5 with indent 2.
---     - `border` is "top":    range is 2-3, border is 1 with indent 0.
---     - `border` is "bottom": range is 3-4, border is 5 with indent 0.
---     - `border` is "none":   range is 3-3, border is empty with indent `nil`.
--- - Option `indent_at_cursor` controls if cursor position should affect
---   computation of scope. If `true`, reference indent is a minimum of
---   reference line's indent and cursor column. In main example, here how
---   scope's body range differs depending on cursor column and `indent_at_cursor`
---   value (assuming cursor is on line 3 and it is whole buffer):
---     Column\Option true|false
---        1 and 2    2-5 | 2-4
---      3 and more   2-4 | 2-4
--- - Option `try_as_border` controls how to act when input line can be
---   recognized as a border of some neighbor indent scope. In main example,
---   when input line is 1 and can be recognized as border for inner scope,
---   value `try_as_border = true` means that inner scope will be returned.
---   Similar, for input line 5 inner scope will be returned if it is
---   recognized as border.
MiniIndentscope.config = {
    -- Delay (in ms) between event and start of drawing scope indicator
    delay = 100,
    -- Animation rule for scope's first drawing. A function which, given
    -- next and total step numbers, returns wait time (in ms). See
    -- |MiniIndentscope.gen_animation| for builtin options. To disable
    -- animation, use `require('mini.indentscope').gen_animation.none()`.
    --minidoc_replace_start animation = --<function: implements constant 20ms between steps>,
    animation = function(s, n) return 20 end,
    --minidoc_replace_end
  -- Module mappings. Use `''` (empty string) to disable one.
  mappings = {
    -- Textobjects
    object_scope = 'ii',
    object_scope_with_border = 'ai',
    -- Motions (jump to respective border line; if not present - body line)
    goto_top = '[i',
    goto_bottom = ']i',
  -- Options which control scope computation
  options = {
    -- Type of scope's border: which line(s) with smaller indent to
    -- categorize as border. Can be one of: 'both', 'top', 'bottom', 'none'.
    border = 'both',
    -- Whether to use cursor column when computing reference indent.
    -- Useful to see incremental scopes with horizontal cursor movements.
    indent_at_cursor = true,
    -- Whether to first check input line to be a border of adjacent scope.
    -- Use it if you want to place cursor on function header to get scope of
    -- its body.
    try_as_border = false,
  -- Which character to use for drawing scope indicator
  symbol = '╎',
--minidoc_afterlines_end
-- Module functionality =======================================================
--- Compute indent scope
--- Indent scope (or just "scope") is a maximum set of consecutive lines which
--- contains certain reference line (cursor line by default) and every member
--- has indent not less than certain reference indent ("indent at column" by
--- default). Here "indent at column" means minimum between input column value
--- and indent of reference line. When using cursor column, this allows for a
--- useful interactive view of nested indent scopes by making horizontal
--- movements within line.
--- Options controlling actual computation is taken from these places in order:
--- - Argument `opts`. Use it to ensure independence from other sources.
--- - Buffer local variable `vim.b.miniindentscope_config` (`options` field).
---   Useful to define local behavior (for example, for a certain filetype).
--- - Global options from |MiniIndentscope.config|.
--- Algorithm overview~
--- - Compute reference "indent at column". Reference line is an input `line`
---   which might be modified to one of its neighbors if `try_as_border` option
---   is `true`: if it can be viewed as border of some neighbor scope, it will.
--- - Process upwards and downwards from reference line to search for line with
---   indent strictly less than reference one. This is like casting rays up and
---   down from reference line and reference indent until meeting "a wall"
---   (character to the right of indent or buffer edge). Latest line before
---   meeting is a respective end of scope body. It always exists because
---   reference line is a such one.
--- - Based on top and bottom lines with strictly lower indent, construct
---   scopes's border. The way it is computed is decided based on `border`
---   option (see |MiniIndentscope.config| for more information).
--- - Compute border indent as maximum indent of border lines (or reference
---   indent minus one in case of no border). This is used during drawing
---   visual indicator.
--- Indent computation~
--- For every line indent is intended to be computed unambiguously:
--- - For "normal" lines indent is an output of |indent()|.
--- - Indent is `-1` for imaginary lines 0 and past last line.
--- - For blank and empty lines indent is computed based on previous
---   (|prevnonblank()|) and next (|nextnonblank()|) non-blank lines. The way
---   it is computed is decided based on `border` in order to not include blank
---   lines at edge of scope's body if there is no border there. See
---   |MiniIndentscope.config| for a details example.
---@param line number Input line number (starts from 1). Can be modified to a
---   neighbor if `try_as_border` is `true`. Default: cursor line.
---@param col number Column number (starts from 1). Default: if
---   `indent_at_cursor` option is `true` - cursor column from `curswant` of
---   |getcurpos()| (allows for more natural behavior on empty lines);
---   `math.huge` otherwise in order to not incorporate cursor in computation.
---@param opts table Options to override global or buffer local ones (see
---   |MiniIndentscope.config|).
---@return table Table with scope information:
---   - <body> - table with <top> (top line of scope, inclusive), <bottom>
---     (bottom line of scope, inclusive), and <indent> (minimum indent withing
---     scope) keys. Line numbers start at 1.
---   - <border> - table with <top> (line of top border, might be `nil`),
---     <bottom> (line of bottom border, might be `nil`), and <indent> (indent
---     of border) keys. Line numbers start at 1.
---   - <buf_id> - identifier of current buffer.
---   - <reference> - table with <line> (reference line), <column> (reference
---     column), and <indent> ("indent at column") keys.
MiniIndentscope.get_scope = function(line, col, opts)
  opts = H.get_config({ options = opts }).options
  -- Compute default `line` and\or `col`
  if not (line and col) then
    local curpos = vim.fn.getcurpos()
    line = line or curpos[2]
    line = opts.try_as_border and H.border_correctors[opts.border](line, opts) or line
    -- Use `curpos[5]` (`curswant`, see `:h getcurpos()`) to account for blank
    -- and empty lines.
    col = col or (opts.indent_at_cursor and curpos[5] or math.huge)
  -- Compute "indent at column"
  local line_indent = H.get_line_indent(line, opts)
  local indent = math.min(col, line_indent)
  -- Make early return
  local body = { indent = indent }
  if indent <= 0 then
    body.top, body.bottom, body.indent = 1, vim.fn.line('$'), line_indent
    local up_min_indent, down_min_indent
    body.top, up_min_indent = H.cast_ray(line, indent, 'up', opts)
    body.bottom, down_min_indent = H.cast_ray(line, indent, 'down', opts)
    body.indent = math.min(line_indent, up_min_indent, down_min_indent)
    body = body,
    border = H.border_from_body[opts.border](body, opts),
    buf_id = vim.api.nvim_get_current_buf(),
    reference = { line = line, column = col, indent = indent },
--- Auto draw scope indicator based on movement events
--- Designed to be used with |autocmd|. No need to use it directly, everything
--- is setup in |MiniIndentscope.setup|.
---@param opts table Options.
MiniIndentscope.auto_draw = function(opts)
  if H.is_disabled() then
    H.undraw_scope()
  opts = opts or {}
  local scope = MiniIndentscope.get_scope()
  -- Make early return if nothing has to be done. Doing this before updating
  -- event id allows to not interrupt ongoing animation.
  if opts.lazy and H.current.draw_status ~= 'none' and H.scope_is_equal(scope, H.current.scope) then return end
  -- Account for current event
  local local_event_id = H.current.event_id + 1
  H.current.event_id = local_event_id
  -- Compute drawing options for current event
  local draw_opts = H.make_autodraw_opts(scope)
  -- Allow delay
  if draw_opts.delay > 0 then H.undraw_scope(draw_opts) end
  -- Use `defer_fn()` even if `delay` is 0 to draw indicator only after all
  -- events are processed (stops flickering)
  vim.defer_fn(function()
    if H.current.event_id ~= local_event_id then return end
    H.undraw_scope(draw_opts)
    H.current.scope = scope
    H.draw_scope(scope, draw_opts)
  end, draw_opts.delay)
--- Draw scope manually
--- Scope is visualized as a vertical line withing scope's body range at column
--- equal to border indent plus one (or body indent if border is absent).
--- Numbering starts from one.
---@param scope table Scope. Default: output of |MiniIndentscope.get_scope|
---   with default arguments.
---@param opts table Options. Currently supported:
---    - <animation_fun> - animation function for drawing. See
---      |MiniIndentscope-drawing| and |MiniIndentscope.gen_animation|.
MiniIndentscope.draw = function(scope, opts)
  scope = scope or MiniIndentscope.get_scope()
  local draw_opts = vim.tbl_deep_extend('force', { animation_fun = H.get_config().draw.animation }, opts or {})
  H.undraw_scope()
  H.current.scope = scope
  H.draw_scope(scope, draw_opts)
--- Undraw currently visible scope manually
MiniIndentscope.undraw = function() H.undraw_scope() end
-- TODO: Remove "Migrate from function type" after 0.7.0 release.
--- Generate builtin animation function
--- This is a builtin source to generate animation function for usage in
--- `MiniIndentscope.config.draw.animation`. Most of them are variations of
--- common easing functions, which provide certain type of progression for
--- revealing scope visual indicator.
--- Each field corresponds to one family of progression which can be customized
--- further by supplying appropriate arguments.
--- Examples ~
--- - Don't use animation: `MiniIndentscope.gen_animation.none()`
--- - Use quadratic "out" easing with total duration of 1000 ms:
---   `gen_animation.quadratic({ easing = 'out', duration = 1000, unit = 'total' })`
--- Migrate from function type ~
--- Initially `MiniIndentscope.gen_animation` was a function taking `easing`
--- and `opts` as arguments. To migrate from it, perform these steps:
--- - Split `easing` value into two parts: progression family ("none", "linear",
---   etc.) and acceleration type ("In", "Out", "InOut").
--- - Use progression family as a field name of `gen_animation` table.
--- - Convert acceleration type to other notation ("In" -> "in", "Out" ->
---   "out", "InOut" -> "in-out") and use it as `easing` field of `opts` table.
--- Examples:
--- - `MiniIndentscope.gen_animation('none')` ->
---   `MiniIndentscope.gen_animation.none()`.
--- - `gen_animation('quadraticInOut', { duration = 1000, unit = 'total' })` ->
---   `gen_animation.quadratic({ easing = 'in-out', duration = 1000, unit = 'total' })`.
---@seealso |MiniIndentscope-drawing| for more information about how drawing is done.
MiniIndentscope.gen_animation = {}
---@alias __animation_opts table Options that control progression. Possible keys:
---   - <easing> `(string)` - a subtype of progression. One of "in"
---     (accelerating from zero speed), "out" (decelerating to zero speed),
---     "in-out" (default; accelerating halfway, decelerating after).
---   - <duration> `(number)` - duration (in ms) of a unit. Default: 20.
---   - <unit> `(string)` - which unit's duration `opts.duration` controls. One
---     of "step" (default; ensures average duration of step to be `opts.duration`)
---     or "total" (ensures fixed total duration regardless of scope's range).
---@alias __animation_return function Animation function (see |MiniIndentscope-drawing|).
-- TODO: Remove after 0.7.0 release.
local n_notifications = 0
setmetatable(MiniIndentscope.gen_animation, {
  __call = function(_, easing, opts)
    if n_notifications < 1 then
      vim.notify(
        '(mini.indentscope) `MiniIndentscope.gen_animation` is now a table '
          .. [[(for consistency with other `gen_*` functions in 'mini.nvim').]]
          .. ' See "Migrate from function type" section of `:h MiniIndentscope.gen_animation`.'
          .. ' Calling it as function will be available until next release.'
      n_notifications = n_notifications + 1
    if easing == 'none' then return function() return 0 end end
    opts = vim.tbl_deep_extend('force', { duration = 20, unit = 'step' }, opts or {})
    if not vim.tbl_contains({ 'total', 'step' }, opts.unit) then
      H.error([[In `gen_animation()` argument `opts.unit` should be one of 'step' or 'total'.]])
    local arith, geom = H.animation_arithmetic_powers, H.animation_geometrical_powers
    local duration, unit = opts.duration, opts.unit
    --stylua: ignore
    local easing_calls = {
      linear           = { impl = arith, args = { 0, { easing = 'in',     duration = duration, unit = unit } } },
      quadraticIn      = { impl = arith, args = { 1, { easing = 'in',     duration = duration, unit = unit } } },
      quadraticOut     = { impl = arith, args = { 1, { easing = 'out',    duration = duration, unit = unit } } },
      quadraticInOut   = { impl = arith, args = { 1, { easing = 'in-out', duration = duration, unit = unit } } },
      cubicIn          = { impl = arith, args = { 2, { easing = 'in',     duration = duration, unit = unit } } },
      cubicOut         = { impl = arith, args = { 2, { easing = 'out',    duration = duration, unit = unit } } },
      cubicInOut       = { impl = arith, args = { 2, { easing = 'in-out', duration = duration, unit = unit } } },
      quarticIn        = { impl = arith, args = { 3, { easing = 'in',     duration = duration, unit = unit } } },
      quarticOut       = { impl = arith, args = { 3, { easing = 'out',    duration = duration, unit = unit } } },
      quarticInOut     = { impl = arith, args = { 3, { easing = 'in-out', duration = duration, unit = unit } } },
      exponentialIn    = { impl = geom,  args = {    { easing = 'in',     duration = duration, unit = unit } } },
      exponentialOut   = { impl = geom,  args = {    { easing = 'out',    duration = duration, unit = unit } } },
      exponentialInOut = { impl = geom,  args = {    { easing = 'in-out', duration = duration, unit = unit } } },
    local allowed_easing_types = vim.tbl_keys(easing_calls)
    table.sort(allowed_easing_types)
    if not vim.tbl_contains(allowed_easing_types, easing) then
      local msg = 'In `gen_animation()` argument `easing` should be one of: '
        .. table.concat(allowed_easing_types, ', ')
        .. '.'
      H.error(msg)
    local parts = easing_calls[easing]
    return parts.impl(unpack(parts.args))
--- Generate no animation
--- Show indicator immediately. Same as animation function always returning 0.
MiniIndentscope.gen_animation.none = function()
  return function() return 0 end
--- Generate linear progression
---@param opts __animation_opts
---@return __animation_return
MiniIndentscope.gen_animation.linear =
  function(opts) return H.animation_arithmetic_powers(0, H.normalize_animation_opts(opts)) end
--- Generate quadratic progression
---@param opts __animation_opts
---@return __animation_return
MiniIndentscope.gen_animation.quadratic =
  function(opts) return H.animation_arithmetic_powers(1, H.normalize_animation_opts(opts)) end
--- Generate cubic progression
---@param opts __animation_opts
---@return __animation_return
MiniIndentscope.gen_animation.cubic =
  function(opts) return H.animation_arithmetic_powers(2, H.normalize_animation_opts(opts)) end
--- Generate quartic progression
---@param opts __animation_opts
---@return __animation_return
MiniIndentscope.gen_animation.quartic =
  function(opts) return H.animation_arithmetic_powers(3, H.normalize_animation_opts(opts)) end
--- Generate exponential progression
---@param opts __animation_opts
---@return __animation_return
MiniIndentscope.gen_animation.exponential =
  function(opts) return H.animation_geometrical_powers(H.normalize_animation_opts(opts)) end
--- Move cursor within scope
--- Cursor is placed on a first non-blank character of target line.
---@param side string One of "top" or "bottom".
---@param use_border boolean Whether to move to border or withing scope's body.
---   If particular border is absent, body is used.
---@param scope table Scope to use. Default: output of |MiniIndentscope.get_scope()|.
MiniIndentscope.move_cursor = function(side, use_border, scope)
  scope = scope or MiniIndentscope.get_scope()
  -- This defaults to body's side if it is not present in border
  local target_line = use_border and scope.border[side] or scope.body[side]
  target_line = math.min(math.max(target_line, 1), vim.fn.line('$'))
  vim.api.nvim_win_set_cursor(0, { target_line, 0 })
  -- Move to first non-blank character to allow chaining scopes
  vim.cmd('normal! ^')
--- Function for motion mappings
--- Move to a certain side of border. Respects |count| and dot-repeat (in
--- operator-pending mode). Doesn't move cursor for scope that is not shown
--- (drawing indent less that zero).
---@param side string One of "top" or "bottom".
---@param add_to_jumplist boolean Whether to add movement to jump list. It is
---   `true` only for Normal mode mappings.
MiniIndentscope.operator = function(side, add_to_jumplist)
  local scope = MiniIndentscope.get_scope()
  -- Don't support scope that can't be shown
  if H.scope_get_draw_indent(scope) < 0 then return end
  -- Add movement to jump list. Needs remembering `count1` before that because
  -- it seems to reset it to 1.
  local count = vim.v.count1
  if add_to_jumplist then vim.cmd('normal! m`') end
  -- Make sequence of jumps
  for _ = 1, count do
    MiniIndentscope.move_cursor(side, true, scope)
    -- Use `try_as_border = false` to enable chaining
    scope = MiniIndentscope.get_scope(nil, nil, { try_as_border = false })
    -- Don't support scope that can't be shown
    if H.scope_get_draw_indent(scope) < 0 then return end
--- Function for textobject mappings
--- Respects |count| and dot-repeat (in operator-pending mode). Doesn't work
--- for scope that is not shown (drawing indent less that zero).
---@param use_border boolean Whether to include border in textobject. When
---   `true` and `try_as_border` option is `false`, allows "chaining" calls for
---   incremental selection.
MiniIndentscope.textobject = function(use_border)
  local scope = MiniIndentscope.get_scope()
  -- Don't support scope that can't be shown
  if H.scope_get_draw_indent(scope) < 0 then return end
  -- Allow chaining only if using border
  local count = use_border and vim.v.count1 or 1
  -- Make sequence of incremental selections
  for _ = 1, count do
    -- Try finish cursor on border
    local start, finish = 'top', 'bottom'
    if use_border and scope.border.bottom == nil then
      start, finish = 'bottom', 'top'
    H.exit_visual_mode()
    MiniIndentscope.move_cursor(start, use_border, scope)
    vim.cmd('normal! V')
    MiniIndentscope.move_cursor(finish, use_border, scope)
    -- Use `try_as_border = false` to enable chaining
    scope = MiniIndentscope.get_scope(nil, nil, { try_as_border = false })
    -- Don't support scope that can't be shown
    if H.scope_get_draw_indent(scope) < 0 then return end
-- Helper data ================================================================
-- Module default config
H.default_config = MiniIndentscope.config
-- Namespace for drawing vertical line
H.ns_id = vim.api.nvim_create_namespace('MiniIndentscope')
-- Timer for doing animation
H.timer = vim.loop.new_timer()
-- Table with current relevalnt data:
-- - `event_id` - counter for events.
-- - `scope` - latest drawn scope.
-- - `draw_status` - status of current drawing.
H.current = { event_id = 0, scope = {}, draw_status = 'none' }
-- Functions to compute indent in ambiguous cases
H.indent_funs = {
  ['min'] = function(top_indent, bottom_indent) return math.min(top_indent, bottom_indent) end,
  ['max'] = function(top_indent, bottom_indent) return math.max(top_indent, bottom_indent) end,
  ['top'] = function(top_indent, bottom_indent) return top_indent end,
  ['bottom'] = function(top_indent, bottom_indent) return bottom_indent end,
-- Functions to compute indent of blank line to satisfy `config.options.border`
H.blank_indent_funs = {
  ['none'] = H.indent_funs.min,
  ['top'] = H.indent_funs.bottom,
  ['bottom'] = H.indent_funs.top,
  ['both'] = H.indent_funs.max,
-- Functions to compute border from body
H.border_from_body = {
  ['none'] = function(body, opts) return {} end,
  ['top'] = function(body, opts) return { top = body.top - 1, indent = H.get_line_indent(body.top - 1, opts) } end,
  ['bottom'] = function(body, opts) return { bottom = body.bottom + 1, indent = H.get_line_indent(body.bottom + 1, opts) } end,
  ['both'] = function(body, opts)
    return {
      top = body.top - 1,
      bottom = body.bottom + 1,
      indent = math.max(H.get_line_indent(body.top - 1, opts), H.get_line_indent(body.bottom + 1, opts)),
-- Functions to correct line in case it is a border
H.border_correctors = {
  ['none'] = function(line, opts) return line end,
  ['top'] = function(line, opts)
    local cur_indent, next_indent = H.get_line_indent(line, opts), H.get_line_indent(line + 1, opts)
    return (cur_indent < next_indent) and (line + 1) or line
  ['bottom'] = function(line, opts)
    local prev_indent, cur_indent = H.get_line_indent(line - 1, opts), H.get_line_indent(line, opts)
    return (cur_indent < prev_indent) and (line - 1) or line
  ['both'] = function(line, opts)
    local prev_indent, cur_indent, next_indent =
      H.get_line_indent(line - 1, opts), H.get_line_indent(line, opts), H.get_line_indent(line + 1, opts)
    if prev_indent <= cur_indent and next_indent <= cur_indent then return line end
    -- If prev and next indents are equal and bigger than current, prefer next
    if prev_indent <= next_indent then return line + 1 end
    return line - 1
-- Helper functionality =======================================================
-- Settings -------------------------------------------------------------------
H.setup_config = function(config)
  -- General idea: if some table elements are not present in user-supplied
  -- `config`, take them from default config
  vim.validate({ config = { config, 'table', true } })
  config = vim.tbl_deep_extend('force', H.default_config, config or {})
  -- Validate per nesting level to produce correct error message
  vim.validate({
    draw = { config.draw, 'table' },
    mappings = { config.mappings, 'table' },
    options = { config.options, 'table' },
    symbol = { config.symbol, 'string' },
  vim.validate({
    ['draw.delay'] = { config.draw.delay, 'number' },
    ['draw.animation'] = { config.draw.animation, 'function' },
    ['mappings.object_scope'] = { config.mappings.object_scope, 'string' },
    ['mappings.object_scope_with_border'] = { config.mappings.object_scope_with_border, 'string' },
    ['mappings.goto_top'] = { config.mappings.goto_top, 'string' },
    ['mappings.goto_bottom'] = { config.mappings.goto_bottom, 'string' },
    ['options.border'] = { config.options.border, 'string' },
    ['options.indent_at_cursor'] = { config.options.indent_at_cursor, 'boolean' },
    ['options.try_as_border'] = { config.options.try_as_border, 'boolean' },
  return config
H.apply_config = function(config)
  MiniIndentscope.config = config
  local maps = config.mappings
  --stylua: ignore start
  H.map('n', maps.goto_top, [[<Cmd>lua MiniIndentscope.operator('top', true)<CR>]], { desc = 'Go to indent scope top' })
  H.map('n', maps.goto_bottom, [[<Cmd>lua MiniIndentscope.operator('bottom', true)<CR>]], { desc = 'Go to indent scope bottom' })
  H.map('x', maps.goto_top, [[<Cmd>lua MiniIndentscope.operator('top')<CR>]], { desc = 'Go to indent scope top' })
  H.map('x', maps.goto_bottom, [[<Cmd>lua MiniIndentscope.operator('bottom')<CR>]], { desc = 'Go to indent scope bottom' })
  H.map('x', maps.object_scope, '<Cmd>lua MiniIndentscope.textobject(false)<CR>', { desc = 'Object scope' })
  H.map('x', maps.object_scope_with_border, '<Cmd>lua MiniIndentscope.textobject(true)<CR>', { desc = 'Object scope with border' })
  H.map('o', maps.goto_top, [[<Cmd>lua MiniIndentscope.operator('top')<CR>]], { desc = 'Go to indent scope top' })
  H.map('o', maps.goto_bottom, [[<Cmd>lua MiniIndentscope.operator('bottom')<CR>]], { desc = 'Go to indent scope bottom' })
  H.map('o', maps.object_scope, '<Cmd>lua MiniIndentscope.textobject(false)<CR>', { desc = 'Object scope' })
  H.map('o', maps.object_scope_with_border, '<Cmd>lua MiniIndentscope.textobject(true)<CR>', { desc = 'Object scope with border' })
  --stylua: ignore start
H.is_disabled = function() return vim.g.miniindentscope_disable == true or vim.b.miniindentscope_disable == true end
H.get_config = function(config)
  return vim.tbl_deep_extend('force', MiniIndentscope.config, vim.b.miniindentscope_config or {}, config or {})
-- Scope ----------------------------------------------------------------------
-- Line indent:
-- - Equals output of `vim.fn.indent()` in case of non-blank line.
-- - Depends on `MiniIndentscope.config.options.border` in such way so as to
--   ignore blank lines before line not recognized as border.
H.get_line_indent = function(line, opts)
  local prev_nonblank = vim.fn.prevnonblank(line)
  local res = vim.fn.indent(prev_nonblank)
  -- Compute indent of blank line depending on `options.border` values
  if line ~= prev_nonblank then
    local next_indent = vim.fn.indent(vim.fn.nextnonblank(line))
    local blank_rule = H.blank_indent_funs[opts.border]
    res = blank_rule(res, next_indent)
  return res
H.cast_ray = function(line, indent, direction, opts)
  local final_line, increment = 1, -1
  if direction == 'down' then
    final_line, increment = vim.fn.line('$'), 1
  local min_indent = math.huge
  for l = line, final_line, increment do
    local new_indent = H.get_line_indent(l + increment, opts)
    if new_indent < indent then return l, min_indent end
    if new_indent < min_indent then min_indent = new_indent end
  return final_line, min_indent
H.scope_get_draw_indent = function(scope) return scope.border.indent or (scope.body.indent - 1) end
H.scope_is_equal = function(scope_1, scope_2)
  if type(scope_1) ~= 'table' or type(scope_2) ~= 'table' then return false end
  return scope_1.buf_id == scope_2.buf_id
    and H.scope_get_draw_indent(scope_1) == H.scope_get_draw_indent(scope_2)
    and scope_1.body.top 
F59F
== scope_2.body.top
    and scope_1.body.bottom == scope_2.body.bottom
H.scope_has_intersect = function(scope_1, scope_2)
  if type(scope_1) ~= 'table' or type(scope_2) ~= 'table' then return false end
  if (scope_1.buf_id ~= scope_2.buf_id) or (H.scope_get_draw_indent(scope_1) ~= H.scope_get_draw_indent(scope_2)) then
    return false
  local body_1, body_2 = scope_1.body, scope_2.body
  return (body_2.top <= body_1.top and body_1.top <= body_2.bottom)
    or (body_1.top <= body_2.top and body_2.top <= body_1.bottom)
-- Indicator ------------------------------------------------------------------
--- Compute indicator of scope to be displayed
--- Indicator is visual representation of scope in current window view using
--- extmarks. Currently only needed because Neovim can't correctly process
--- horizontal window scroll (Neovim issue:
--- https://github.com/neovim/neovim/issues/14050)
---@return table|nil Table with indicator info or empty one in case indicator
---   shouldn't be drawn.
---@private
H.indicator_compute = function(scope)
  scope = scope or H.current.scope
  local indent = H.scope_get_draw_indent(scope)
  -- Don't draw indicator that should be outside of screen. This condition is
  -- (perpusfully) "responsible" for not drawing indicator spanning whole file.
  if indent < 0 then return {} end
  -- Text indentation should depend on current window view because it will use
  -- `virt_text_win_col` attribute of extmark options (the only way to reliably
  -- put it anywhere on screen; important to show properly on empty lines).
  local col = indent - vim.fn.winsaveview().leftcol
  if col < 0 then return {} end
  local virt_text = { { H.get_config().symbol, 'MiniIndentscopeSymbol' } }
    buf_id = vim.api.nvim_get_current_buf(),
    virt_text = virt_text,
    virt_text_win_col = col,
    top = scope.body.top,
    bottom = scope.body.bottom,
-- Drawing --------------------------------------------------------------------
H.draw_scope = function(scope, opts)
  scope = scope or {}
  opts = opts or {}
  local indicator = H.indicator_compute(scope)
  -- Don't draw anything if nothing to be displayed
  if indicator.virt_text == nil or #indicator.virt_text == 0 then
    H.current.draw_status = 'finished'
  -- Make drawing function
  local draw_fun = H.make_draw_function(indicator, opts)
  -- Perform drawing
  H.current.draw_status = 'drawing'
  H.draw_indicator_animation(indicator, draw_fun, opts.animation_fun)
H.draw_indicator_animation = function(indicator, draw_fun, animation_fun)
  -- Draw from origin (cursor line but wihtin indicator range)
  local top, bottom = indicator.top, indicator.bottom
  local origin = math.min(math.max(vim.fn.line('.'), top), bottom)
  local step = 0
  local n_steps = math.max(origin - top, bottom - origin)
  local wait_time = 0
  local draw_step
  draw_step = vim.schedule_wrap(function()
    -- Check for not drawing outside of interval is done inside `draw_fun`
    local success = draw_fun(origin - step)
    if step > 0 then success = success and draw_fun(origin + step) end
    if not success or step == n_steps then
      H.current.draw_status = step == n_steps and 'finished' or H.current.draw_status
      H.timer:stop()
      return
    step = step + 1
    wait_time = wait_time + animation_fun(step, n_steps)
    -- Repeat value of `timer` seems to be rounded down to milliseconds. This
    -- means that values less than 1 will lead to timer stop repeating. Instead
    -- call next step function directly.
    if wait_time < 1 then
      H.timer:set_repeat(0)
      -- Use `return` to make this proper "tail call"
      return draw_step()
      H.timer:set_repeat(wait_time)
      -- Restart `wait_time` only if it is actually used
      wait_time = 0
      -- Usage of `again()` is needed to overcome the fact that it is called
      -- inside callback and to restart initial timer. Mainly this is needed
      -- only in case of transition from 'non-repeating' timer to 'repeating'
      -- one in case of complex animation functions. See
      -- https://docs.libuv.org/en/v1.x/timer.html#api
      H.timer:again()
  -- Start non-repeating timer without callback execution. This shouldn't be
  -- `timer:start(0, 0, draw_step)` because it will execute `draw_step` on the
  -- next redraw (flickers on window scroll).
  H.timer:start(10000000, 0, draw_step)
  -- Draw step zero (at origin) immediately
  draw_step()
H.undraw_scope = function(opts)
  opts = opts or {}
  -- Don't operate outside of current event if able to verify
  if opts.event_id and opts.event_id ~= H.current.event_id then return end
  pcall(vim.api.nvim_buf_clear_namespace, H.current.scope.buf_id or 0, H.ns_id, 0, -1)
  H.current.draw_status = 'none'
  H.current.scope = {}
H.make_autodraw_opts = function(scope)
  local config = H.get_config()
  local res = {
    event_id = H.current.event_id,
    type = 'animation',
    delay = config.draw.delay,
    animation_fun = config.draw.animation,
  if H.current.draw_status == 'none' then return res end
  -- Draw immediately scope which intersects (same indent, overlapping ranges)
  -- currently drawn or finished. This is more natural when typing text.
  if H.scope_has_intersect(scope, H.current.scope) then
    res.type = 'immediate'
    res.delay = 0
    res.animation_fun = MiniIndentscope.gen_animation.none()
    return res
  return res
H.make_draw_function = function(indicator, opts)
  local extmark_opts = {
    hl_mode = 'combine',
    priority = 2,
    right_gravity = false,
    virt_text = indicator.virt_text,
    virt_text_win_col = indicator.virt_text_win_col,
    virt_text_pos = 'overlay',
  local current_event_id = opts.event_id
  return function(l)
    -- Don't draw if outdated
    if H.current.event_id ~= current_event_id and current_event_id ~= nil then return false end
    -- Don't draw if disabled
    if H.is_disabled() then return false end
    -- Don't put extmark outside of indicator range
    if not (indicator.top <= l and l <= indicator.bottom) then return true end
    return pcall(vim.api.nvim_buf_set_extmark, indicator.buf_id, H.ns_id, l - 1, 0, extmark_opts)
-- Animations -----------------------------------------------------------------
--- Imitate common power easing function
--- Every step is preceeded by waiting time decreasing/increasing in power
--- series fashion (`d` is "delta", ensures total duration time):
--- - "in":  d*n^p; d*(n-1)^p; ... ; d*2^p;     d*1^p
--- - "out": d*1^p; d*2^p;     ... ; d*(n-1)^p; d*n^p
--- - "in-out": "in" until 0.5*n, "out" afterwards
--- This way it imitates `power + 1` common easing function because animation
--- progression behaves as sum of `power` elements.
View remainder of file in raw view

FilesExpand file tree

indentscope.lua

Latest commit

History

indentscope.lua

File metadata and controls