retrovim 0.0.3

package/nvim/plugins/mini.nvim/doc/mini-cmdline.txt

@@ -0,0 +1,392 @@
+*mini.cmdline* Command line tweaks
+
+MIT License Copyright (c) 2025 Evgeni Chasnovski
+
+------------------------------------------------------------------------------
+                                                                   *MiniCmdline*
+Features:
+
+- Autocomplete with customizable delay. Enhances |cmdline-completion| and
+  manual |'wildchar'| pressing experience.
+  Requires Neovim>=0.11, though Neovim>=0.12 is recommended.
+
+- Autocorrect words as-you-type. Only words that must come from a fixed set of
+  candidates (like commands and options) are autocorrected by default.
+
+- Autopeek command range as-you-type. Shows a floating window with range lines
+  along with customizable context lines.
+
+What it doesn't do:
+
+- Customization of command line UI. Use |ui2| (on Neovim>=0.12).
+
+- Customization of autocompletion candidates. They are computed
+  via |cmdline-completion|.
+
+# Setup ~
+
+This module needs a setup with `require('mini.cmdline').setup({})` (replace `{}`
+with your `config` table). It will create global Lua table `MiniCmdline` which
+you can use for scripting or manually (with `:lua MiniCmdline.*`).
+
+See |MiniCmdline.config| for `config` structure and default values.
+
+You can override runtime config settings locally to buffer inside
+`vim.b.minicmdline_config` which should have same structure as
+`MiniCmdline.config`. See |mini.nvim-buffer-local-config| for more details.
+
+# Suggested option values ~
+
+Some options are set automatically (if not set before |MiniCmdline.setup()|):
+- |'wildmode'| is set to "noselect,full" for less intrusive autocompletion.
+  Requires Neovim>=0.11 and enabled `config.autocomplete`.
+- |'wildoptions'| is set to "pum,fuzzy" to enable fuzzy matching.
+
+# Comparisons ~
+
+- [folke/noice.nvim](https://github.com/folke/noice.nvim):
+    - Mostly focuses on visual aspects of the Command line.
+      This modules is aimed to improve its workflow without changing UI.
+
+- [nacro90/numb.nvim](https://github.com/nacro90/numb.nvim):
+    - Designed to preview only a single line range defined by numbers.
+      This module handles any form of |:range| and |:range-offset| for both
+      one and two line ranges.
+    - Shows target line directly in the normal window.
+      This module uses a dedicated floating window.
+
+- Built-in |cmdline-autocompletion| (on Neovim>=0.12):
+    - This module on Neovim>=0.12 uses that as its base for autocompletion.
+      Ont top of that it also provides customizable delay and predicate.
+
+- Built-in |ui2| (on Neovim>=0.12):
+    - Mostly focuses on visual aspects of the Command line.
+      This modules is aimed to improve its workflow without changing UI.
+
+# Highlight groups ~
+*MiniCmdline-hl-groups*
+
+- `MiniCmdlinePeekBorder` - border of autopeek window.
+- `MiniCmdlinePeekLineNr` - line numbers in autopeek window.
+- `MiniCmdlinePeekNormal` - basic foreground/background of autopeek window.
+- `MiniCmdlinePeekSep` - statuscolumn separator in autopeek window.
+- `MiniCmdlinePeekSign` - signs in autopeek window.
+- `MiniCmdlinePeekTitle` - title of autopeek window.
+
+# Disabling ~
+
+To disable acting in mappings, set `vim.g.minicmdline_disable` (globally) or
+`vim.b.minicmdline_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.
+
+------------------------------------------------------------------------------
+                                                           *MiniCmdline.setup()*
+                         `MiniCmdline.setup`({config})
+Module setup
+
+Parameters ~
+{config} `(table|nil)` Module config table. See |MiniCmdline.config|.
+
+Usage ~
+>lua
+  require('mini.cmdline').setup() -- use default config
+  -- OR
+  require('mini.cmdline').setup({}) -- replace {} with your config table
+<
+------------------------------------------------------------------------------
+                                                            *MiniCmdline.config*
+                              `MiniCmdline.config`
+Defaults ~
+>lua
+  MiniCmdline.config = {
+    -- Autocompletion: show `:h 'wildmenu'` as you type
+    autocomplete = {
+      enable = true,
+
+      -- Delay (in ms) after which to trigger completion
+      -- Neovim>=0.12 is recommended for positive values
+      delay = 0,
+
+      -- Custom rule of when to trigger completion
+      predicate = nil,
+
+      -- Whether to map arrow keys for more consistent wildmenu behavior
+      map_arrows = true,
+    },
+
+    -- Autocorrection: adjust non-existing words (commands, options, etc.)
+    autocorrect = {
+      enable = true,
+
+      -- Custom autocorrection rule
+      func = nil,
+    },
+
+    -- Autopeek: show command's target range in a floating window
+    autopeek = {
+      enable = true,
+
+      -- Number of lines to show above and below range lines
+      n_context = 1,
+
+      -- Custom rule of when to show peek window
+      predicate = nil,
+
+      -- Window options
+      window = {
+        -- Floating window config
+        config = {},
+
+        -- Function to render statuscolumn
+        statuscolumn = nil,
+      },
+    },
+  }
+<
+# General ~
+
+- Each feature is configured via separate table.
+- Use `enable = false` to disable a feature.
+
+Autocomplete ~
+
+`config.autocomplete` is used to configure autocompletion: automatic show
+of |'wildmenu'|.
+
+`autocomplete.delay` defines a (debounce style) delay after which |'wildchar'|
+is triggered to show wildmenu.
+Default: 0. Note: Neovim>=0.12 is recommended for positive values if you
+want to reduce flicker (thanks to |wildtrigger()|).
+
+`autocomplete.predicate` defines a condition of whether to trigger completion
+at the current command line state. Takes a table with input data and should
+return `true` to show completion and `false` otherwise. Will be called before
+the possible delay at current command line state.
+Default: |MiniCmdline.default_autocomplete_predicate()|.
+
+Input data fields:
+- <line> `(string)` - current command line text. See |getcmdline()|.
+- <pos> `(number)` - current command line column. See |getcmdpos()|.
+- <line_prev> `(string)` - command line text before the latest change.
+- <pos_prev> `(number)` - command line column before the latest cursor move.
+
+Example of blocking completion based on completion type (as some may be slow): >lua
+
+  local block_compltype = { shellcmd = true }
+  require('mini.cmdline').setup({
+    autocomplete = {
+      predicate = function()
+        return not block_compltype[vim.fn.getcmdcompltype()]
+      end,
+    },
+  })
+<
+Similar approach can be used to enable completion only for normal Ex commands.
+Use `return vim.fn.getcmdtype() == ':'` as a predicate output.
+
+Autocorrect ~
+
+`config.autocorrect` is used to configure autocorrection: automatic adjustment
+of bad words as you type them. This works only when appending single character
+at the end of the command line. Editing already typed words does not trigger
+autocorrect (allows correcting the autocorrection).
+
+When to autocorrect is computed automatically based on |getcmdcomplpat()| after
+every key press: if it doesn't add the character to completion pattern, then
+the pattern before the key press is attempted to be corrected.
+There is also an autocorrection attempt for the last word just before
+executing the command.
+
+Notes:
+- This is intended mostly for fixing typos and not as a shortcut for fuzzy
+  matching. Performing the latter automatically is too intrusive. Explicitly
+  use fuzzy completion for that (set up by default).
+
+- Default autocorrection is done only for words that must come from a fixed
+  set of candidates (like commands and options) by choosing the one with
+  the lowest string distance.
+  See |MiniCmdline.default_autocorrect_func()| for details.
+
+- Word that matches some Command-line |abbreviation| is not autocorrected.
+
+- If current command expects only a single argument (like |:colorscheme|), then
+  autocorrection will happen only just before executing the command.
+
+`autocorrect.func` is a function that can be used to customize autocorrection.
+Takes a table with input data and should return a string with the correct word
+or `nil` for no autocorrection. Default: |MiniCmdline.default_autocorrect_func()|.
+
+Input data fields:
+- <word> `(string)` - word to be autocorrected. Never empty string.
+- <type> `(string)` - word type. Output of |getcmdcompltype()|.
+
+Autopeek ~
+
+`config.autopeek` is used to configure automatic peeking: show command's target
+range in a floating window. The window will appear above command line and show
+current buffer with the focus on left and right (if present and differs from
+left) range lines.
+
+`autopeek.n_context` defines how many lines to show above and below the target.
+The range itself is visualized by default with the statuscolumn signs.
+Default: 1.
+
+`autopeek.predicate` defines a condition of whether to show peek window at
+the current command line state. Takes a table with input data and should
+return `true` to peek and `false` otherwise.
+Will be called only if it is possible to parse range from the current command
+line text and it is for buffer lines (no command or |:command-addr| is `lines`)
+Default: |MiniCmdline.default_autopeek_predicate()|.
+
+Input data fields:
+- <left> `(number)` - left range edge. Not necessarily smallest.
+- <right> `(number)` - right range edge. Same as `left` for a single line range.
+- <cmd> `(string)` - full command name. Can be empty string if no valid
+  command is (yet) entered.
+
+`autopeek.window` defines behavior of a peek window.
+`autopeek.window.config` is a table defining floating window characteristics
+or a callable returning such table.
+It should have the same structure as in |nvim_open_win()|.
+
+`autopeek.window.statuscolumn` is a special function that can be used to
+customize |'statuscolumn'| value for the peek window. Takes a table with input
+data and should return a string to display for line |v:lnum|.
+Default: |MiniCmdline.default_autopeek_statuscolumn()|.
+Input data fields are the same as for `autopeek.predicate`.
+
+Example of showing `<` and `>` signs on range lines: >lua
+
+  function(data)
+    local n, l, r = vim.v.lnum, data.left, data.right
+    local s = n == l and (n == r and '* ' or '< ') or n == r and '> ' or ''
+    -- Needs explicit highlighting via `:h 'statusline'` syntax
+    return '%#MiniCmdlinePeekSign#' .. s
+  end
+<
+Notes:
+- Peek window directly shows current buffer, which means that all its
+  extmarks, virtual text, virtual lines, etc. are also shown.
+- Non-zero context might work unreliably if there are virtual lines.
+- Peeking intentionally hides Visual selection if Command-line mode is entered
+  directly from it. Peeking `'<,'>` range already visualizes the selection.
+  To disable autopeek for this case, add the following code BEFORE
+  executing `require('mini.cmdline').setup()`: >lua
+
+    local disable = vim.schedule_wrap(function()
+      local is_from_visual = vim.startswith(vim.fn.getcmdline(), "'<,'>")
+      MiniCmdline.config.autopeek.enable = not is_from_visual
+    end)
+    local reenable = function() MiniCmdline.config.autopeek.enable = true end
+
+    vim.api.nvim_create_autocmd('CmdlineEnter', { callback = disable })
+    vim.api.nvim_create_autocmd('CmdlineLeave', { callback = reenable })
+<
+------------------------------------------------------------------------------
+                                  *MiniCmdline.default_autocomplete_predicate()*
+          `MiniCmdline.default_autocomplete_predicate`({data}, {opts})
+Default autocompletion predicate
+
+Parameters ~
+{data} `(table)` Input autocompletion data. As described in |MiniCmdline.config|.
+{opts} `(table|nil)` Options. Reserved for future use.
+
+Return ~
+`(boolean)` If command line does not (yet) contain a letter - `false`,
+  otherwise - `true`. This makes autopeek easier to use for a numerical range.
+
+------------------------------------------------------------------------------
+                                        *MiniCmdline.default_autocorrect_func()*
+             `MiniCmdline.default_autocorrect_func`({data}, {opts})
+Default autocorrection function
+
+- Return input word if `opts.strict_type=true` and input `type` is not proper.
+- Get candidates via `opts.get_candidates()`.
+  Default: mostly via |getcompletion()| with empty pattern and input `type`.
+  Exceptions are `help` and `option` types: both list all available candidates
+  in their own ways.
+- Choose the candidate with the lowest Damerau–Levenshtein distance
+  (smallest number of deletion/insertion/substitution/transposition needed
+  to transform one word into another; slightly prefers transposition).
+  Notes:
+    - Type `'command'` also chooses from all valid candidate abbreviations.
+    - Comparison is done both respecting and ignoring case.
+
+Parameters ~
+{data} `(table)` Input autocorrection data. As described in |MiniCmdline.config|.
+{opts} `(table|nil)` Options. Possible fields:
+  - <strict_type> `(boolean)` - whether to restrict output only for types which
+    must have words from a fixed set of candidates (like command or option
+    names). Note: does not include `help` type since |:help| already has
+    "sophisticated algorithm" to handle typos. Default: `true`.
+  - <get_candidates> `(function)` - source of candidates. Will be called
+    with `data` as argument and should return array of string candidates to
+    choose from.
+    Default: for most types -  |getcompletion()| with empty pattern and
+    input `type`; for `help` and `option` type - all available help tags and
+    option names (long and short) respectively.
+
+Return ~
+`(string)` Autocorrected word.
+
+------------------------------------------------------------------------------
+                                      *MiniCmdline.default_autopeek_predicate()*
+            `MiniCmdline.default_autopeek_predicate`({data}, {opts})
+Default autopeek predicate
+
+Parameters ~
+{data} `(table)` Input autopeek data. As described in |MiniCmdline.config|.
+{opts} `(table|nil)` Options. Reserved for future use.
+
+Return ~
+`(boolean)` If command defines |:command-preview| - `false`, otherwise - `true`.
+  This makes autopeek easier to use for commands like |:substitute|,
+  especially if |'inccommand'| is set to `split`.
+
+------------------------------------------------------------------------------
+                                   *MiniCmdline.default_autopeek_statuscolumn()*
+          `MiniCmdline.default_autopeek_statuscolumn`({data}, {opts})
+Default autopeek statuscolumn
+
+- Show signs next to lines depending on their relation to peeked range.
+  Highlighted with `MiniCmdlinePeekSign` group.
+- Show line numbers for left and right parts of the range.
+  Highlighted with `MiniCmdlinePeekLineNr` group.
+- Separate statuscolumn and buffer text with dedicated separator character.
+  Highlighted with `MiniCmdlinePeekSep` group.
+
+Notes:
+- Intended to only be used as a part of |'statuscolumn'| function, as it
+  uses |v:lnum| and |v:virtnum| to compute the output.
+
+Example of adjusting a `mid` sign: >lua
+
+  local peek_stc_opts = { signs = { mid = '+' } }
+  local peek_stc = function(data)
+    return MiniCmdline.default_autopeek_statuscolumn(data, peek_stc_opts)
+  end
+  require('mini.cmdline').setup({
+    autopeek = { window = { statuscolumn = peek_stc } },
+  })
+<
+Parameters ~
+{data} `(table)` Input peek data. As described in |MiniCmdline.config|.
+{opts} `(table|nil)` Options. Possible fields:
+  - <signs> `(table)` - signs to show. Possible fields:
+      - <same> `(string)` - on range if `left=right`. Default: `'🭬'`.
+      - <left> `(string)`  - on `left` line.  Default: `'┌'`.
+      - <mid> `(string)`   - inside range.  Default: `'┊'`.
+      - <right> `(string)` - on `right` line. Default: `'└'`.
+      - <out> `(string)` - outside of range. Default: `''` (no sign).
+      - <virt> `(string)` - virtual line. Default: `'•'`.
+      - <wrap> `(string)` - wrapped line. Default: `'↳'`.
+  - <sep> `(string)` - string to put at the end to separate statuscolumn and
+    buffer text. Default: `'│'`
+
+  Note: Any sign and separator should have every `%` escaped as `%%` (due to its
+  special meaning in |'statuscolumn'|).
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: