@@ -3,94 +3,134 @@
33==============================================================================
44Table of Contents *nvim-autopairs-rules-table-of-contents*
55
6− - Define rule with a pairs |nvim-autopairs-rules-define-rule-with-a-pairs|
7− - Rules |nvim-autopairs-rules-rules|
6+1. Rule Basics |nvim-autopairs-rules-rule-basics|
7+2. Controlling rule behavior |nvim-autopairs-rules-controlling-rule-behavior|
8+ - Method Overview |nvim-autopairs-rules-method-overview|
9+ - Conditions |nvim-autopairs-rules-conditions|
10+3. Method Explanations |nvim-autopairs-rules-method-explanations|
11+ - The `with_*` methods |nvim-autopairs-rules-the-`with_*`-methods|
12+ - The `use_*` methods |nvim-autopairs-rules-the-`use_*`-methods|
13+ - Shorthand methods |nvim-autopairs-rules-shorthand-methods|
14+ - Advanced methods |nvim-autopairs-rules-advanced-methods|
815
9−DEFINE RULE WITH A PAIRS *nvim-autopairs-rules-define-rule-with-a-pairs*
16+==============================================================================
17+1. Rule Basics *nvim-autopairs-rules-rule-basics*
18+
19+At its core, a rule consists of two things: a **pair definition** and an
20+optional **declaration of filetypes** where the rule is in effect. A pair
21+definition has an opening part and a closing part. Each of these parts can be
22+as simple as a single character like a pair of parenthesis, or multiple
23+characters like Markdown code fences. Defining a rule is straightforward:
24+
25+>
26+ Rule(begin_pair, end_pair, filetypes)
27+<
1028
11−Rule(begin_pair, end_pair, filetypes)
1229
30+Where `begin_pair` is the opening part of the pair and `end_pair` is the
31+closing part. `filetypes` may be specified in multiple ways:
1332
14−- You can use string or a table(array) on file type
15− `Rule("(",")", "markdown")` ,`Rule("(",")", {"markdown","vim"})`
16−- If you add minus "-" before file type mean that rule is not working on that file type.
17− `Rule("a","a","-vim")`
33+>
34+ Rule("(", ")") -- Enabled for all filetypes
35+ Rule("(", ")", "markdown") -- As a string
36+ Rule("(", ")", {"markdown", "vim"}) -- As a table
37+<
1838
1939
20−RULES *nvim-autopairs-rules-rules*
40+Additionally, it is possible to specify filetypes where the rule should **not**
41+be enabled by prefixing it with a `-` character:
2142
22−│ function │ usage │
23−│with_pair(cond) │add condition to check for pair event │
24−│with_move(cond) │add condition to check for move right event │
25−│with_cr(cond) │add condition to check for break line event │
26−│with_del(cond) │add condition to check for delete pair event │
27−│only_cr(cond) │disable move,del and pair event Only use break li│
28−│ │ne event │
29−│use_regex(bool,"<key>")│input pair use regex and trigger by key │
30−│ │ │
31−│use_key('<key>') │change trigger key │
32−│replace_endpair(func) │change a map pair with function │
33−│set_end_pair_length(num│help to move a cursor to a middle of the end pair│
34−│ber) │ │
35−│ │when you use a replace_endpair with key <left> <P│
36−│ │lug> │
37−│replace_map_cr(func) │change a map on cr key with with function │
38−│end_wise(cond) │expand pair only on enter key │
43+>
44+ Rule("(", ")", "-markdown") -- All filetypes *except* markdown
45+<
3946
4047
41− *nvim-autopairs-rules-replace_endpair*
48+==============================================================================
49+2. Controlling rule behavior *nvim-autopairs-rules-controlling-rule-behavior*
4250
43−replace_endpair paramaters 2 of replace_endpair use to
44− combine with with_pair function
51+By default, rules are very simple and will always complete a pair the moment
52+the opening part is typed. This is fine and in some cases desirable, but the
53+rules API allows you to control the manner and context in which pairs are
54+completed; this is done by attaching **conditions** (predicates) to **events**
55+and adding **modifiers** to the rule. `Rule` objects expose a variety of
56+methods to add these predicates and modifiers to the rule.
4557
58+METHOD OVERVIEW *nvim-autopairs-rules-method-overview*
4659
47−>
48− Rule("(",")")
49− :use_key("<c-h>")
50− :replace_endpair(function() return "<bs><del>" end, true)
51− -- it is a short version of this
52− Rule("(","")
53− :use_key("<c-h>")
54− :with_pair(cond.after_text(")")) -- check text after cursor is )
55− :replace_endpair(function() return "<bs><del>" end)
56−<
60+These methods allow control over if, when, and how rules perform completion of
61+pairs. Each method returns the `Rule` object so that they may be chained
62+together to easily define complex rules.
5763
64+│ method │ usage │
65+│with_pair(cond) │add condition to check during pair event │
66+│with_move(cond) │add condition to check during move right event │
67+│with_cr(cond) │add condition to check during line break event │
68+│with_del(cond) │add condition to check during delete pair event │
69+│only_cr(cond) │enable _only_ the line break event; disable everything │
70+│ │else │
71+│use_regex(bool, "<k│interpret begin_pair as regex; optionally set trigger k│
72+│ey>") │ey │
73+│use_key("<key>") │set trigger key │
74+│replace_endpair(fun│define ending part with a function; optionally add with│
75+│c, check_pair) │_pair │
76+│set_end_pair_length│override offset used to position the cursor between the│
77+│(number) │ pair when replace_endpair is used │
78+│replace_map_cr(func│change the mapping for used for <CR> during the line br│
79+│) │eak event │
80+│end_wise(cond) │make the rule an end-wise rule │
5881
59−CONDITION ~
82+
83+AIDING UNDERSTANDING: "WHEN" INSTEAD OF "WITH" ~
84+
85+It may be helpful to think of the `with_<event>` functions as reading more like
86+`when_<event>` instead, as the condition is checked **when** `<event>` happens
87+(or wants to happen). This naming scheme more accurately describes how the
88+`Rule` is affected and reads more intuitively when reading a rule definition.
89+
90+For example, given a rule definition `Rule("(", ")")`, each method has a
91+certain effect on how and when the ending part of the pair, the closing
92+parenthesis, is completed. The ending part is only completed **when**
93+associated conditions are met upon typing the opening part of the pair.
94+
95+CONDITIONS *nvim-autopairs-rules-conditions*
96+
97+nvim-autopairs comes with a variety of common predicates ready to use simply by
98+including:
6099
61100>
62101 local cond = require('nvim-autopairs.conds')
63102<
64103
65104
66−│ function │ Usage │
67−│none() │always wrong │
68−│done() │always correct │
69−│before_text(text) │check character before │
70−│after_text(text) │check character after │
71−│before_regex(regex,length│check character before with lua regex │
72−│) │ │
73−│after_regex(regex,length)│check character after with lua regex │
74−│ │ │
75−│not_before_text(text) │check character before │
76−│not_after_text(text) │check character after │
77−│not_before_regex(regex,le│check character before with lua regex │
78−│ngth) │ │
79−│not_after_regex(regex,len│check character after with lua regex │
80−│gth) │ │
81−│not_inside_quote() │check is not inside a quote │
82−│is_inside_quote() │check is inside a quote │
83−│not_filetypes({table}) │check filetype is not inside table │
84−│is_bracket_in_quote() │check the next char is quote and cursor is insi│
85−│ │de quote │
86−
105+│ function │ Usage │
106+│none() │always false │
107+│done() │always true │
108+│before_text(text) │text exists before opening part │
109+│after_text(text) │text exists after opening part │
110+│before_regex(regex, length│regex matches before opening part │
111+│) │ │
112+│after_regex(regex, length)│regex matches after opening part │
113+│ │ │
114+│not_before_text(text) │text is not before opening part │
115+│not_after_text(text) │text is not after opening part │
116+│not_before_regex(regex, le│regex doesn’t match before opening part │
117+│ngth) │ │
118+│not_after_regex(regex, len│regex doesn’t match after opening part │
119+│gth) │ │
120+│not_inside_quote() │not currently within quotation marks │
121+│is_inside_quote() │currently within quotation marks │
122+│not_filetypes({table}) │current filetype is not inside table │
123+│is_bracket_in_quote() │check the next char is quote and cursor is insi│
124+│ │de quote │
87125
88126
89−- cond.not_filetypes should be use by add minus on filetype when you declare rule.
90− Rule("a","a","-vim") because it is complete remove that rule on buffer.
127+**N.B.** While `cond.not_filetypes` is available, it’s better to use the
128+minus syntax on the desired filetype in the initial rule declaration, since
129+then the rule is completely removed from the buffer.
91130
131+TREESITTER CONDITIONS ~
92132
93−TREESITTER CONDITION ~
133+Predicates based on the state of the Treesitter graph can be used by including:
94134
95135>
96136 local ts_conds = require('nvim-autopairs.ts-conds')
@@ -102,6 +142,208 @@ TREESITTER CONDITION ~
102142│is_not_ts_node({node_table})│check not in treesitter node │
103143
104144
145+==============================================================================
146+3. Method Explanations *nvim-autopairs-rules-method-explanations*
147+
148+This section explains each method in more detail: their signatures and how they
149+modify the rule’s behavior are all outlined here.
150+
151+THE `WITH_*` METHODS *nvim-autopairs-rules-the-`with_*`-methods*
152+
153+Calling these methods on a `Rule` will add predicate functions to their
154+corresponding event, which determines whether the effect of the event actually
155+takes place. There are no predicates if you don’t define any, and so any
156+events without predicates behave as if they had a single predicate that always
157+returns true.
158+
159+A `Rule` may have more than one predicate defined for a given event, and the
160+order that they are defined will be the order that they are checked. However,
161+the **first** non-`nil` value returned by a predicate is used and the remaining
162+predicates (if any) are **not** executed. In other words, predicates defined
163+earlier have priority over predicates defined later.
164+
165+`WITH_PAIR(COND, POS)` ~
166+
167+After typing the opening part, `cond` will fire and the ending part will only
168+be added if `cond` returned true. `with_pair` may be called more than once, and
169+by default, each predicate is appended to a list. When the "pair" event fires,
170+the _first_ predicate to return non-nil is used as the condition result.
171+Specifying `pos` allows explicit control over the order of the predicates.
172+
173+`WITH_MOVE(COND)` ~
174+
175+If `cond` is true, the cursor is simply moved right when typing the ending part
176+of the pair and the next character is also the ending part, e.g. `|" -> "|`
177+when typing `"`. If `cond` returns false, the ending part is inserted as normal
178+instead.
179+
180+`WITH_CR(COND)` ~
181+
182+If `cond` is true, then move the ending part of the pair to a new line below
183+the cursor after pressing `<CR>` while the cursor is between the pair (think
184+curly braces opening a block). Otherwise `<CR>` behaves as normal. For example:
185+
186+>
187+ {|}
188+<
189+
190+
191+Typing `<CR>` produces the following when `cond` is true:
192+
193+>
194+ {
195+ |
196+ }
197+<
198+
199+
200+`WITH_DEL(COND)` ~
201+
202+If `cond` is true, when the cursor is between the pair, pressing `<BS>` to
203+delete the opening part of the pair will delete the ending part as well.
204+
205+THE `USE_*` METHODS *nvim-autopairs-rules-the-`use_*`-methods*
206+
207+The `use_*` functions alter how auto-pairing is triggered. Normally, the first
208+argument to `Rule` is taken literally as the opening part of the pair and as
209+soon as it is typed the "pair" event fires.
210+
211+`USE_KEY(KEY)` ~
212+
213+The pair is only completed when `key` is pressed, instead of the moment that
214+the opening part is typed. This is particularly useful in `use_regex`.
215+
216+`USE_REGEX(BOOL, KEY)` ~
217+
218+Causes the opening part to be interpreted as a lua pattern that triggers
219+insertion of the ending part when matched. If `key` is specified, then it acts
220+as an implicit `use_key`.
221+
222+SHORTHAND METHODS *nvim-autopairs-rules-shorthand-methods*
223+
224+These methods exist as convenient shortcuts for defining certain behaviors.
225+
226+`END_WISE(FUNC)` ~
227+
228+This method is used to make "end-wise" rules, which is terminology that should
229+be familiar to users of other auto-pair plugins, e.g. Lexima. Specifically,
230+this method makes it so that the ending part of the pair will be completed
231+_only upon pressing `<CR>` after the opening part_, in which case the "newline"
232+event is fired as usual.
233+
234+This behavior is useful for languages with statement constructs like Lua and
235+Bash. For example, defining the following `Rule`:
236+
237+>
238+ Rule('then', 'end'):end_wise(function(opts))
239+ -- Add any context checks here, e.g. line starts with "if"
240+ return string.match(opts.line, '^%s*if') ~= nil
241+ end)
242+<
243+
244+
245+And then pressing `<CR>` at the following cursor position:
246+
247+>
248+ if foo == bar then|
249+<
250+
251+
252+Would be completed as this (assuming some kind of automatic indent is enabled):
253+
254+>
255+ if foo == bar then
256+ |
257+ end
258+<
259+
260+
261+`ONLY_CR(COND)` ~
262+
263+This shortcut method disables the "pair", "del", and "move" events by setting a
264+single predicate for each that is always false. Additionally, the effect of any
265+`use_key` modifiers are removed as well. If `cond` is specified, a "newline"
266+predicate is set as if `with_cr` were called.
267+
268+This method is convenient for defining _simple_ end-wise rules. As an example,
269+a default rule is defined with `only_cr` for Markdown code blocks with an
270+explicit language; the closing triple-backtick is not completed until you press
271+`<CR>` after specifying the language:
272+
273+>
274+ ```lua <-- <CR> pressed here
275+ |
276+ ```
277+<
278+
279+
280+ADVANCED METHODS *nvim-autopairs-rules-advanced-methods*
281+
282+These methods allow you to define more complex and dynamic rules. When combined
283+with `with_*` and `use_*` methods, it is possible to create very powerful
284+auto-pairs.
285+
286+`REPLACE_ENDPAIR(FUNC, CHECK_PAIR)` ~
287+
288+Facilitates the creation of dynamic ending parts. When the "pair" event fires
289+and the ending part is to be completed, `func` is called with a single `opts`
290+argument and should return a string. The returned string will be sent to
291+`nvim_feedkeys` to insert the ending part of the pair.
292+
293+The `opts` parameter is a table that provides context for the current pair
294+completion, and can be useful for determining what to return. Note that because
295+`nvim_feedkeys` is used, arbitrary Vim functionality can be leveraged, such as
296+including `<Esc>` to be able to send normal mode commands.
297+
298+ *nvim-autopairs-rules-Optional-`check_pair`-parameter*
299+
300+Optional `check_pair` parameter The `check_pair` parameter is optional,
301+ and can either be a boolean or function.
302+ If `check_pair` is a function, it is
303+ passed as-is to `with_pair` to create a
304+ "pair" predicate. If `check_pair` is
305+ true, then an implicit
306+ `with_pair(cond.after_text(rule.end_pair))`
307+ predicate is added, where
308+ `rule.end_pair` is the second argument
309+ to the `Rule` constructor. If
310+ `check_pair` is false, an "always false"
311+ `with_pair` predicate is added.
312+
313+
314+As an example, these two rule definitions are equivalent:
315+
316+>
317+ -- This...
318+ Rule("(", ")")
319+ :use_key("<C-h>")
320+ :replace_endpair(function() return "<BS><Del>" end, true)
321+
322+ -- ...is shorthand for this
323+ Rule("(", "")
324+ :use_key("<C-h>")
325+ :with_pair(cond.after_text(")")) -- check that text after cursor is `)`
326+ :replace_endpair(function() return "<BS><Del>" end)
327+<
328+
329+
330+`SET_END_PAIR_LENGTH(LEN)` ~
331+
332+When completing the ending part of a pair, the cursor necessarily moves
333+backward so that is in between the opening part and the closing part. In order
334+to do this, the `Rule` must know the length of the ending part, which by
335+default is trivially determined. However, if you would like to override where
336+the cursor is placed after completion, i.e. using `replace_endpair`, you can
337+explicitly set the ending part length with this method.
338+
339+`REPLACE_MAP_CR(FUNC)` ~
340+
341+This method allows you to set a custom mapping for the "newline" (`<CR>`) event
342+that will be used instead of the normal behavior. This can be helpful for
343+enforcing certain styles or or adding additional edits. `func` is called with a
344+single `opts` argument and should return a string specifying the mapping for
345+`<CR>`. The default mapping is: `<C-g>u<CR><C-c>O`.
346+
105347Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>
106348
107349vim:tw=78:ts=8:noet:ft=help:norl: