retrovim 0.0.3

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

@@ -0,0 +1,472 @@
+*mini.operators* Text edit operators
+
+MIT License Copyright (c) 2023 Evgeni Chasnovski
+
+------------------------------------------------------------------------------
+                                                                 *MiniOperators*
+Features:
+- Operators:
+    - Evaluate text and replace with output.
+    - Exchange text regions.
+    - Multiply (duplicate) text.
+    - Replace text with register.
+    - Sort text.
+
+- Automated configurable mappings to operate on textobject, line, selection.
+  Can be disabled in favor of more control with |MiniOperators.make_mappings()|.
+
+- All operators support |[count]| and dot-repeat.
+
+See |MiniOperators-overview| and |MiniOperators.config| for more details.
+
+# Setup ~
+
+This module needs a setup with `require('mini.operators').setup({})` (replace
+`{}` with your `config` table). It will create global Lua table `MiniOperators`
+which you can use for scripting or manually (with `:lua MiniOperators.*`).
+
+See |MiniOperators.config| for available config settings.
+
+You can override runtime config settings (but not `config.mappings`) locally
+to buffer inside `vim.b.minioperators_config` which should have same structure
+as `MiniOperators.config`. See |mini.nvim-buffer-local-config| for more details.
+
+# Comparisons ~
+
+- [gbprod/substitute.nvim](https://github.com/gbprod/substitute.nvim):
+    - Has "replace" and "exchange" variants, but not others from this module.
+    - Has "replace/substitute" over range functionality, while this module
+      does not by design (it is similar to |:s| functionality while not
+      offering significantly lower mental complexity).
+    - "Replace" highlights pasted text, while in this module it doesn't.
+    - "Exchange" doesn't work across buffers, while in this module it does.
+
+- [svermeulen/vim-subversive](https://github.com/svermeulen/vim-subversive):
+    - Main inspiration for "replace" functionality, so they are mostly similar
+      for this operator.
+    - Has "replace/substitute" over range functionality, while this module
+      does not by design.
+
+- [tommcdo/vim-exchange](https://github.com/tommcdo/vim-exchange):
+    - Main inspiration for "exchange" functionality, so they are mostly
+      similar for this operator.
+    - Doesn't work across buffers, while this module does.
+
+- [christoomey/vim-sort-motion](https://github.com/christoomey/vim-sort-motion):
+    - Uses |:sort| for linewise sorting, while this module uses consistent
+      sorting algorithm (by default, see |MiniOperators.default_sort_func()|).
+    - Sorting algorithm can't be customized, while this module allows this
+      (see `sort.func` in |MiniOperators.config|).
+    - For charwise region uses only commas as separators, while this module
+      can also separate by semicolon or whitespace (by default,
+      see |MiniOperators.default_sort_func()|).
+
+# Highlight groups ~
+*MiniOperators-hl-groups*
+
+- `MiniOperatorsExchangeFrom` - first region to exchange.
+
+To change any highlight group, set it directly with |nvim_set_hl()|.
+
+# Disabling ~
+
+To disable main functionality, set `vim.g.minioperators_disable` (globally) or
+`vim.b.minioperators_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.
+
+------------------------------------------------------------------------------
+                                                        *MiniOperators-overview*
+Operator defines an action that will be performed on a textobject, motion,
+or visual selection (similar to |d|, |c|, etc.). When makes sense, it can also
+respect supplied register (like "replace" operator).
+
+This module implements each operator in a separate dedicated function
+(like |MiniOperators.replace()| for "replace" operator). Each such function
+takes `mode` as argument and acts depending on it:
+
+- If `mode` is `nil` (or not explicitly supplied), it sets |'operatorfunc'|
+  to this dedicated function and returns `g@` assuming being called from
+  expression mapping. See |:map-operator| and |:map-expression| for more details.
+
+- If `mode` is "char", "line", or "block", it acts as `operatorfunc` and performs
+  action for region between |`[| and |`]| marks.
+
+- If `mode` is "visual", it performs action for region between |`<| and |`>| marks.
+
+For more details about specific operator, see help for its function:
+
+- Evaluate: |MiniOperators.evaluate()|
+- Exchange: |MiniOperators.exchange()|
+- Multiply: |MiniOperators.multiply()|
+- Replace:  |MiniOperators.replace()|
+- Sort:     |MiniOperators.sort()|
+
+# Mappings ~
+*MiniOperators-mappings*
+
+All operators are automatically mapped during |MiniOperators.setup()| execution.
+Mappings keys are deduced from `prefix` field of corresponding `config` entry.
+All built-in conflicting mappings are removed (like |gra|, |grn| in Neovim>=0.11).
+Both |gx| and |v_gx| are remapped to `gX` (if that is not already taken).
+
+For each operator the following mappings are created:
+
+- In Normal mode to operate on textobject. Uses `prefix` directly.
+- In Normal mode to operate on line. Appends to `prefix` the last character.
+  This aligns with |operator-doubled| and established patterns for operators
+  with more than two characters, like |guu|, |gUU|, etc.
+- In Visual mode to operate on visual selection. Uses `prefix` directly.
+
+Example of default mappings for "replace":
+- `gr` in Normal mode for operating on textobject.
+  Example of usage: `griw` replaces "inner word" with default register.
+- `grr` in Normal mode for operating on line.
+  Example of usage: `grr` replaces current line.
+- `gr` in Visual mode for operating on visual selection.
+  Example of usage: `viw` selects "inner word" and `gr` replaces it.
+
+There are two suggested ways to customize mappings:
+
+- Change `prefix` in |MiniOperators.setup()| call. For example, doing >lua
+
+    require('mini.operators').setup({ replace = { prefix = 'cr' } })
+<
+  will make mappings for `cr` / `crr` / `cr` instead of `gr` / `grr` / `gr`.
+
+- Disable automated mapping creation by supplying empty string as prefix and
+  use |MiniOperators.make_mappings()| directly. For example: >lua
+
+    -- Disable automated creation of "replace"
+    local operators = require('mini.operators')
+    operators.setup({ replace = { prefix = '' } })
+
+    -- Make custom mappings
+    operators.make_mappings(
+      'replace',
+      { textobject = 'cr', line = 'crr', selection = 'cr' }
+    )
+<
+------------------------------------------------------------------------------
+                                                         *MiniOperators.setup()*
+                        `MiniOperators.setup`({config})
+Module setup
+
+Parameters ~
+{config} `(table|nil)` Module config table. See |MiniOperators.config|.
+
+Usage ~
+>lua
+  require('mini.operators').setup() -- use default config
+  -- OR
+  require('mini.operators').setup({}) -- replace {} with your config table
+<
+------------------------------------------------------------------------------
+                                                          *MiniOperators.config*
+                             `MiniOperators.config`
+Defaults ~
+>lua
+  MiniOperators.config = {
+    -- Each entry configures one operator.
+    -- `prefix` defines keys mapped during `setup()`: in Normal mode
+    -- to operate on textobject and line, in Visual - on selection.
+
+    -- Evaluate text and replace with output
+    evaluate = {
+      prefix = 'g=',
+
+      -- Function which does the evaluation
+      func = nil,
+    },
+
+    -- Exchange text regions
+    exchange = {
+      -- NOTE: Default `gx` is remapped to `gX`
+      prefix = 'gx',
+
+      -- Whether to reindent new text to match previous indent
+      reindent_linewise = true,
+    },
+
+    -- Multiply (duplicate) text
+    multiply = {
+      prefix = 'gm',
+
+      -- Function which can modify text before multiplying
+      func = nil,
+    },
+
+    -- Replace text with register
+    replace = {
+      -- NOTE: Default `gr*` LSP mappings are removed
+      prefix = 'gr',
+
+      -- Whether to reindent new text to match previous indent
+      reindent_linewise = true,
+    },
+
+    -- Sort text
+    sort = {
+      prefix = 'gs',
+
+      -- Function which does the sort
+      func = nil,
+    }
+  }
+<
+# Evaluate ~
+
+`evaluate.prefix` is a string used to automatically infer operator mappings keys
+during |MiniOperators.setup()|. See |MiniOperators-mappings|.
+
+`evaluate.func` is a function used to actually evaluate text region.
+If `nil` (default), |MiniOperators.default_evaluate_func()| is used.
+
+This function will take content table representing selected text as input
+and should return array of lines as output (each item per line).
+Content table has fields `lines`, array of region lines, and `submode`,
+one of `v`, `V`, `\22` (escaped `<C-v>`) for charwise, linewise, and blockwise.
+
+To customize evaluation per language, set `evaluate.func` in buffer-local
+config (`vim.b.minioperators_config`; see |mini.nvim-buffer-local-config|).
+
+# Exchange ~
+
+`exchange.prefix` is a string used to automatically infer operator mappings keys
+during |MiniOperators.setup()|. See |MiniOperators-mappings|.
+
+Note: default value "gx" overrides |gx| / |v_gx|. Instead they are remapped
+to `gX` (if that is not already taken). To keep using `gx` with built-in
+feature (open URL at cursor) choose different `config.prefix`.
+
+`exchange.reindent_linewise` is a boolean indicating whether newly put linewise
+text should preserve indent of replaced text. In other words, if `false`,
+regions are exchanged preserving their indents; if `true` - without them.
+
+# Multiply ~
+
+`multiply.prefix` is a string used to automatically infer operator mappings keys
+during |MiniOperators.setup()|. See |MiniOperators-mappings|.
+
+`multiply.func` is a function used to optionally update multiplied text.
+If `nil` (default), text used as is.
+
+Takes content table as input (see "Evaluate" section) and should return
+array of lines as output.
+
+# Replace ~
+
+`replace.prefix` is a string used to automatically infer operator mappings keys
+during |MiniOperators.setup()|. See |MiniOperators-mappings|.
+
+`replace.reindent_linewise` is a boolean indicating whether newly put linewise
+text should preserve indent of replaced text.
+
+# Sort ~
+
+`sort.prefix` is a string used to automatically infer operator mappings keys
+during |MiniOperators.setup()|. See |MiniOperators-mappings|.
+
+`sort.func` is a function used to actually sort text region.
+If `nil` (default), |MiniOperators.default_sort_func()| is used.
+
+Takes content table as input (see "Evaluate" section) and should return
+array of lines as output.
+
+Example of `sort.func` which asks user for custom delimiter for charwise region: >lua
+
+  local sort_func = function(content)
+    local opts = {}
+    if content.submode == 'v' then
+      -- Ask for delimiter to be treated as is (not as Lua pattern)
+      local delimiter = vim.fn.input('Sort delimiter: ')
+      -- Treat surrounding whitespace as part of split
+      opts.split_patterns = { '%s*' .. vim.pesc(delimiter) .. '%s*' }
+    end
+    return MiniOperators.default_sort_func(content, opts)
+  end
+
+  require('mini.operators').setup({ sort = { func = sort_func } })
+<
+------------------------------------------------------------------------------
+                                                      *MiniOperators.evaluate()*
+                        `MiniOperators.evaluate`({mode})
+Evaluate text and replace with output
+
+It replaces the region with the output of `config.evaluate.func`.
+By default it is |MiniOperators.default_evaluate_func()| which evaluates
+text as Lua code depending on the region submode.
+
+Parameters ~
+{mode} `(string|nil)` One of `nil`, `'char'`, `'line'`, `'block'`, `'visual'`.
+
+------------------------------------------------------------------------------
+                                                      *MiniOperators.exchange()*
+                        `MiniOperators.exchange`({mode})
+Exchange text regions
+
+Has two-step logic:
+- First call remembers the region as the one to be exchanged and highlights it
+  with `MiniOperatorsExchangeFrom` highlight group.
+- Second call performs the exchange. Basically, a two substeps action:
+  "yank both regions" and replace each one with another.
+
+Notes:
+- Use `<C-c>` to stop exchanging after the first step.
+
+- Exchanged regions can have different (char,line,block)-wise submodes.
+
+- Works with most cases of intersecting regions, but not officially supported.
+
+Parameters ~
+{mode} `(string|nil)` One of `nil`, `'char'`, `'line'`, `'block'`, `'visual'`.
+
+------------------------------------------------------------------------------
+                                                      *MiniOperators.multiply()*
+                        `MiniOperators.multiply`({mode})
+Multiply (duplicate) text
+
+Copies a region (without affecting registers) and puts it directly after.
+
+Notes:
+- Supports two types of |[count]|: `[count1]gm[count2][textobject]` with default
+  `config.multiply.prefix` makes `[count1]` copies of region defined by
+  `[count2][textobject]`. Example: `2gm3aw` - 2 copies of `3aw`.
+
+- |[count]| for "line" mapping (`gmm` by default) is treated as `[count1]` from
+  previous note.
+
+- Advantages of using this instead of "yank" + "paste":
+   - Doesn't modify any register, while separate steps need some register to
+     hold multiplied text.
+   - In most cases separate steps would be "yank" + "move cursor" + "paste",
+     while "multiply" makes it at once.
+
+Parameters ~
+{mode} `(string|nil)` One of `nil`, `'char'`, `'line'`, `'block'`, `'visual'`.
+
+------------------------------------------------------------------------------
+                                                       *MiniOperators.replace()*
+                        `MiniOperators.replace`({mode})
+Replace text with register
+
+Notes:
+- Supports two types of |[count]|: `[count1]gr[count2][textobject]` with default
+  `config.replace.prefix` puts `[count1]` contents of register over region defined
+  by `[count2][textobject]`. Example: `2gr3aw` - 2 register contents over `3aw`.
+
+- |[count]| for "line" mapping (`grr` by default) is treated as `[count1]` from
+  previous note.
+
+- Advantages of using this instead of "visually select" + "paste with |v_P|":
+   - As operator it is dot-repeatable which has cumulative gain in case of
+     multiple replacing is needed.
+   - Can automatically reindent.
+
+Parameters ~
+{mode} `(string|nil)` One of `nil`, `'char'`, `'line'`, `'block'`, `'visual'`.
+
+------------------------------------------------------------------------------
+                                                          *MiniOperators.sort()*
+                          `MiniOperators.sort`({mode})
+Sort text
+
+It replaces the region with the output of `config.sort.func`.
+By default it is |MiniOperators.default_sort_func()| which sorts the text
+depending on submode.
+
+Notes:
+- "line" mapping is charwise (as there is not much sense in sorting
+  linewise a single line). This also results into no |[count]| support.
+
+Parameters ~
+{mode} `(string|nil)` One of `nil`, `'char'`, `'line'`, `'block'`, `'visual'`.
+
+------------------------------------------------------------------------------
+                                                 *MiniOperators.make_mappings()*
+           `MiniOperators.make_mappings`({operator_name}, {lhs_tbl})
+Make operator mappings
+
+Parameters ~
+{operator_name} `(string)` Name of existing operator from this module.
+{lhs_tbl} `(table)` Table with mappings keys. Should have these fields:
+  - <textobject> `(string)` - Normal mode mapping to operate on textobject.
+  - <line> `(string)` - Normal mode mapping to operate on line.
+    Usually an alias for textobject mapping followed by |_|.
+    For "sort" it operates charwise on whole line without left and right
+    whitespace (as there is not much sense in sorting linewise a single line).
+  - <selection> `(string)` - Visual mode mapping to operate on selection.
+
+  Supply empty string to not create particular mapping. Note: creating `line`
+  mapping needs `textobject` mapping to be set.
+
+Usage ~
+>lua
+  require('mini.operators').make_mappings(
+    'replace',
+    { textobject = 'cr', line = 'crr', selection = 'cr' }
+  )
+<
+------------------------------------------------------------------------------
+                                         *MiniOperators.default_evaluate_func()*
+                `MiniOperators.default_evaluate_func`({content})
+Default evaluate function
+
+Evaluate text as Lua code and return object from last line (like if last
+line is prepended with `return` if it is not already).
+
+Behavior depends on region submode:
+
+- For charwise and linewise regions, text evaluated as is.
+
+- For blockwise region, lines are evaluated per line using only first lines
+  of outputs. This allows separate execution of lines in order to provide
+  something different compared to linewise region.
+
+Parameters ~
+{content} `(table)` Table with the following fields:
+  - <lines> `(table)` - array with content lines.
+  - <submode> `(string)` - region submode. One of `'v'`, `'V'`, `'<C-v>'` (escaped).
+
+------------------------------------------------------------------------------
+                                             *MiniOperators.default_sort_func()*
+              `MiniOperators.default_sort_func`({content}, {opts})
+Default sort function
+
+Sort text based on region submode:
+
+- For charwise region, split by separator pattern, sort parts, merge back
+  with separators. Actual pattern is inferred based on the array of patterns
+  from `opts.split_patterns`: whichever element is present in the text is
+  used, preferring the earlier one if several are present.
+  Example: sorting "c, b; a" line with default `opts.split_patterns` results
+  into "b; a, c" as it is split only by comma.
+
+- For linewise and blockwise regions sort lines as is.
+
+Notes:
+- Sort is done with |table.sort()| on an array of lines, which doesn't treat
+  whitespace or digits specially. Use |:sort| for more complicated tasks.
+
+- Pattern is allowed to be an empty string in which case split results into
+  all characters as parts.
+
+- Pad pattern in `split_patterns` with `%s*` to include whitespace into separator.
+  Example: line "b _ a" with "_" pattern will be sorted as " a_b " (because
+  it is split as "b ", "_", " a" ) while with `%s*_%s*` pattern it results
+  into "a _ b" (split as "b", " _ ", "a").
+
+Parameters ~
+{content} `(table)` Table with the following fields:
+  - <lines> `(table)` - array with content lines.
+  - <submode> `(string)` - region submode. One of `'v'`, `'V'`, `'<C-v>'` (escaped).
+{opts} `(table|nil)` Options. Possible fields:
+  - <compare_fun> `(function)` - compare function compatible with |table.sort()|.
+    Default: direct compare with `<`.
+  - <split_patterns> `(table)` - array of split Lua patterns to be used for
+    charwise submode. Order is important.
+    Default: `{ '%s*,%s*', '%s*;%s*', '%s+', '' }`.
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: