350 lines
15 KiB
Plaintext
350 lines
15 KiB
Plaintext
*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:
|