mirror of
https://github.com/ilyakooo0/nvim-autopairs.git
synced 2024-10-05 12:08:02 +03:00
chore: generated vimdoc (#241)
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This commit is contained in:
github-actions[bot]
GitHub
parent
469ef47fc2
commit
4a95b3982b
@ -3,94 +3,134 @@
|
||||
==============================================================================
|
||||
Table of Contents *nvim-autopairs-rules-table-of-contents*
|
||||
|
||||
- Define rule with a pairs |nvim-autopairs-rules-define-rule-with-a-pairs|
|
||||
- Rules |nvim-autopairs-rules-rules|
|
||||
1. Rule Basics |nvim-autopairs-rules-rule-basics|
|
||||
2. Controlling rule behavior |nvim-autopairs-rules-controlling-rule-behavior|
|
||||
- Method Overview |nvim-autopairs-rules-method-overview|
|
||||
- Conditions |nvim-autopairs-rules-conditions|
|
||||
3. Method Explanations |nvim-autopairs-rules-method-explanations|
|
||||
- The `with_*` methods |nvim-autopairs-rules-the-`with_*`-methods|
|
||||
- The `use_*` methods |nvim-autopairs-rules-the-`use_*`-methods|
|
||||
- Shorthand methods |nvim-autopairs-rules-shorthand-methods|
|
||||
- Advanced methods |nvim-autopairs-rules-advanced-methods|
|
||||
|
||||
DEFINE RULE WITH A PAIRS *nvim-autopairs-rules-define-rule-with-a-pairs*
|
||||
|
||||
Rule(begin_pair, end_pair, filetypes)
|
||||
|
||||
|
||||
- You can use string or a table(array) on file type
|
||||
`Rule("(",")", "markdown")` ,`Rule("(",")", {"markdown","vim"})`
|
||||
- If you add minus "-" before file type mean that rule is not working on that file type.
|
||||
`Rule("a","a","-vim")`
|
||||
|
||||
|
||||
RULES *nvim-autopairs-rules-rules*
|
||||
|
||||
│ function │ usage │
|
||||
│with_pair(cond) │add condition to check for pair event │
|
||||
│with_move(cond) │add condition to check for move right event │
|
||||
│with_cr(cond) │add condition to check for break line event │
|
||||
│with_del(cond) │add condition to check for delete pair event │
|
||||
│only_cr(cond) │disable move,del and pair event Only use break li│
|
||||
│ │ne event │
|
||||
│use_regex(bool,"<key>")│input pair use regex and trigger by key │
|
||||
│ │ │
|
||||
│use_key('<key>') │change trigger key │
|
||||
│replace_endpair(func) │change a map pair with function │
|
||||
│set_end_pair_length(num│help to move a cursor to a middle of the end pair│
|
||||
│ber) │ │
|
||||
│ │when you use a replace_endpair with key <left> <P│
|
||||
│ │lug> │
|
||||
│replace_map_cr(func) │change a map on cr key with with function │
|
||||
│end_wise(cond) │expand pair only on enter key │
|
||||
|
||||
|
||||
*nvim-autopairs-rules-replace_endpair*
|
||||
|
||||
replace_endpair paramaters 2 of replace_endpair use to
|
||||
combine with with_pair function
|
||||
==============================================================================
|
||||
1. Rule Basics *nvim-autopairs-rules-rule-basics*
|
||||
|
||||
At its core, a rule consists of two things: a **pair definition** and an
|
||||
optional **declaration of filetypes** where the rule is in effect. A pair
|
||||
definition has an opening part and a closing part. Each of these parts can be
|
||||
as simple as a single character like a pair of parenthesis, or multiple
|
||||
characters like Markdown code fences. Defining a rule is straightforward:
|
||||
|
||||
>
|
||||
Rule("(",")")
|
||||
:use_key("<c-h>")
|
||||
:replace_endpair(function() return "<bs><del>" end, true)
|
||||
-- it is a short version of this
|
||||
Rule("(","")
|
||||
:use_key("<c-h>")
|
||||
:with_pair(cond.after_text(")")) -- check text after cursor is )
|
||||
:replace_endpair(function() return "<bs><del>" end)
|
||||
Rule(begin_pair, end_pair, filetypes)
|
||||
<
|
||||
|
||||
|
||||
CONDITION ~
|
||||
Where `begin_pair` is the opening part of the pair and `end_pair` is the
|
||||
closing part. `filetypes` may be specified in multiple ways:
|
||||
|
||||
>
|
||||
Rule("(", ")") -- Enabled for all filetypes
|
||||
Rule("(", ")", "markdown") -- As a string
|
||||
Rule("(", ")", {"markdown", "vim"}) -- As a table
|
||||
<
|
||||
|
||||
|
||||
Additionally, it is possible to specify filetypes where the rule should **not**
|
||||
be enabled by prefixing it with a `-` character:
|
||||
|
||||
>
|
||||
Rule("(", ")", "-markdown") -- All filetypes *except* markdown
|
||||
<
|
||||
|
||||
|
||||
==============================================================================
|
||||
2. Controlling rule behavior *nvim-autopairs-rules-controlling-rule-behavior*
|
||||
|
||||
By default, rules are very simple and will always complete a pair the moment
|
||||
the opening part is typed. This is fine and in some cases desirable, but the
|
||||
rules API allows you to control the manner and context in which pairs are
|
||||
completed; this is done by attaching **conditions** (predicates) to **events**
|
||||
and adding **modifiers** to the rule. `Rule` objects expose a variety of
|
||||
methods to add these predicates and modifiers to the rule.
|
||||
|
||||
METHOD OVERVIEW *nvim-autopairs-rules-method-overview*
|
||||
|
||||
These methods allow control over if, when, and how rules perform completion of
|
||||
pairs. Each method returns the `Rule` object so that they may be chained
|
||||
together to easily define complex rules.
|
||||
|
||||
│ method │ usage │
|
||||
│with_pair(cond) │add condition to check during pair event │
|
||||
│with_move(cond) │add condition to check during move right event │
|
||||
│with_cr(cond) │add condition to check during line break event │
|
||||
│with_del(cond) │add condition to check during delete pair event │
|
||||
│only_cr(cond) │enable _only_ the line break event; disable everything │
|
||||
│ │else │
|
||||
│use_regex(bool, "<k│interpret begin_pair as regex; optionally set trigger k│
|
||||
│ey>") │ey │
|
||||
│use_key("<key>") │set trigger key │
|
||||
│replace_endpair(fun│define ending part with a function; optionally add with│
|
||||
│c, check_pair) │_pair │
|
||||
│set_end_pair_length│override offset used to position the cursor between the│
|
||||
│(number) │ pair when replace_endpair is used │
|
||||
│replace_map_cr(func│change the mapping for used for <CR> during the line br│
|
||||
│) │eak event │
|
||||
│end_wise(cond) │make the rule an end-wise rule │
|
||||
|
||||
|
||||
AIDING UNDERSTANDING: "WHEN" INSTEAD OF "WITH" ~
|
||||
|
||||
It may be helpful to think of the `with_<event>` functions as reading more like
|
||||
`when_<event>` instead, as the condition is checked **when** `<event>` happens
|
||||
(or wants to happen). This naming scheme more accurately describes how the
|
||||
`Rule` is affected and reads more intuitively when reading a rule definition.
|
||||
|
||||
For example, given a rule definition `Rule("(", ")")`, each method has a
|
||||
certain effect on how and when the ending part of the pair, the closing
|
||||
parenthesis, is completed. The ending part is only completed **when**
|
||||
associated conditions are met upon typing the opening part of the pair.
|
||||
|
||||
CONDITIONS *nvim-autopairs-rules-conditions*
|
||||
|
||||
nvim-autopairs comes with a variety of common predicates ready to use simply by
|
||||
including:
|
||||
|
||||
>
|
||||
local cond = require('nvim-autopairs.conds')
|
||||
<
|
||||
|
||||
|
||||
│ function │ Usage │
|
||||
│none() │always wrong │
|
||||
│done() │always correct │
|
||||
│before_text(text) │check character before │
|
||||
│after_text(text) │check character after │
|
||||
│before_regex(regex,length│check character before with lua regex │
|
||||
│) │ │
|
||||
│after_regex(regex,length)│check character after with lua regex │
|
||||
│ │ │
|
||||
│not_before_text(text) │check character before │
|
||||
│not_after_text(text) │check character after │
|
||||
│not_before_regex(regex,le│check character before with lua regex │
|
||||
│ngth) │ │
|
||||
│not_after_regex(regex,len│check character after with lua regex │
|
||||
│gth) │ │
|
||||
│not_inside_quote() │check is not inside a quote │
|
||||
│is_inside_quote() │check is inside a quote │
|
||||
│not_filetypes({table}) │check filetype is not inside table │
|
||||
│is_bracket_in_quote() │check the next char is quote and cursor is insi│
|
||||
│ │de quote │
|
||||
│ function │ Usage │
|
||||
│none() │always false │
|
||||
│done() │always true │
|
||||
│before_text(text) │text exists before opening part │
|
||||
│after_text(text) │text exists after opening part │
|
||||
│before_regex(regex, length│regex matches before opening part │
|
||||
│) │ │
|
||||
│after_regex(regex, length)│regex matches after opening part │
|
||||
│ │ │
|
||||
│not_before_text(text) │text is not before opening part │
|
||||
│not_after_text(text) │text is not after opening part │
|
||||
│not_before_regex(regex, le│regex doesn’t match before opening part │
|
||||
│ngth) │ │
|
||||
│not_after_regex(regex, len│regex doesn’t match after opening part │
|
||||
│gth) │ │
|
||||
│not_inside_quote() │not currently within quotation marks │
|
||||
│is_inside_quote() │currently within quotation marks │
|
||||
│not_filetypes({table}) │current filetype is not inside table │
|
||||
│is_bracket_in_quote() │check the next char is quote and cursor is insi│
|
||||
│ │de quote │
|
||||
|
||||
|
||||
**N.B.** While `cond.not_filetypes` is available, it’s better to use the
|
||||
minus syntax on the desired filetype in the initial rule declaration, since
|
||||
then the rule is completely removed from the buffer.
|
||||
|
||||
- cond.not_filetypes should be use by add minus on filetype when you declare rule.
|
||||
Rule("a","a","-vim") because it is complete remove that rule on buffer.
|
||||
TREESITTER CONDITIONS ~
|
||||
|
||||
|
||||
TREESITTER CONDITION ~
|
||||
Predicates based on the state of the Treesitter graph can be used by including:
|
||||
|
||||
>
|
||||
local ts_conds = require('nvim-autopairs.ts-conds')
|
||||
@ -102,6 +142,208 @@ TREESITTER CONDITION ~
|
||||
│is_not_ts_node({node_table})│check not in treesitter node │
|
||||
|
||||
|
||||
==============================================================================
|
||||
3. Method Explanations *nvim-autopairs-rules-method-explanations*
|
||||
|
||||
This section explains each method in more detail: their signatures and how they
|
||||
modify the rule’s behavior are all outlined here.
|
||||
|
||||
THE `WITH_*` METHODS *nvim-autopairs-rules-the-`with_*`-methods*
|
||||
|
||||
Calling these methods on a `Rule` will add predicate functions to their
|
||||
corresponding event, which determines whether the effect of the event actually
|
||||
takes place. There are no predicates if you don’t define any, and so any
|
||||
events without predicates behave as if they had a single predicate that always
|
||||
returns true.
|
||||
|
||||
A `Rule` may have more than one predicate defined for a given event, and the
|
||||
order that they are defined will be the order that they are checked. However,
|
||||
the **first** non-`nil` value returned by a predicate is used and the remaining
|
||||
predicates (if any) are **not** executed. In other words, predicates defined
|
||||
earlier have priority over predicates defined later.
|
||||
|
||||
`WITH_PAIR(COND, POS)` ~
|
||||
|
||||
After typing the opening part, `cond` will fire and the ending part will only
|
||||
be added if `cond` returned true. `with_pair` may be called more than once, and
|
||||
by default, each predicate is appended to a list. When the "pair" event fires,
|
||||
the _first_ predicate to return non-nil is used as the condition result.
|
||||
Specifying `pos` allows explicit control over the order of the predicates.
|
||||
|
||||
`WITH_MOVE(COND)` ~
|
||||
|
||||
If `cond` is true, the cursor is simply moved right when typing the ending part
|
||||
of the pair and the next character is also the ending part, e.g. `|" -> "|`
|
||||
when typing `"`. If `cond` returns false, the ending part is inserted as normal
|
||||
instead.
|
||||
|
||||
`WITH_CR(COND)` ~
|
||||
|
||||
If `cond` is true, then move the ending part of the pair to a new line below
|
||||
the cursor after pressing `<CR>` while the cursor is between the pair (think
|
||||
curly braces opening a block). Otherwise `<CR>` behaves as normal. For example:
|
||||
|
||||
>
|
||||
{|}
|
||||
<
|
||||
|
||||
|
||||
Typing `<CR>` produces the following when `cond` is true:
|
||||
|
||||
>
|
||||
{
|
||||
|
|
||||
}
|
||||
<
|
||||
|
||||
|
||||
`WITH_DEL(COND)` ~
|
||||
|
||||
If `cond` is true, when the cursor is between the pair, pressing `<BS>` to
|
||||
delete the opening part of the pair will delete the ending part as well.
|
||||
|
||||
THE `USE_*` METHODS *nvim-autopairs-rules-the-`use_*`-methods*
|
||||
|
||||
The `use_*` functions alter how auto-pairing is triggered. Normally, the first
|
||||
argument to `Rule` is taken literally as the opening part of the pair and as
|
||||
soon as it is typed the "pair" event fires.
|
||||
|
||||
`USE_KEY(KEY)` ~
|
||||
|
||||
The pair is only completed when `key` is pressed, instead of the moment that
|
||||
the opening part is typed. This is particularly useful in `use_regex`.
|
||||
|
||||
`USE_REGEX(BOOL, KEY)` ~
|
||||
|
||||
Causes the opening part to be interpreted as a lua pattern that triggers
|
||||
insertion of the ending part when matched. If `key` is specified, then it acts
|
||||
as an implicit `use_key`.
|
||||
|
||||
SHORTHAND METHODS *nvim-autopairs-rules-shorthand-methods*
|
||||
|
||||
These methods exist as convenient shortcuts for defining certain behaviors.
|
||||
|
||||
`END_WISE(FUNC)` ~
|
||||
|
||||
This method is used to make "end-wise" rules, which is terminology that should
|
||||
be familiar to users of other auto-pair plugins, e.g. Lexima. Specifically,
|
||||
this method makes it so that the ending part of the pair will be completed
|
||||
_only upon pressing `<CR>` after the opening part_, in which case the "newline"
|
||||
event is fired as usual.
|
||||
|
||||
This behavior is useful for languages with statement constructs like Lua and
|
||||
Bash. For example, defining the following `Rule`:
|
||||
|
||||
>
|
||||
Rule('then', 'end'):end_wise(function(opts))
|
||||
-- Add any context checks here, e.g. line starts with "if"
|
||||
return string.match(opts.line, '^%s*if') ~= nil
|
||||
end)
|
||||
<
|
||||
|
||||
|
||||
And then pressing `<CR>` at the following cursor position:
|
||||
|
||||
>
|
||||
if foo == bar then|
|
||||
<
|
||||
|
||||
|
||||
Would be completed as this (assuming some kind of automatic indent is enabled):
|
||||
|
||||
>
|
||||
if foo == bar then
|
||||
|
|
||||
end
|
||||
<
|
||||
|
||||
|
||||
`ONLY_CR(COND)` ~
|
||||
|
||||
This shortcut method disables the "pair", "del", and "move" events by setting a
|
||||
single predicate for each that is always false. Additionally, the effect of any
|
||||
`use_key` modifiers are removed as well. If `cond` is specified, a "newline"
|
||||
predicate is set as if `with_cr` were called.
|
||||
|
||||
This method is convenient for defining _simple_ end-wise rules. As an example,
|
||||
a default rule is defined with `only_cr` for Markdown code blocks with an
|
||||
explicit language; the closing triple-backtick is not completed until you press
|
||||
`<CR>` after specifying the language:
|
||||
|
||||
>
|
||||
```lua <-- <CR> pressed here
|
||||
|
|
||||
```
|
||||
<
|
||||
|
||||
|
||||
ADVANCED METHODS *nvim-autopairs-rules-advanced-methods*
|
||||
|
||||
These methods allow you to define more complex and dynamic rules. When combined
|
||||
with `with_*` and `use_*` methods, it is possible to create very powerful
|
||||
auto-pairs.
|
||||
|
||||
`REPLACE_ENDPAIR(FUNC, CHECK_PAIR)` ~
|
||||
|
||||
Facilitates the creation of dynamic ending parts. When the "pair" event fires
|
||||
and the ending part is to be completed, `func` is called with a single `opts`
|
||||
argument and should return a string. The returned string will be sent to
|
||||
`nvim_feedkeys` to insert the ending part of the pair.
|
||||
|
||||
The `opts` parameter is a table that provides context for the current pair
|
||||
completion, and can be useful for determining what to return. Note that because
|
||||
`nvim_feedkeys` is used, arbitrary Vim functionality can be leveraged, such as
|
||||
including `<Esc>` to be able to send normal mode commands.
|
||||
|
||||
*nvim-autopairs-rules-Optional-`check_pair`-parameter*
|
||||
|
||||
Optional `check_pair` parameter The `check_pair` parameter is optional,
|
||||
and can either be a boolean or function.
|
||||
If `check_pair` is a function, it is
|
||||
passed as-is to `with_pair` to create a
|
||||
"pair" predicate. If `check_pair` is
|
||||
true, then an implicit
|
||||
`with_pair(cond.after_text(rule.end_pair))`
|
||||
predicate is added, where
|
||||
`rule.end_pair` is the second argument
|
||||
to the `Rule` constructor. If
|
||||
`check_pair` is false, an "always false"
|
||||
`with_pair` predicate is added.
|
||||
|
||||
|
||||
As an example, these two rule definitions are equivalent:
|
||||
|
||||
>
|
||||
-- This...
|
||||
Rule("(", ")")
|
||||
:use_key("<C-h>")
|
||||
:replace_endpair(function() return "<BS><Del>" end, true)
|
||||
|
||||
-- ...is shorthand for this
|
||||
Rule("(", "")
|
||||
:use_key("<C-h>")
|
||||
:with_pair(cond.after_text(")")) -- check that text after cursor is `)`
|
||||
:replace_endpair(function() return "<BS><Del>" end)
|
||||
<
|
||||
|
||||
|
||||
`SET_END_PAIR_LENGTH(LEN)` ~
|
||||
|
||||
When completing the ending part of a pair, the cursor necessarily moves
|
||||
backward so that is in between the opening part and the closing part. In order
|
||||
to do this, the `Rule` must know the length of the ending part, which by
|
||||
default is trivially determined. However, if you would like to override where
|
||||
the cursor is placed after completion, i.e. using `replace_endpair`, you can
|
||||
explicitly set the ending part length with this method.
|
||||
|
||||
`REPLACE_MAP_CR(FUNC)` ~
|
||||
|
||||
This method allows you to set a custom mapping for the "newline" (`<CR>`) event
|
||||
that will be used instead of the normal behavior. This can be helpful for
|
||||
enforcing certain styles or or adding additional edits. `func` is called with a
|
||||
single `opts` argument and should return a string specifying the mapping for
|
||||
`<CR>`. The default mapping is: `<C-g>u<CR><C-c>O`.
|
||||
|
||||
Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>
|
||||
|
||||
vim:tw=78:ts=8:noet:ft=help:norl:
|
||||
|
||||
@ -4,6 +4,7 @@
|
||||
Table of Contents *nvim-autopairs-table-of-contents*
|
||||
|
||||
- nvim-autopairs |nvim-autopairs-nvim-autopairs|
|
||||
- Installation |nvim-autopairs-installation|
|
||||
- Default values |nvim-autopairs-default-values|
|
||||
|
||||
NVIM-AUTOPAIRS *nvim-autopairs-nvim-autopairs*
|
||||
@ -12,10 +13,28 @@ A super powerful autopair plugin for Neovim that supports multiple characters.
|
||||
|
||||
Requires neovim 0.5+
|
||||
|
||||
SETUP ~
|
||||
INSTALLATION *nvim-autopairs-installation*
|
||||
|
||||
Install the plugin with your preferred package manager:
|
||||
|
||||
VIM-PLUG <HTTPS://GITHUB.COM/JUNEGUNN/VIM-PLUG> ~
|
||||
|
||||
>
|
||||
require('nvim-autopairs').setup{}
|
||||
Plug 'windwp/nvim-autopairs'
|
||||
|
||||
lua << EOF
|
||||
require("nvim-autopairs").setup {}
|
||||
EOF
|
||||
<
|
||||
|
||||
|
||||
PACKER <HTTPS://GITHUB.COM/WBTHOMASON/PACKER.NVIM> ~
|
||||
|
||||
>
|
||||
use {
|
||||
"windwp/nvim-autopairs",
|
||||
config = function() require("nvim-autopairs").setup {} end
|
||||
}
|
||||
<
|
||||
|
||||
|
||||
@ -73,14 +92,59 @@ Check readme.md on nvim-cmp repo.
|
||||
-- If you want insert `(` after select function or method item
|
||||
local cmp_autopairs = require('nvim-autopairs.completion.cmp')
|
||||
local cmp = require('cmp')
|
||||
cmp.event:on( 'confirm_done', cmp_autopairs.on_confirm_done({ map_char = { tex = '' } }))
|
||||
|
||||
|
||||
-- add a lisp filetype (wrap my-function), FYI: Hardcoded = { "clojure", "clojurescript", "fennel", "janet" }
|
||||
cmp_autopairs.lisp[#cmp_autopairs.lisp+1] = "racket"
|
||||
cmp.event:on(
|
||||
'confirm_done',
|
||||
cmp_autopairs.on_confirm_done()
|
||||
)
|
||||
<
|
||||
|
||||
|
||||
Mapping `<CR>` You can customize the kind of completion
|
||||
to add `(` or any character.
|
||||
|
||||
|
||||
>
|
||||
local handlers = require('nvim-autopairs.completion.handlers')
|
||||
|
||||
cmp.event:on(
|
||||
'confirm_done',
|
||||
cmp_autopairs.on_confirm_done({
|
||||
filetypes = {
|
||||
-- "*" is a alias to all filetypes
|
||||
["*"] = {
|
||||
["("] = {
|
||||
kind = {
|
||||
cmp.lsp.CompletionItemKind.Function,
|
||||
cmp.lsp.CompletionItemKind.Method,
|
||||
},
|
||||
handler = handlers["*"]
|
||||
}
|
||||
},
|
||||
lua = {
|
||||
["("] = {
|
||||
kind = {
|
||||
cmp.lsp.CompletionItemKind.Function,
|
||||
cmp.lsp.CompletionItemKind.Method
|
||||
},
|
||||
---@param char string
|
||||
---@param item item completion
|
||||
---@param bufnr buffer number
|
||||
handler = function(char, item, bufnr)
|
||||
-- Your handler function. Inpect with print(vim.inspect{char, item, bufnr})
|
||||
end
|
||||
}
|
||||
},
|
||||
-- Disable for tex
|
||||
tex = false
|
||||
}
|
||||
})
|
||||
)
|
||||
<
|
||||
|
||||
|
||||
Don’t use `nil` to disable a filetype. If a filetype is `nil` then `*` is
|
||||
used as fallback.
|
||||
|
||||
coq_nvim ~
|
||||
|
||||
>
|
||||
@ -132,9 +196,8 @@ without completion plugin ~
|
||||
<
|
||||
|
||||
|
||||
Mapping `<CR>` another completion plugin
|
||||
<https://github.com/windwp/nvim-autopairs/wiki/Completion-plugin>
|
||||
|
||||
another completion plugin
|
||||
<https://github.com/windwp/nvim-autopairs/wiki/Completion-plugin>
|
||||
|
||||
If you have a problem with indent after you press `<CR>` please check the
|
||||
settings of treesitter indent or install a plugin that has indent support for
|
||||
@ -235,6 +298,7 @@ You can use treesitter to check for a pair.
|
||||
|
||||
>
|
||||
local npairs = require("nvim-autopairs")
|
||||
local Rule = require('nvim-autopairs.rule')
|
||||
|
||||
npairs.setup({
|
||||
check_ts = true,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user