retrovim 0.0.3

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

@@ -0,0 +1,889 @@
+*mini.ai* Extend and create a/i textobjects
+
+MIT License Copyright (c) 2022 Evgeni Chasnovski
+
+------------------------------------------------------------------------------
+                                                                        *MiniAi*
+Enhance some builtin |text-objects| (like |a(|, |a)|, |a'|, and more),
+create new ones (like `a*`, `a<Space>`, `af`, `a?`, and more), and allow
+user to create their own.
+
+Features:
+- Customizable creation of `a`/`i` textobjects using Lua patterns and functions.
+  Supports:
+    - Dot-repeat.
+    - |v:count|.
+    - Different search methods (see |MiniAi.config|).
+    - Consecutive application (update selection without leaving Visual mode).
+    - Aliases for multiple textobjects.
+
+- Comprehensive builtin textobjects (see more in |MiniAi-builtin-textobjects|):
+    - Balanced brackets (with and without whitespace) plus alias.
+    - Balanced quotes plus alias.
+    - Function call.
+    - Argument.
+    - Tag.
+    - Derived from user prompt.
+    - Default for anything but Latin letters (to fall back to |text-objects|).
+
+    For more textobjects see |MiniExtra.gen_ai_spec|.
+
+- Motions for jumping to left/right edge of textobject.
+
+- Set of specification generators to tweak some builtin textobjects (see
+  |MiniAi.gen_spec|).
+
+- Treesitter textobjects (through |MiniAi.gen_spec.treesitter()| helper).
+
+This module works by defining mappings for both `a` and `i` in Visual and
+Operator-pending mode. After typing, they wait for single character user input
+treated as textobject identifier and apply resolved textobject specification
+(fall back to other mappings if can't find proper textobject id). For more
+information see |MiniAi-textobject-specification| and |MiniAi-algorithm|.
+
+Known issues which won't be resolved:
+- Search for builtin textobjects is done mostly using Lua patterns
+  (regex-like approach). Certain amount of false positives is to be expected.
+
+- During search for builtin textobjects there is no distinction if it is
+  inside string or comment. For example, in the following case there will
+  be wrong match for a function call: `f(a = ")", b = 1)`.
+
+General rule of thumb: any instrument using available parser for document
+structure (like treesitter) will usually provide more precise results. This
+module has builtins mostly for plain text textobjects which are useful
+most of the times (like "inside brackets", "around quotes/underscore", etc.).
+For advanced use cases define function specification for custom textobjects.
+
+What it doesn't (and probably won't) do:
+- Have special operators to specially handle whitespace (like `I` and `A`
+  in `wellle/targets.vim`). Whitespace handling is assumed to be done inside
+  textobject specification (like `i(` and `i)` handle whitespace differently).
+
+# Setup ~
+
+This module needs a setup with `require('mini.ai').setup({})` (replace
+`{}` with your `config` table). It will create global Lua table `MiniAi`
+which you can use for scripting or manually (with `:lua MiniAi.*`).
+
+See |MiniAi.config| for available config settings.
+
+You can override runtime config settings (like `config.custom_textobjects`)
+locally to buffer inside `vim.b.miniai_config` which should have same structure
+as `MiniAi.config`. See |mini.nvim-buffer-local-config| for more details.
+
+To stop module from showing non-error feedback, set `config.silent = true`.
+
+# Comparisons ~
+
+- [wellle/targets.vim](https://github.com/wellle/targets.vim):
+    - Has limited support for creating own textobjects: it is constrained
+      to pre-defined detection rules. |mini.ai| allows creating own rules
+      via Lua patterns and functions (see |MiniAi-textobject-specification|).
+    - Doesn't provide any programmatical API for getting information about
+      textobjects. |mini.ai| does it via |MiniAi.find_textobject()|.
+    - Has no implementation of "moving to edge of textobject". |mini.ai|
+      does it via |MiniAi.move_cursor()| and `g[` and `g]` default mappings.
+    - Both implement the notion of manual "next"/"last" search directions.
+    - Implements `A`, `I` operators. |mini.ai| does not by design: it is
+      assumed to be a property of textobject, not operator.
+    - Doesn't implement "function call" and "user prompt" textobjects.
+      |mini.ai| does (with `f` and `?` identifiers).
+    - Has limited support for "argument" textobject. Although it works in
+      most situations, it often misdetects commas as argument separator
+      (like if it is inside quotes or `{}`). |mini.ai| deals with these cases.
+- [nvim-treesitter/nvim-treesitter-textobjects](https://github.com/nvim-treesitter/nvim-treesitter-textobjects):
+    - Along with textobject functionality provides a curated and maintained
+      set of popular textobject queries for many languages (which can power
+      |MiniAi.gen_spec.treesitter()| functionality).
+    - Both support working with |treesitter-directives| allowing more
+      fine-tuned textobjects.
+    - Implements only textobjects based on treesitter.
+    - Doesn't support |v:count|.
+    - Doesn't support multiple search method (basically, only `'cover'`).
+    - Doesn't support consecutive application of target textobject.
+
+# Disabling ~
+
+To disable, set `vim.g.miniai_disable` (globally) or `vim.b.miniai_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.
+
+------------------------------------------------------------------------------
+                                                    *MiniAi-builtin-textobjects*
+This table describes all builtin textobjects along with what they
+represent. Explanation:
+- `Key` represents the textobject identifier: single character which should
+  be typed after `a`/`i`.
+- `Name` is a description of textobject.
+- `Example line` contains a string for which examples are constructed. The
+  `*` denotes the cursor position.
+- `a`/`i` describe inclusive region representing `a` and `i` textobjects.
+  Use numbers in separators for easier navigation.
+- `2a`/`2i` describe either `2a`/`2i` (support for |v:count|) textobjects
+  or `a`/`i` textobject followed by another `a`/`i` textobject (consecutive
+  application leads to incremental selection).
+
+Example: typing `va)` with cursor on `*` leads to selection from column 2
+to column 12. Another typing `a)` changes selection to [1; 13]. Also, besides
+visual selection, any |operator| can be used or `g[`/`g]` motions to move
+to left/right edge of `a` textobject.
+>
+ ┌───┬───────────────┬──────────────────┬────────┬────────┬────────┬────────┐
+ │Key│     Name      │   Example line   │   a    │   i    │   2a   │   2i   │
+ ├───┴───────────────┴──────────────────┴────────┴────────┴────────┴────────┤
+ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈1234567890123456┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
+ │ ( │  Balanced ()  │ (( *a (bb) ))    │        │        │        │        │
+ │ [ │  Balanced []  │ [[ *a [bb] ]]    │ [2;12] │ [4;10] │ [1;13] │ [2;12] │
+ │ { │  Balanced {}  │ {{ *a {bb} }}    │        │        │        │        │
+ │ < │  Balanced <>  │ << *a <bb> >>    │        │        │        │        │
+ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈1234567890123456┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
+ │ ) │  Balanced ()  │ (( *a (bb) ))    │        │        │        │        │
+ │ ] │  Balanced []  │ [[ *a [bb] ]]    │        │        │        │        │
+ │ } │  Balanced {}  │ {{ *a {bb} }}    │ [2;12] │ [3;11] │ [1;13] │ [2;12] │
+ │ > │  Balanced <>  │ << *a <bb> >>    │        │        │        │        │
+ │ b │  Alias for    │ [( *a {bb} )]    │        │        │        │        │
+ │   │  ), ], or }   │                  │        │        │        │        │
+ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈1234567890123456┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
+ │ " │  Balanced "   │ "*a" " bb "      │        │        │        │        │
+ │ ' │  Balanced '   │ '*a' ' bb '      │        │        │        │        │
+ │ ` │  Balanced `   │ `*a` ` bb `      │ [1;4]  │ [2;3]  │ [6;11] │ [7;10] │
+ │ q │  Alias for    │ '*a' " bb "      │        │        │        │        │
+ │   │  ", ', or `   │                  │        │        │        │        │
+ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈1234567890123456┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
+ │ ? │  User prompt  │ e*e o e o o      │ [3;5]  │ [4;4]  │ [7;9]  │ [8;8]  │
+ │   │(typed e and o)│                  │        │        │        │        │
+ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈1234567890123456┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
+ │ t │      Tag      │ <x><y>*a</y></x> │ [4;12] │ [7;8]  │ [1;16] │ [4;12] │
+ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈1234567890123456┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
+ │ f │ Function call │ f(a, g(*b, c) )  │ [6;13] │ [8;12] │ [1;15] │ [3;14] │
+ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈1234567890123456┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
+ │ a │   Argument    │ f(*a, g(b, c) )  │ [3;5]  │ [3;4]  │ [5;14] │ [7;13] │
+ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈1234567890123456┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
+ │   │    Default    │ aa_*b__cc___     │ [4;7]  │ [4;5]  │ [8;12] │ [8;9]  │
+ │   │   (typed _)   │                  │        │        │        │        │
+ └───┴───────────────┴──────────────────┴────────┴────────┴────────┴────────┘
+<
+Notes:
+- All examples assume default `config.search_method`.
+- Open brackets differ from close brackets by how they treat inner edge
+  whitespace for `i` textobject: open ignores it, close - includes.
+- Default textobject is activated for identifiers which are not Latin letters.
+  They are designed to be treated as separators, so include only right edge
+  in `a` textobject. To include both edges, use custom textobjects
+  (see |MiniAi-textobject-specification| and |MiniAi.config|). Note:
+    - When cursor is exactly on the identifier character while there are
+      two matching candidates on both left and right, the resulting region
+      with smaller width is preferred.
+
+------------------------------------------------------------------------------
+                                                               *MiniAi-glossary*
+Note: this is similar to |MiniSurround-glossary|.
+
+REGION ~
+Table representing region in a buffer. Fields:
+- <from> and <to> for inclusive start and end positions (<to> might be
+  `nil` to describe empty region). Each position is also a table with
+  line <line> and column <col> (both start at 1).
+- <vis_mode> for which Visual mode will be used to select textobject.
+  See `opts` argument of |MiniAi.select_textobject()|.
+  One of `'v'`, `'V'`, `'\22'` (escaped `'<C-v>'`).
+
+Examples: >lua
+
+  { from = { line = 1, col = 1 }, to = { line = 2, col = 1 } }
+
+  -- Forced linewise mode
+  {
+    from = { line = 1, col = 1 }, to = { line = 2, col = 1 },
+    vis_mode = 'V',
+  }
+
+  -- Empty region
+  { from = { line = 10, col = 10 } }
+<
+PATTERN ~
+String describing Lua pattern.
+
+SPAN ~
+Interval inside a string (end-exclusive). Like [1, 5). Equal `from` and `to` edges
+describe empty span at that point.
+
+Span `A = [a1, a2)` covers `B = [b1, b2)` if every element of `B` is within
+`A` (`a1 <= b < a2`). It also is described as "B is nested inside A".
+
+NESTED PATTERN ~
+Array of patterns aimed to describe nested spans.
+
+SPAN MATCHES NESTED PATTERN ~
+If there is a sequence of consecutively nested spans each matching
+corresponding pattern within substring of previous span (or input string
+for first span). Example: >lua
+
+  -- Nested patterns for balanced `()` with inner space
+  { '%b()', '^. .* .$' }
+
+  -- Example input string (with columns underneath for easier reading):
+     "( ( () ( ) ) )"
+  --  12345678901234
+<
+Here are all matching spans [1, 15) and [3, 13). Both [5, 7) and [8, 10)
+match first pattern but not second. All other combinations of `(` and `)`
+don't match first pattern (not balanced).
+
+COMPOSED PATTERN ~
+Array with each element describing possible pattern (or array of them) at
+that place. Composed pattern basically defines all possible combinations of
+nested pattern (their cartesian product). Examples:
+
+1. Either balanced `()` or balanced `[]` but both with inner edge space: >lua
+
+    -- Composed pattern
+    { { '%b()', '%b[]' }, '^. .* .$' }
+
+    -- Composed pattern expanded into equivalent array of nested patterns
+    { '%b()', '^. .* .$' } -- and
+    { '%b[]', '^. .* .$' }
+<
+2. Either "balanced `()` with inner edge space" or "balanced `[]` with no
+   inner edge space", both with 5 or more characters: >lua
+
+    -- Composed pattern
+    { { { '%b()', '^. .* .$' }, { '%b[]', '^.[^ ].*[^ ].$' } }, '.....' }
+
+    -- Composed pattern expanded into equivalent array of nested patterns
+    { '%b()', '^. .* .$', '.....' } -- and
+    { '%b[]', '^.[^ ].*[^ ].$', '.....' }
+<
+SPAN MATCHES COMPOSED PATTERN ~
+If it matches at least one nested pattern from expanded composed pattern.
+
+------------------------------------------------------------------------------
+                                               *MiniAi-textobject-specification*
+Textobject specification has a structure of composed pattern (see
+|MiniAi-glossary|) with two differences:
+- Last pattern(s) should have even number of empty capture groups denoting
+  how the last string should be processed to extract `a` or `i` textobject:
+    - Zero captures mean that whole string represents both `a` and `i`.
+      Example: `xxx` will define textobject matching string `xxx` literally.
+    - Two captures represent `i` textobject inside of them. `a` - whole string.
+      Example: `x()x()x` defines `a` textobject to be `xxx`, `i` - middle `x`.
+    - Four captures define `a` textobject inside captures 1 and 4, `i` -
+      inside captures 2 and 3. Example: `x()()x()x()` defines `a`
+      textobject to be last `xx`, `i` - middle `x`.
+- Allows callable objects (see |vim.is_callable()|) in certain places
+  (enables more complex textobjects in exchange of increase in configuration
+  complexity and computations):
+    - If specification itself is a callable, it will be called with the same
+      arguments as |MiniAi.find_textobject()| and should return one of:
+        - Composed pattern. Useful for implementing user input. Example of
+          simplified variant of textobject for function call with name taken
+          from user prompt: >lua
+
+            function()
+              local left_edge = vim.pesc(vim.fn.input('Function name: '))
+              return { left_edge .. '%b()', '^.-%(().*()%)$' }
+            end
+<
+        - Single output region. Useful to allow full control over
+          textobject. Will be taken as is. Example of returning whole buffer: >lua
+
+            function()
+              local from = { line = 1, col = 1 }
+              local to = {
+                line = vim.fn.line('$'),
+                col = math.max(vim.fn.getline('$'):len(), 1)
+              }
+              return { from = from, to = to, vis_mode = 'V' }
+            end
+<
+        - Array of output region(s). Useful for incorporating other
+          instruments, like treesitter (see |MiniAi.gen_spec.treesitter()|).
+          The best region will be picked in the same manner as with composed
+          pattern (respecting options `n_lines`, `search_method`, etc.).
+          Example of selecting "best" line with display width more than 80: >lua
+
+            function(_, _, _)
+              local res = {}
+              for i = 1, vim.api.nvim_buf_line_count(0) do
+                local cur_line = vim.fn.getline(i)
+                if vim.fn.strdisplaywidth(cur_line) > 80 then
+                  local region = {
+                    from = { line = i, col = 1 },
+                    to = { line = i, col = cur_line:len() },
+                  }
+                  table.insert(res, region)
+                end
+              end
+              return res
+            end
+<
+    - If there is a callable instead of assumed string pattern, it is expected
+      to have signature `(line, init)` and behave like `pattern:find()`.
+      It should return two numbers representing span in `line` next after
+      or at `init` (`nil` if there is no such span).
+      !IMPORTANT NOTE!: it means that output's `from` shouldn't be strictly
+      to the left of `init` (it will lead to infinite loop). Not allowed as
+      last item (as it should be pattern with captures).
+      Example of matching only balanced parenthesis with big enough width: >lua
+
+        {
+          '%b()',
+          function(s, init)
+            if init > 1 or s:len() < 5 then return end
+            return 1, s:len()
+          end,
+          '^.().*().$'
+        }
+<
+More examples: >lua
+
+  -- Pair of balanced brackets from set (used for builtin `b` identifier):
+  { { '%b()', '%b[]', '%b{}' }, '^.().*().$' }
+
+  -- Imitate word ignoring digits and punctuation (only for Latin alphabet):
+  { '()()%f[%w]%w+()[ \t]*()' }
+
+  -- Word with camel case support (also supports only Latin alphabet):
+  {
+    {
+      '%u[%l%d]+%f[^%l%d]',
+      '%f[%S][%l%d]+%f[^%l%d]',
+      '%f[%P][%l%d]+%f[^%l%d]',
+      '^[%l%d]+%f[^%l%d]',
+    },
+    '^().*()$'
+  }
+
+  -- Number:
+  { '%f[%d]%d+' }
+
+  -- Date in 'YYYY-MM-DD' format:
+  { '()%d%d%d%d%-%d%d%-%d%d()' }
+
+  -- Lua block string:
+  { '%[%[().-()%]%]' }
+<
+See |MiniAi.gen_spec| for function wrappers to create commonly used
+textobject specifications.
+
+------------------------------------------------------------------------------
+                                                              *MiniAi-algorithm*
+Search for the textobjects relies on these principles:
+- It uses same input data as described in |MiniAi.find_textobject()|,
+  i.e. whether it is `a` or `i` textobject, its identifier, reference region, etc.
+- Textobject specification is constructed based on textobject identifier
+  (see |MiniAi-textobject-specification|).
+- General search is done by converting some 2d buffer region (neighborhood
+  of reference region) into 1d string (each line is appended with `\n`).
+  Then search for a best span matching textobject specification is done
+  inside string (see |MiniAi-glossary|). After that, span is converted back
+  into 2d region. Note: first search is done inside reference region lines,
+  and only after that - inside its neighborhood within `config.n_lines`
+  (see |MiniAi.config|).
+- The best matching span is chosen by iterating over all spans matching
+  textobject specification and comparing them with "current best".
+  Comparison also depends on reference region (tighter covering is better,
+  otherwise closer is better) and search method (if span is even considered).
+- Extract span based on extraction pattern (last item in nested pattern).
+- If task is to perform a consecutive search (`opts.n_times` is greater than 1),
+  steps are repeated with current best match becoming reference region.
+  One such additional step is also done if final region is equal to
+  reference region (this enables consecutive application).
+
+Notes:
+- Iteration over all matched spans is done in depth-first fashion with
+  respect to nested pattern.
+- It is guaranteed that span is compared only once.
+- For the sake of increasing functionality, during iteration over all
+  matching spans, some Lua patterns in composed pattern are handled
+  specially.
+    - `%bxx` (`xx` is two identical characters). It denotes balanced pair
+      of identical characters and results into "paired" matches. For
+      example, `%b""` for `"aa" "bb"` would match `"aa"` and `"bb"`, but
+      not middle `" "`.
+    - `x.-y` (`x` and `y` are different strings). It results only in matches with
+      smallest width. For example, `e.-o` for `e e o o` will result only in
+      middle `e o`. Note: it has some implications for when parts have
+      quantifiers (like `+`, etc.), which usually can be resolved with
+      frontier pattern `%f[]` (see examples in |MiniAi-textobject-specification|).
+
+------------------------------------------------------------------------------
+                                                                *MiniAi.setup()*
+                            `MiniAi.setup`({config})
+Module setup
+
+Parameters ~
+{config} `(table|nil)` Module config table. See |MiniAi.config|.
+
+Usage ~
+>lua
+  require('mini.ai').setup() -- use default config
+  -- OR
+  require('mini.ai').setup({}) -- replace {} with your config table
+<
+------------------------------------------------------------------------------
+                                                                 *MiniAi.config*
+                                `MiniAi.config`
+Defaults ~
+>lua
+  MiniAi.config = {
+    -- Table with textobject id as fields, textobject specification as values.
+    -- Also use this to disable builtin textobjects. See |MiniAi.config|.
+    custom_textobjects = nil,
+
+    -- Module mappings. Use `''` (empty string) to disable one.
+    mappings = {
+      -- Main textobject prefixes
+      around = 'a',
+      inside = 'i',
+
+      -- Next/last textobjects
+      -- NOTE: This (deliberately) overrides Neovim>=0.12 built-in incremental
+      -- selection mappings. See `:h MiniAi-default-an-in` for more details.
+      around_next = 'an',
+      inside_next = 'in',
+      around_last = 'al',
+      inside_last = 'il',
+
+      -- Move cursor to corresponding edge of `a` textobject
+      goto_left = 'g[',
+      goto_right = 'g]',
+    },
+
+    -- Number of lines within which textobject is searched
+    n_lines = 50,
+
+    -- How to search for object (first inside current line, then inside
+    -- neighborhood). One of 'cover', 'cover_or_next', 'cover_or_prev',
+    -- 'cover_or_nearest', 'next', 'prev', 'nearest'.
+    search_method = 'cover_or_next',
+
+    -- Whether to disable showing non-error feedback
+    -- This also affects (purely informational) helper messages shown after
+    -- idle time if user input is required.
+    silent = false,
+  }
+<
+# Custom textobjects ~
+
+User can define own textobjects by supplying `config.custom_textobjects`.
+It should be a table with keys being single character textobject identifier
+(supported by |getcharstr()|, except <Esc> and <C-c> which are used to cancel)
+and values - textobject specification (see |MiniAi-textobject-specification|).
+
+General recommendations:
+- This can be used to override builtin ones (|MiniAi-builtin-textobjects|).
+  Supply non-valid input (not in specification format) to disable module's
+  builtin textobject in favor of external or Neovim's builtin mapping.
+- Keys should use character representation which can be |getcharstr()| output.
+  For example, `'\r'` and not `'<CR>'`.
+
+Examples:
+>lua
+  require('mini.ai').setup({
+    custom_textobjects = {
+      -- Tweak argument textobject
+      a = require('mini.ai').gen_spec.argument({ brackets = { '%b()' } }),
+
+      -- Disable brackets alias in favor of builtin block textobject
+      b = false,
+
+      -- Now `vax` should select `xxx` and `vix` - middle `x`
+      x = { 'x()x()x' },
+
+      -- Whole buffer
+      g = function()
+        local from = { line = 1, col = 1 }
+        local to = {
+          line = vim.fn.line('$'),
+          col = math.max(vim.fn.getline('$'):len(), 1)
+        }
+        return { from = from, to = to }
+      end
+    }
+  })
+
+  -- Use `vim.b.miniai_config` to customize per buffer
+  -- Example of specification useful for Markdown files:
+  local spec_pair = require('mini.ai').gen_spec.pair
+  vim.b.miniai_config = {
+    custom_textobjects = {
+      ['*'] = spec_pair('*', '*', { type = 'greedy' }),
+      ['_'] = spec_pair('_', '_', { type = 'greedy' }),
+    },
+  }
+<
+There are more example specifications in |MiniAi-textobject-specification|.
+
+# Search method ~
+
+Value of `config.search_method` defines how best match search is done.
+Based on its value, one of the following matches will be selected:
+- Covering match. Left/right edge is before/after left/right edge of
+  reference region.
+- Previous match. Left/right edge is before left/right edge of reference
+  region.
+- Next match. Left/right edge is after left/right edge of reference region.
+- Nearest match. Whichever is closest among previous and next matches.
+
+Possible values are:
+- `'cover'` - use only covering match. Don't use either previous or
+  next; report that there is no textobject found.
+- `'cover_or_next'` (default) - use covering match. If not found, use next.
+- `'cover_or_prev'` - use covering match. If not found, use previous.
+- `'cover_or_nearest'` - use covering match. If not found, use nearest.
+- `'next'` - use next match.
+- `'prev'` - use previous match.
+- `'nearest'` - use nearest match.
+
+Note: search is first performed on the reference region lines and only
+after failure - on the whole neighborhood defined by `config.n_lines`. This
+means that with `config.search_method` not equal to `'cover'`, "prev" or
+"next" textobject will end up as search result if they are found on first
+stage although covering match might be found in bigger, whole neighborhood.
+This design is based on observation that most of the time operation is done
+within reference region lines (usually cursor line).
+
+Here is an example of what `a)` textobject is based on a value of
+`'config.search_method'` when cursor is inside `bbb` word:
+- `'cover'`:         `(a) bbb (c)` -> none
+- `'cover_or_next'`: `(a) bbb (c)` -> `(c)`
+- `'cover_or_prev'`: `(a) bbb (c)` -> `(a)`
+- `'cover_or_nearest'`: depends on cursor position.
+  For first and second `b` - as in `cover_or_prev` (as previous match is
+  nearer), for third - as in `cover_or_next` (as next match is nearer).
+- `'next'`: `(a) bbb (c)` -> `(c)`. Same outcome for `(bbb)`.
+- `'prev'`: `(a) bbb (c)` -> `(a)`. Same outcome for `(bbb)`.
+- `'nearest'`: depends on cursor position (same as in `'cover_or_nearest'`).
+
+# Mappings ~
+
+Mappings `around_next` / `inside_next` and `around_last` / `inside_last` are
+essentially `around` / `inside` but using search method `'next'` and `'prev'`.
+
+## Overriding default `an` and `in` ~
+*MiniAi-default-an-in*
+
+Default `around_next` / `inside_next` mappings override newly added in Neovim=0.12
+built-in mappings |v_an| and |v_in|. This is intentional for better usability
+and backwards compatibility. There are several ways to work around this:
+
+- Remap Neovim's `an` / `in` to something else before calling |MiniAi.setup()|: >lua
+
+    -- Use `<Leader>ls` and `<Leader>lS` for incremental selection
+    local copy_keymap = function(mode, from_lhs, to_lhs)
+      local keymap = vim.fn.maparg(from_lhs, mode, false, true)
+      local rhs = keymap.callback or keymap.rhs
+      vim.keymap.set(mode, to_lhs, rhs, { desc = keymap.desc })
+    end
+    copy_keymap('x', 'an', '<Leader>ls')
+    copy_keymap('x', 'in', '<Leader>lS')
+
+    -- ...
+    require('mini.ai').setup({...})
+<
+- Use |MiniAi.gen_spec.treesitter()| with one or many captures for versatile
+  tree-sitter based textobjects. It also allows consecutive application in
+  Visual mode: similar to incremental selection, with `next` / `last` variants,
+  but without "decrease selection".
+
+- Use other values for "next" / "last" variants. For example: >lua
+
+  require('mini.ai').setup({
+    mappings = {
+      around_next = 'aN',
+      inside_next = 'iN',
+      around_last = 'aL',
+      inside_last = 'iL',
+    }
+  })
+<
+## Overriding default `al` and `il` ~
+*MiniAi-default-al-il*
+
+Default `around_last` / `inside_last` mappings override newly added in Neovim=0.13
+built-in mappings |al| and |il|. This is intentional for better usability
+and backwards compatibility. There are several ways to work around this:
+
+- Use |MiniExtra.gen_ai_spec.buffer()| and |MiniExtra.gen_ai_spec.line()| to
+  create custom textobjects for buffer and line: >lua
+
+    require('mini.extra').setup()
+    require('mini.ai').setup({
+      custom_textobjects = {
+        -- Makes `aB` equivalent to built-in `al`
+        B = MiniExtra.gen_ai_spec.buffer(),
+        -- Makes `iL` equivalent to built-in `il`
+        L = MiniExtra.gen_ai_spec.line(),
+      },
+    })
+<
+- Use other values for "next" / "last" variants. See |MiniAi-default-an-in|.
+
+------------------------------------------------------------------------------
+                                                      *MiniAi.find_textobject()*
+               `MiniAi.find_textobject`({ai_type}, {id}, {opts})
+Find textobject region
+
+Parameters ~
+{ai_type} `(string)` One of `'a'` or `'i'`.
+{id} `(string)` Single character string representing textobject id. It is
+  used to get specification which is later used to compute textobject region.
+  Note: if specification is a function, it is called with all present
+  arguments (`opts` is populated with default arguments).
+{opts} `(table|nil)` Options. Possible fields:
+  - <n_lines> - Number of lines within which textobject is searched.
+    Default: `config.n_lines` (see |MiniAi.config|).
+  - <n_times> - Number of times to perform a consecutive search. Each one
+    is done with reference region being previous found textobject region.
+    Default: 1.
+  - <reference_region> - region to try to cover (see |MiniAi-glossary|). It
+    is guaranteed that output region will not be inside or equal to this one.
+    Default: empty region at cursor position.
+  - <search_method> - Search method. Default: `config.search_method`.
+
+Return ~
+`(table|nil)` Region of textobject or `nil` if no textobject different
+  from `opts.reference_region` was consecutively found `opts.n_times` times.
+
+------------------------------------------------------------------------------
+                                                          *MiniAi.move_cursor()*
+             `MiniAi.move_cursor`({side}, {ai_type}, {id}, {opts})
+Move cursor to edge of textobject
+
+Parameters ~
+{side} `(string)` One of `'left'` or `'right'`.
+{ai_type} `(string)` One of `'a'` or `'i'`.
+{id} `(string)` Single character string representing textobject id.
+{opts} `(table|nil)` Same as in |MiniAi.find_textobject()|.
+  `opts.n_times` means number of actual jumps (important when cursor
+  already on the potential jump spot).
+
+------------------------------------------------------------------------------
+                                                               *MiniAi.gen_spec*
+                               `MiniAi.gen_spec`
+Generate common textobject specifications
+
+This is a table with function elements. Call to actually get specification.
+
+Example: >lua
+
+  local gen_spec = require('mini.ai').gen_spec
+  require('mini.ai').setup({
+    custom_textobjects = {
+      -- Tweak argument to be recognized only inside `()` between `;`
+      a = gen_spec.argument({ brackets = { '%b()' }, separator = ';' }),
+
+      -- Tweak function call to not detect dot in function name
+      f = gen_spec.function_call({ name_pattern = '[%w_]' }),
+
+      -- Function definition (needs treesitter queries with these captures)
+      F = gen_spec.treesitter({ a = '@function.outer', i = '@function.inner' }),
+
+      -- Make `|` select both edges in non-balanced way
+      ['|'] = gen_spec.pair('|', '|', { type = 'non-balanced' }),
+    }
+  })
+<
+------------------------------------------------------------------------------
+                                                    *MiniAi.gen_spec.argument()*
+                       `MiniAi.gen_spec.argument`({opts})
+Argument specification
+
+Argument textobject (has default `a` identifier) is a region inside
+balanced bracket between allowed not excluded separators. Use this function
+to tweak how it works.
+
+Examples:
+- `argument({ brackets = { '%b()' } })` will search for an argument only
+  inside balanced `()`.
+- `argument({ separator = '[,;]' })` will treat both `,` and `;` as separators.
+- `argument({ exclude_regions = { '%b()' } })` will exclude separators
+  which are inside balanced `()` (inside outer brackets).
+
+Parameters ~
+{opts} `(table|nil)` Options. Allowed fields:
+  - <brackets> - array of patterns for outer balanced brackets.
+    Default: `{ '%b()', '%b[]', '%b{}' }` (any `()`, `[]`, or `{}` can
+    enclose arguments).
+  - <separator> - separator pattern. Default: `','`.
+    One of the practical usages of this option is to include whitespace
+    around character to be a part of separator. For example, `'%s*,%s*'`
+    will treat as separator not only `,`, but its possible surrounding
+    whitespace. This has both positive and negative effects. On one hand,
+    `daa` executed over the first argument will delete whitespace after
+    first comma, leading to a more expected outcome. On the other hand it
+    is ambiguous which argument is picked when cursor is over whitespace
+    near the character separator.
+  - <exclude_regions> - array with patterns for regions inside which
+    separators will be ignored.
+    Default: `{ '%b""', "%b''", '%b()', '%b[]', '%b{}' }` (separators
+    inside balanced quotes or brackets are ignored).
+
+------------------------------------------------------------------------------
+                                               *MiniAi.gen_spec.function_call()*
+                    `MiniAi.gen_spec.function_call`({opts})
+Function call specification
+
+Function call textobject (has default `f` identifier) is a region with some
+characters followed by balanced `()`. Use this function to tweak how it works.
+
+Example:
+- `function_call({ name_pattern = '[%w_]' })` will recognize function name with
+  only alphanumeric or underscore (not dot).
+
+Parameters ~
+{opts} `(table|nil)` Options. Allowed fields:
+  - <name_pattern> - string pattern of character set allowed in function name.
+    Default: `'[%w_%.]'` (alphanumeric, underscore, or dot).
+    Note: should be enclosed in `[]`.
+
+------------------------------------------------------------------------------
+                                                        *MiniAi.gen_spec.pair()*
+                `MiniAi.gen_spec.pair`({left}, {right}, {opts})
+Pair specification
+
+Use it to define textobject for region surrounded with `left` from left and
+`right` from right. The `a` textobject includes both edges, `i` - excludes them.
+
+Region can be one of several types (controlled with `opts.type`). All
+examples are for default search method, `a` textobject, and use `'_'` as
+both `left` and `right`:
+- Non-balanced (`{ type = 'non-balanced' }`), default. Equivalent to using
+  `x.-y` as first pattern. Example: on line `_a_b_c_` it consecutively
+  matches `_a_`, `_b_`, `_c_`.
+- Balanced (`{ type = 'balanced' }`). Equivalent to using `%bxy` as first
+  pattern. Example: on line `_a_b_c_` it consecutively matches `_a_`, `_c_`.
+  Note: both `left` and `right` should be single character.
+- Greedy (`{ type = 'greedy' }`). Like non-balanced but will select maximum
+  consecutive `left` and `right` edges. Example: on line `__a__b_` it
+  consecutively selects `__a__` and `__b_`. Note: both `left` and `right`
+  should be single character.
+
+Parameters ~
+{left} `(string)` Left edge.
+{right} `(string)` Right edge.
+{opts} `(table|nil)` Options. Possible fields:
+  - <type> - Type of a pair. One of `'non-balanced'` (default), `'balanced'`,
+  `'greedy'`.
+
+------------------------------------------------------------------------------
+                                                  *MiniAi.gen_spec.treesitter()*
+              `MiniAi.gen_spec.treesitter`({ai_captures}, {opts})
+Treesitter specification
+
+This is a specification in function form. When called with a pair of
+treesitter captures, it returns a specification function outputting an
+array of regions that match corresponding (`a` or `i`) capture.
+
+In order for this to work, apart from working treesitter parser for desired
+language, user should have a reachable language-specific `'textobjects'`
+query (see |vim.treesitter.query.get()|).
+The most straightforward way for this is to have `textobjects.scm` query
+file with treesitter captures stored in some recognized path. This is
+primarily designed to be compatible with plugin
+`nvim-treesitter/nvim-treesitter-textobjects`, but can be used without it.
+
+Two most common approaches for having a query file:
+- Install `nvim-treesitter/nvim-treesitter-textobjects`. It has curated and
+  well maintained builtin query files for many languages with a standardized
+  capture names, like `function.outer`, `function.inner`, etc.
+- Manually create file `after/queries/<language-name>/textobjects.scm` in
+  your |$XDG_CONFIG_HOME| directory. It should contain queries with
+  captures (later used to define textobjects). See |lua-treesitter-query|.
+To verify that query file is reachable, run (example for "lua" language,
+output should have at least an intended file): >vim
+
+  :lua print(vim.inspect(vim.treesitter.query.get_files('lua','textobjects')))
+<
+Example configuration for function definition textobject with
+`nvim-treesitter/nvim-treesitter-textobjects` captures:
+>lua
+  local spec_treesitter = require('mini.ai').gen_spec.treesitter
+  require('mini.ai').setup({
+    custom_textobjects = {
+      F = spec_treesitter({ a = '@function.outer', i = '@function.inner' }),
+      o = spec_treesitter({
+        a = { '@conditional.outer', '@loop.outer' },
+        i = { '@conditional.inner', '@loop.inner' },
+      })
+    }
+  })
+<
+Notes:
+- Be sure that query files don't contain unknown |treesitter-directives|
+  (like `#make-range!`, for example). Otherwise textobject for such capture
+  might not be found as |lua-treesitter-core| won't treat them as captures.
+  Verify with `:=vim.treesitter.query.get('lang', 'textobjects')` and see
+  if the target capture is recognized as one.
+- It uses buffer's |filetype| to determine query language.
+- It first searches the language under cursor for matches. If no matches are
+  found, it falls back to searching parent languages (up to the buffer's root
+  language). If no matches are found again, it falls back to recursively
+  searching all children languages (from the language under cursor). If no
+  matches again - report no matches.
+- On large files it is slower than pattern-based textobjects. Still very
+  fast though (one search should be magnitude of milliseconds or tens of
+  milliseconds on really large file).
+
+Parameters ~
+{ai_captures} `(table)` Captures for `a` and `i` textobjects: table with
+  <a> and <i> fields with captures for `a` and `i` textobjects respectively.
+  Each value can be either a string capture (should start with `'@'`) or an
+  array of such captures (best among all matches will be chosen).
+{opts} `(table|nil)` Options. Possible values:
+  - <use_nvim_treesitter> - whether to try to use `nvim-treesitter` plugin
+    (if present) to do the query. It used to implement more advanced behavior
+    and more coherent experience if `nvim-treesitter-textobjects` queries are
+    used. However, as |lua-treesitter-core| methods are more capable now,
+    the option will soon be removed. Only present for backward compatibility.
+    Default: `false`.
+
+Return ~
+`(function)` Function with |MiniAi.find_textobject()| signature which
+  returns array of current buffer regions representing matches for
+  corresponding (`a` or `i`) treesitter capture.
+
+See also ~
+- |MiniAi-textobject-specification| for how this type of textobject
+  specification is processed.
+- |vim.treesitter.query.get()| for how query is fetched.
+- |Query:iter_captures()| for how all query captures are iterated in case of
+  no `nvim-treesitter`.
+
+------------------------------------------------------------------------------
+                                                 *MiniAi.gen_spec.user_prompt()*
+                        `MiniAi.gen_spec.user_prompt`()
+Specification from user prompt
+
+- Ask user for left and right textobject edges as raw strings (no pattern).
+  It uses |MiniInput.get()| (if enabled) or |input().
+- Construct specification for a textobject that matches from left edge string
+  to right edge string: `a` includes both strings, `i` only insides.
+
+Used for |MiniAi-builtin-textobjects| with identifier `?`.
+
+Return ~
+`(function)` Textobject specification as function.
+
+------------------------------------------------------------------------------
+                                                    *MiniAi.select_textobject()*
+              `MiniAi.select_textobject`({ai_type}, {id}, {opts})
+Visually select textobject region
+
+Does nothing if no region is found.
+
+Parameters ~
+{ai_type} `(string)` One of `'a'` or `'i'`.
+{id} `(string)` Single character string representing textobject id.
+{opts} `(table|nil)` Same as in |MiniAi.find_textobject()|. Extra fields:
+  - <vis_mode> - One of `'v'`, `'V'`, or `'\22'` (escaped version of `'<C-v>'`).
+    Default: Latest visual mode.
+  - <operator_pending> - Whether selection is for Operator-pending mode.
+    Used in that mode's mappings, shouldn't be used directly. Default: `false`.
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: