*AutoPairsHowTo*            A list of how-to guides for auto-pairs

==============================================================================
Table of help documents~

    |AutoPairs.txt|
    |AutoPairsCompatibility|
    |AutoPairsTroubleshooting|
    |AutoPairsHowTo| (you are here)

==============================================================================
CONTENTS                                              *autopairs-howto-contents*

    About this document ................................ |autopairs-howto-about|
    Requiring whitespace when inserting ................ |autopairs-howto-whitespace-only|
    Configuring contextual insertion ................... |autopairs-howto-contextual|
    Adding regex pairs ................................. |autopairs-adding-regex-pairs|
    Using <CR> for autocomplete ........................ |autopairs-autocomplete-cr|
    Using non-<BS> keys for deleting pairs ............. |autopairs-non-bs-deletion|
        1. Alternative keys ............................ |autopairs-delete-other-key|
        2. Using <C-w>, <Delete>, or similar ........... |autopairs-delete-other-action|

==============================================================================
About this document                                      *autopairs-howto-about*

This document is for a concrete list of common questions and answers regarding
commonly asked-about auto-pairs configurations.

Use |autopairs-howto-contents| to navigate the contents of this file.
If you have anything you feel fits in this document, and that others would
benefit from, consider opening a PR with your addition. New sections are added
last, unless they fit better as a subsection. See other sections for examples.

==============================================================================
Requiring whitespace when inserting            *autopairs-howto-whitespace-only*

Auto-pairs can be configured to only insert when there's whitespace
immediately after the cursor. This is done by setting: >
    let g:AutoPairsCompleteOnlyOnSpace = 1
<

Note that by default, this includes a few exceptions for close pairs. This
means that if your cursor is ahead of a known close pair, but that isn't a
quote, completion will still happen. If you do not want this, you can disable
it: >
    let g:AutoPairsAutoBuildSpaceWhitelist = 0
<

Regardless of this option, if you want to add or remove characters that are
exceptions to requiring whitespace, you can add them to
|g:AutoPairsNextCharWhitelist|. Note that this variable doesn't support
multiple bytes; use with caution.

Further reading~
* |g:AutoPairsAutoBuildSpaceWhitelist|
* |g:AutoPairsCompleteOnlyOnSpace|

==============================================================================
Configuring contextual insertion                    *autopairs-howto-contextual*

WARNING: Highly experimental. May have performance consequences.

Auto-pairs has some limited context support, currently only supporting
strings. |g:AutoPairsStringHandlingMode| has tree legal values.

Given () "|" ), pressing ( at |, the three modes yield:

 0: No differentiation between comments and code; cross-balancing will occur;
    default behavior for jiangmiao/auto-pairs. Example output: () "(|" )
 1: Content outside the group (i.e. string) gets matched separately from
    content within. Example output: () "(|)" )
 2: No completion; jumping is still supported. Example output:
    () "(|" ), regardless of whether the ) at the end is there or not

Option 1 comes with the heaviest performance consequences, as it has to check
each individual character for highlight groups. At the time of writing, this
function call comes with some significant overhead, and it's unclear why.

==============================================================================
Adding regex pairs                                *autopairs-adding-regex-pairs*

As of 4.0.0, regex in pairs is disabled by default.

This is easily fixed by adding `'regex': 1` to the |autopairs-pair-object|: >
    {'<open pair>': {'close': '<close pair>', 'regex': 1}}
<
Note that there's generally very few reasons to do this in the wild. The
overwhelming majority of pairs do not need regex, and benefit from having it
disabled, as it is by default.

Also note that poorly designed pairs can and will result in various regex
errors. The regexes are interpreted using |\v|, and need to be written to be
compatible with that flag.

==============================================================================
Using <CR> for autocomplete                          *autopairs-autocomplete-cr*

Due to how Vim's input system works, the conditional used by many plugins for
`<CR>` autocomplete insertion does not take effect on auto-pairs' function,
combining async weirdness with a function thinking it's doing its job. The
separate execution means auto-pairs always executes, rather than just
executing in the fallback condition, which it's easy to assume the mapping
should be part of.

Admittedly, there are relatively few cases where this is triggered. JavaScript
files seem far more prone to bugs than any other file, at least with coc.nvim

Workarounds~

Use Ctrl-Y (strongly recommended)~
A workaround for this is to just use |complete_CTRL-Y| rather than CR, and
leave CR to auto-pairs.

Ctrl-Y has first-class support in Vim, and generally generally doesn't
conflict with anything. It also matches the other default completion keybinds,
making them a great option for consistency.

Map <CR> manually~
If you absolutely need to use <CR> rather than |complete_CTRL-Y| to
select from your autocomplete menu, you have to disable the auto-pairs CR map,
and deal with it yourself: 

With the current recommendation for coc.nvim's map, the else condition has to
be modified to include \<Plug>AutopairsReturn after <CR>: >
    let g:AutoPairsMapCR = 0
    inoremap <silent><expr> <cr> coc#pum#visible() ? coc#_select_confirm() : "\<C-g>u\<CR>\<Plug>AutoPairsReturn"
<
Note that other autocomplete plugins have other commands; see their respective
documentation for the source template to copy-pasta. I also recommend checking
coc.nvim's documentation for a template to copy-pasta, as the one kept here
will not be kept up-to-date.

================================================================================
Using non-<BS> keys for deleting pairs                 *autopairs-non-bs-deletion*

This section describes two scenarios:

1. Using alternative keys instead of <BS>
2. Using other strokes (such as <C-w> or <Delete>) to trigger pair deletion

--------------------------------------------------------------------------------
1. Alternative keys                                   *autopairs-delete-other-key*

For using an alternate key that acts identically to <BS>, you can recursively
remap that key to <BS>: >
    imap <somekey> <BS>
<

Note that, for pair deletion to work, |g:AutoPairsMapBS| MUST be set to 1. At
the time of writing, if you want to remap that other key to be the only trigger,
you need to do so with a bit more involved map: >
    inoremap <silent> <somekey> <C-R>=autopairs#AutoPairsDelete()<CR>
<

--------------------------------------------------------------------------------
2. Using <C-w>, <Delete>, or similar               *autopairs-delete-other-action*


In some cases, you may want pair deletion to work with keys other than <BS>.
For convenience, auto-pairs lets you define ✨ special maps ✨ to work with
these. autopairs#AutoPairsDelete() accepts a single argument with the default
action to take if not deleting pairs. Using this does not affect how the pairs
are deleted, but it changes what default action to take for that map if pair
deletions aren't applicable. 

If you were to use method 1 for <C-w>, for example, it would delete pairs, but
it would also convert <C-w> into a glorified <BS> that no longer deletes entire
words like one might expect.

If, for example, you want to map `<C-w>` to delete pairs if possible, but
without affecting your ability to use it to delete words, you'd use[^1]: >
    inoremap <silent><expr> <C-w> autopairs#AutoPairsDelete("\<C-w>")
<

If you have >
    (|)
<
and now press <C-w>, the pair will be deleted. But if you have: >
    (Hello|)
<

and press <C-w>, you get: >
    (|)
<
Again, as expected from <C-w>. 

Note that the keybind needs to be present in both the string and in the keymap
itself. The action actually taken by auto-pairs is dictated by the string, and
not the keybind the function is called in.

WARNING: Using this with <Delete> will result in unintuitive behaviour around
deletion. If you have the following scenario: >
    ()|[]
<
And use <Delete> as a special pair delete key, it will NOT delete the pair in
front of the cursor. After pressing <Delete>, you'll have: >
    |[]
<
... or exactly the same thing <BS> would've done. This is the case for all
alternate actions.

While you can remap <Delete>, this unintuitive behaviour means I don't recommend
doing so. Forward-looking deletions may come at some point in the future, but
are not currently planned. If you want it, consider opening a PR.

Associated FR:~
    https://github.com/LunarWatcher/auto-pairs/issues/90

Section footnotes~
[^1]: Why <expr> here, but not in the previous section, you ask?
    
    I have no fucking clue. <C-R>= refused to cooperate with the string
    argument, and incorrectly claims autopairs#AutoPairsDelete does not exist.
    <expr> does not have this issue, but requires dropping <C-R>.

vim:ft=help
