*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|
    Contextual pair insertion .................... |autopairs-howto-contextual|
    Regex-based pairs ............................ |autopairs-adding-regex-pairs|
    Using <CR> for the autocomplete popup ........ |autopairs-autocomplete-cr|

==============================================================================
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.


vim:ft=help
