Regenerate nvim config
This commit is contained in:
@ -0,0 +1,349 @@
|
||||
*nvim-autopairs-rules.txt* nvim-autopairs rules
|
||||
|
||||
==============================================================================
|
||||
Table of Contents *nvim-autopairs-rules-table-of-contents*
|
||||
|
||||
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|
|
||||
|
||||
==============================================================================
|
||||
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(begin_pair, end_pair, filetypes)
|
||||
<
|
||||
|
||||
|
||||
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 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.
|
||||
|
||||
TREESITTER CONDITIONS ~
|
||||
|
||||
Predicates based on the state of the Treesitter graph can be used by including:
|
||||
|
||||
>
|
||||
local ts_conds = require('nvim-autopairs.ts-conds')
|
||||
<
|
||||
|
||||
|
||||
│ function │ Usage │
|
||||
│is_ts_node({node_table}) │check current treesitter node│
|
||||
│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:
|
||||
Reference in New Issue
Block a user