8000 mini.nvim/doc/mini-surround.txt at sync · vivi-et/mini.nvim · GitHub
[go: up one dir, main page]
Skip to content

mini-surround.txt

Latest commit

 

History

History
774 lines (680 loc) · 35.8 KB

mini-surround.txt

File metadata and controls

774 lines (680 loc) · 35.8 KB
Raw
- 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 surrounding 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.
- `'previous'` - 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'`, "previous"
or "next" surrounding 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 how replacing `)` with `]` surrounding is done based
on a value of `'config.search_method'` when cursor is inside `bbb` word:
- `'cover'`: `(a) bbb (c)` -> `(a) bbb (c)` (with message)
- `'cover_or_next'`: `(a) bbb (c)` -> `(a) bbb [c]`
- `'cover_or_prev'`: `(a) bbb (c)` -> `[a] bbb (c)`
- `'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)` -> `(a) bbb [c]`. Same outcome for `(bbb)`.
- `'prev'`: `(a) bbb (c)` -> `[a] bbb (c)`. Same outcome for `(bbb)`.
- `'nearest'`: depends on cursor position (same as in `'cover_or_nearest'`).
## Search suffixes~
To provide more searching possibilities, 'mini.surround' creates extended
mappings force "prev" and "next" methods for particular search. It does so
by appending mapping with certain suffix: `config.mappings.suffix_last` for
mappings which will use "prev" search method, `config.mappings.suffix_next`
- "next" search method.
Notes:
- It creates new mappings only for actions involving surrounding search:
delete, replace, find (right and left), highlight.
- All new mappings behave the same way as if `config.search_method` is set
to certain search method. They are dot-repeatable, respect |v:count|, etc.
- Supply empty string to disable creation of corresponding set of mappings.
Example with default values (`n` for `suffix_next`, `l` for `suffix_last`)
and initial line `(aa) (bb) (cc)`.
- Typing `sdn)` with cursor inside `(aa)` results into `(aa) bb (cc)`.
- Typing `sdl)` with cursor inside `(cc)` results into `(aa) bb (cc)`.
- Typing `2srn)]` with cursor inside `(aa)` results into `(aa) (bb) [cc]`.
------------------------------------------------------------------------------
*MiniSurround.operator()*
`MiniSurround.operator`({task}, {cache})
Surround operator
Main function to be used in expression mappings. No need to use it
directly, everything is setup in |MiniSurround.setup|.
Parameters~
{task} `(string)` Name of surround task.
{cache} `(table)` Task cache.
------------------------------------------------------------------------------
*MiniSurround.add()*
`MiniSurround.add`({mode})
Add surrounding
No need to use it directly, everything is setup in |MiniSurround.setup|.
Parameters~
{mode} `(string)` Mapping mode (normal by default).
------------------------------------------------------------------------------
*MiniSurround.delete()*
`MiniSurround.delete`()
Delete surrounding
No need to use it directly, everything is setup in |MiniSurround.setup|.
------------------------------------------------------------------------------
*MiniSurround.replace()*
`MiniSurround.replace`()
Replace surrounding
No need to use it directly, everything is setup in |MiniSurround.setup|.
------------------------------------------------------------------------------
*MiniSurround.find()*
`MiniSurround.find`()
Find surrounding
No need to use it directly, everything is setup in |MiniSurround.setup|.
------------------------------------------------------------------------------
*MiniSurround.highlight()*
`MiniSurround.highlight`()
Highlight surrounding
No need to use it directly, everything is setup in |MiniSurround.setup|.
------------------------------------------------------------------------------
*MiniSurround.update_n_lines()*
`MiniSurround.update_n_lines`()
Update `MiniSurround.config.n_lines`
Convenient wrapper for updating `MiniSurround.config.n_lines` in case the
default one is not appropriate.
------------------------------------------------------------------------------
*MiniSurround.user_input()*
`MiniSurround.user_input`({prompt}, {text})
Ask user for input
This is mainly a wrapper for |input()| which allows empty string as input,
cancelling with `<Esc>` and `<C-c>`, and slightly modifies prompt. Use it
to ask for input inside function custom surrounding (see |MiniSurround.config|).
------------------------------------------------------------------------------
*MiniSurround.gen_spec*
`MiniSurround.gen_spec`
Generate common surrounding specifications
This is a table with two sets of generator functions: <input> and <output>
(currently empty). Each is a table with values being function generating
corresponding surrounding specification.
Example: >
local ts_input = require('mini.surround').gen_spec.input.treesitter
require('mini.surround').setup({
custom_surroundings = {
-- Use tree-sitter to search for function call
f = {
input = ts_input({ outer = '@call.outer', inner = '@call.inner' })
},
}
})
See also~
|MiniAi.gen_spec|
------------------------------------------------------------------------------
*MiniSurround.gen_spec.input.treesitter()*
`MiniSurround.gen_spec.input.treesitter`({captures}, {opts})
Treesitter specification for input surrounding
This is a specification in function form. When called with a pair of
treesitter captures, it returns a specification function outputting an
array of region pairs derived from <outer> and <inner> captures. It first
searches for all matched nodes of outer capture and then completes each one
with the biggest match of inner capture inside that node (if any). The result
region pair is a difference between regions of outer and inner captures.
In order for this to work, apart from working treesitter parser for desired
language, user should have a reachable language-specific 'textobjects'
query (see |get_query()|). 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
'nvim-treesitter/nvim-treesitter-textobjects' plugin, 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 `call.outer`, `call.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 surrounding parts). See |lua-treesitter-query|.
To verify that query file is reachable, run (example for "lua" language)
`:lua print(vim.inspect(vim.treesitter.get_query_files('lua', 'textobjects')))`
(output should have at least an intended file).
Example configuration for function definition textobject with
'nvim-treesitter/nvim-treesitter-textobjects' captures:
>
local ts_input = require('mini.surround').gen_spec.input.treesitter
require('mini.surround').setup({
custom_textobjects = {
f = ts_input({ outer = '@call.outer', inner = '@call.inner' }),
}
})
>
Notes:
- By default query is done using 'nvim-treesitter' plugin if it is present
(falls back to builtin methods otherwise). This allows for a more
advanced features (like multiple buffer languages, custom directives, etc.).
See `opts.use_nvim_treesitter` for how to disable this.
- It uses buffer's |filetype| to determine query language.
- 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~
{captures} `(table)` Captures for outer and inner parts of region pair:
table with <outer> and <inner> fields with captures for outer
(`[left.form; right.to]`) and inner (`(left.to; right.from)` both edges
exclusive, i.e. they won't be a part of surrounding) regions. Each value
should be a string capture starting with `'@'`.
{opts} `(table)` Options. Possible values:
- <use_nvim_treesitter> - whether to try to use 'nvim-treesitter' plugin
(if present) to do the query. It implements more advanced behavior at
cost of increased execution time. Provides more coherent experience if
'nvim-treesitter-textobjects' queries are used. Default: `true`.
Return~
`(function)` Function which returns array of current buffer region pairs
representing differences between outer and inner captures.
See also~
|MiniSurround-surround-specification| for how this type of
surrounding specification is processed.
|get_query()| for how query is fetched in case of no 'nvim-treesitter'.
|Query:iter_captures()| for how all query captures are iterated in case of
no 'nvim-treesitter'.
|MiniAi.gen_spec.treesitter()| for similar 'mini.ai' generator.
vim:tw=78:ts=8:noet:ft=help:norl:
0