*matchup.txt*    modern matching words
*matchup* *match-up*

Author: Andy Massimino <a@normed.space>
Web: https://github.com/andymass/vim-matchup
Script ID: 5624
License: MIT license {{{

  Copyright (c) 2020 Andy Massimino

  Copyright (c) 2016 Karl Yngve Lervåg

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this  software and  associated documentation  files (the  "Software"), to
  deal in the  Software without restriction, including  without limitation the
  rights to use, copy, modify,  merge, publish, distribute, sublicense, and/or
  sell copies of the  Software, and to permit persons to  whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright  notice and this permission notice shall  be included in
  all copies or substantial portions of the Software.

  THE SOFTWARE IS  PROVIDED "AS IS", WITHOUT WARRANTY OF  ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING  BUT NOT  LIMITED TO  THE WARRANTIES  OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  AUTHORS  OR COPYRIGHT  HOLDERS BE  LIABLE FOR  ANY CLAIM,  DAMAGES OR  OTHER
  LIABILITY,  WHETHER IN  AN ACTION  OF CONTRACT,  TORT OR  OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  IN THE SOFTWARE.

}}}

==============================================================================
CONTENTS                                                     *matchup-contents*

  Introduction                                  |matchup-introduction|
    Feature overview                            |matchup-overview|
  Usage                                         |matchup-usage|
    Default mappings                            |matchup-default-mappings|
    Customizing mappings                        |matchup-custom-mappings|
    Features                                    |matchup-features|
    Commands                                    |matchup-commands|
    Options                                     |matchup-options|
    File type options                           |matchup-file-types|
  FAQ                                           |matchup-faq|
  Interoperability                              |matchup-interoperability|
  Acknowledgments                               |matchup-acknowledgments|
  Development                                   |matchup-development|

==============================================================================
INTRODUCTION                                             *matchup-introduction*

|match-up| is a plugin that lets you visualize, navigate, and operate on
matching sets of text.  It is a replacement for the venerable vim plugin
|matchit|.  match-up aims to replicate all of |matchit|'s features, fix a number
of its deficiencies and bugs, and add a few totally new features.  It also
replaces the standard plugin |matchparen|, allowing all of |matchit|'s words to be
highlighted along with the 'matchpairs' symbols such as `()`, `{}`, and `[]`.

------------------------------------------------------------------------------
Feature overview~
                                                             *matchup-overview*

This plugin:

- Extends vim's |%| (see |matchup-%|) motion to language-specific words instead of
  just single characters.  The words depend on the specific |filetype| plugin
  (|ftplugin|).  The following built-in vim filetype plugins
  currently provide support for match-up: >

    abaqus, ada, aspvbs, c, clojure, cobol, config, context, csc, csh, dtd,
    dtrace, eiffel, eruby, falcon, fortran, framescript, haml, hamster, hog,
    html, ishd, j, jsp, kconfig, liquid, lua, make, matlab, mf, mp, ocaml,
    pascal, pdf, perl, php, plaintex, postscr, ruby, sh, spec, sql, tex, vb,
    verilog, vhdl, vim, xhtml, xml, zimbu, zsh
<
- Highlights symbols and words under the cursor along with their matches.

- Display off-screen matches in the |status-line|.

- Adds motions |g%|, |[%|, |]%|, and |z%|.

- Provides analogous text objects |i%| and |a%|.

==============================================================================
USAGE                                                           *matchup-usage*

------------------------------------------------------------------------------
Default mappings~
                                                     *matchup-default-mappings*

For customization, see |matchup-custom-mappings|.

                                                         *matchup-%*
%                       When on a recognized word, go forwards to its next
                        matching word.  If at a close word, cycle back to the
                        corresponding open word.  If the cursor is not on a
                        word, seek forwards to one and then jump to its match.
                        This is an |inclusive| motion.

                                                         *matchup-N%*
{count}%                If {count} is less than 6, go forwards {count} times.
                        Otherwise, go to {count} percentage in the file (|N%|).
                        See |g:matchup_motion_override_Npercent|.

                                                         *g%*
g%                      When on a recognized word, go backwards to [count]th
                        previous matching word.  If at an open word, cycle
                        around to the corresponding open word.  If the cursor
                        is not on a word, seek forwards to one and then jump
                        to its match.

                                                         *[%*
[%                      Go to [count]th previous outer open word.  Allows
                        navigation to the start of blocks surrounding the
                        cursor. This is similar to vim's built-in |[(| and |[{|
                        and is an |exclusive| motion (|matchup-feat-exclusive|).

                                                         *]%*
]%                      Go to [count]th next outer close word.  Allows
                        navigation to the end of blocks surrounding the
                        cursor. This is similar to vim's built-in |])| and |]}|
                        and is an |exclusive| motion (|matchup-feat-exclusive|).

                                                         *z%*
z%                      Go to inside [count]th nearest block.  This is an
                        |exclusive| motion when used with operators,
                        except it eats white-space.  For example, where `█` is
                        the cursor position, >

                        █ call somefunction(      param1, param2)
<
                        `dz%` produces >

                        param1, param2)
<
                                                         *v_a%* *a%*
a%                      Select an |any-block|.
                        This closely matches vim's built-in |ab|.

                                                         *v_Na%* *Na%*
{count}a%               Select an |open-to-close-block|.
                        When {count} is greater than 1, select the {count}th
                        surrounding open-to-close block.

                                                         *v_i%* *i%*
i%                      Select the inside of an |any-block|.
                        This closely matches vim's built-in |ib|.
                        See also |matchup-feat-linewise|.

                                                         *v_Ni%* *Ni%*
{count}i%               Select the inside of an |open-to-close-block|.
                        When {count} is greater than 1, select the inside of
                        the {count}th surrounding open-to-close block.

                                                         *ds%*
{count}ds%              Delete {count}th surrounding matching words.  This
                        only works for open and close words.
                        Requires |g:matchup_surround_enabled| = 1.

                                                         *cs%*
{count}cs%              Change {count}th surrounding matching words.  This
                        only works for open and close words.  If vim-surround
                        is installed, you can type replacements according to
                        that plugin's rules.  Otherwise, match-up will give
                        you the opportunity to type a single character.  Some
                        simple replacement pairs are supported.
                        Requires |g:matchup_surround_enabled| = 1.

------------------------------------------------------------------------------
Customizing mappings~
                                                      *matchup-custom-mappings*

|match-up| provides a number of default mappings.  Each right-hand side is
provided as a <plug>-mapping (see |using-<plug>|).  For any given map, the
default mapping will only be created if it does not already exist. This means
that if a user defines a custom mapping, e.g., with >

  nmap <leader>% <plug>(matchup-z%)
<
the corresponding default left-hand side will not be mapped.

  -------------------------------------------------------------------------~
   LHS         RHS                                       Mode   Module
  -------------------------------------------------------------------------~
   %           |<plug>(matchup-%)|                         nx     motion
   g%          |<plug>(matchup-g%)|                        nx     motion
   [%          |<plug>(matchup-[%)|                        nx     motion
   ]%          |<plug>(matchup-]%)|                        nx     motion
   z%          |<plug>(matchup-z%)|                        nx     motion
   a%          |<plug>(matchup-%)|                         x      text_obj
   i%          |<plug>(matchup-%)|                         x      text_obj
   ds%         |<plug>(matchup-ds%)|                       n      surround
   cs%         |<plug>(matchup-cs%)|                       n      surround
   (none)      |<plug>(matchup-hi-surround)|               n      matchparen
  -------------------------------------------------------------------------~
   Operator pending maps~
  -------------------------------------------------------------------------~
   %           |<plug>(matchup-%)|                         o      motion
     ... And so on for g%, [%, ]%, z%, a%, i% ...

Key: (n) normal, (x) visual, (o) operator-pending (|omap-info|).

Note: Prior to vim 8.1.0648, in order to support motion forcing (see |o_v|, |o_V|,
|o_CTRL-V|) for each operator-pending map, match-up made four maps corresponding
to each motion type:

  -------------------------------------------------------------------------~
   Obsolete operator pending maps~
  -------------------------------------------------------------------------~
   %           |<plug>(matchup-o_)||<plug>(matchup-%)|       o      motion
   v%          |<plug>(matchup-o_v)||<plug>(matchup-%)|      o      motion
   V%          |<plug>(matchup-o_V)||<plug>(matchup-%)|      o      motion
   <c-v>%      |<plug>(matchup-o_<c-v>)||<plug>(matchup-%)|  o      motion
     ... And so on for g%, [%, ]%, z%, a%, i% ...

This meant, for example, `d2v%` would work (meaning delete 2 matches forward,
exclusively), but `dv2%` would not work as you would expect (the behavior is
undefined).  After vim version 8.1.0648, this limitation of operator-pending
mapping was lifted and match-up is able to use simplified mappings.

------------------------------------------------------------------------------
Features~
                                                             *matchup-features*

What do we mean by open, close, mid?  This depends on the specific file type
and is configured through the variable |b:match_words|.  Here are a couple
of examples: >

  if l:x == 1
    call one()
  elseif l:x == 2
    call two()
  else
    call three()
  endif
<
                                            *any-block* *open-to-close-block*

For the vim-script language, match-up understands the words `if`, `else`, `elseif`,
`endif` and that they form a sequential construct.  The "open" word is `if`, the
"close" word is `endif`, and the "mid" words are `else` and `elseif`.  The `if`/`endif`
pair is called an "open-to-close" block and the `if`/`else`, `else`/`elsif`, and
`elseif`/`endif` are called "any" blocks.

C, C++: >

  #if 0
  #else
  #endif

  void some_func() {
      if (true) {
        one();
      } else if (false && false) {
        two();
      } else {
        three();
      }
  }
<
Since in C and C++, blocks are delimited using braces (`{` & `}`), match-up will
recognize `{` as the open word and `}` as the close word. It will ignore the if
and else if because they are not defined in vim's C file type plugin.

On the other hand, match-up will recognize the `#if`, `#else`, `#endif` preprocessor
directives.

See |matchup-feat-exclusive| and |matchup-feat-linewise| for some examples and
important special cases.

Highlighting matches~

To disable match highlighting at |startup|, use >

  let g:matchup_matchparen_enabled = 0
>
in your vimrc.  See |matchup-opts-matchparen| for more information and related
options.

You can enable highlighting on the fly using >

  :DoMatchParen
<
Likewise, you can disable highlighting at any time using >

  :NoMatchParen
<
After start-up, is better to use `:NoMatchParen` and `:DoMatchParen` to toggle
highlighting globally than setting the global variable since these commands
make sure not to leave stale matches around.

Display matches off screen~

If an open or close match which would have been highlighted is on a line
positioned outside of the current window, the match is shown in the status
line (the default).  If both the open and close match are off-screen, the
close match is preferred.
See |g:matchup_matchparen_offscreen| for configuration.

                                                  *<plug>(matchup-hi-surround)*
Highlight surrounding~

To highlight the surrounding delimiters until the cursor moves, use a map such
as the following >

  nmap <silent> <F7> <plug>(matchup-hi-surround)
<
There is no default map for this feature.

Parallel transmutation~

In insert mode, after changing text inside a word, matching words will be
changed in parallel.  As an example, >

  <pre>
    text
  </pre>
<
Changing `pre` to `div` and leaving insert mode will produce: >

  <div>
    text
  </div>
<
Note: this currently only works for match words which define a backref
relation like `\1`.  A wider set of transmutations are planned.

Parallel transmutation requires the matchparen module to be enabled.

                                                       *matchup-feat-exclusive*
Inclusive and exclusive motions~

In vim, character motions following operators (such as `d` for delete and `c` for
change) are either |inclusive| or |exclusive|.  This means they either include
the ending position or not.  Here, "ending position" means the line and column
closest to the end of the buffer of the region swept over by the motion.
match-up is designed so that `d]%` inside a set of parenthesis behaves exactly
like `d])`, except generalized to words.

Put differently, forward exclusive motions will not include the close word.
In this example, where `█` is the cursor position, >

  if █x | continue | endif
<
pressing `d]%` will produce (cursor on the `e`) >

  if endif
<
To include the close word, use either `dv]%` or `vd]%`.  This is also
compatible with vim's `dv])` and `dv]}`.

Operators over backward exclusive motions will instead exclude the position
the cursor was on before the operator was invoked.  For example, in >

  if █x | continue | endif
<
pressing `d[%` will produce >

  █x | continue | endif
<
This is compatible with vim's `d[(` and `d[{`.

                                                                 *d%* *dg%*

Unlike `]%`, `%` is an |inclusive| motion.  As a special case for the `d` (delete)
operator, if `d%` leaves behind lines white-space, they will be deleted also.
In effect, it will be operating line-wise.  As an example, pressing `d%` will
leave behind nothing. >

     █(

     )
<
To operate character-wise in this situation, use `dv%` or `vd%`.  This is vim
compatible with the built-in `d%` on items in 'matchpairs'.

                                                        *matchup-feat-linewise*
Line-wise operator/text-object combinations~

Normally, the text objects |i%| and |a%| work character-wise.  However,
there are some special cases.  For certain operators combined with |i%|,
under certain conditions, match-up will effectively operate line-wise
instead.  For example, in >

  if condition
   █call one()
    call two()
  endif
<
pressing `di%` will produce >

  if condition
  endif
<
even though deleting ` condition` would be suggested by the object `i%`.
The intention is to make operators more useful in some cases.  The
following rules apply:

1. The operator must be listed in |g:matchup_text_obj_linewise_operators|.
   By default this is |d| and |y| (e.g., `di%` and `ya%`).

2. The outer block must span multiple lines.

3. The open and close delimiters must be more than one character long.  In
   particular, `di%` involving a `(`...`)` block will not be subject to
   these special rules.

To prevent this behavior for a particular operation, use `vi%d`.  Note that
special cases involving indentation still apply (like with |i)| etc).

To disable this entirely, remove the operator from the following variable, >

  let g:matchup_text_obj_linewise_operators = [ 'y' ]
<
Note: unlike vim's built-in |i)|, |ab|, etc., |i%| does not make an existing visual
mode character-wise.

A second special case involves `da%`.  In this example, >

    if condition
     █call one()
      call two()
    endif
<
pressing `da%` will delete all four lines and leave no white-space.  This is
compatible with vim's `da(`, `dab`, etc.

------------------------------------------------------------------------------
Commands~
                                                             *matchup-commands*

                                          *:NoMatchParen* *matchup-:NoMatchParen*
:NoMatchParen       Disable matching after the plugin was loaded.
                                          *:DoMatchParen* *matchup-:DoMatchParen*
:DoMatchParen       Enable matching again.

                                          *:MatchupShowTimes*
:MatchupShowTimes   Display performance data, useful for debugging slow
                    matching.  Shows last, average, and maximum times.
                                          *:MatchupClearTimes*
:MatchupClearTimes  Reset performance counters to zero.

                                          *:MatchupWhereAmI*
:MatchupWhereAmI?   Echos your position in code by finding successive matching
                    words, like doing `[%` repeatedly.  Example:
>
  1310 do_pending_operator( … { ⯈ if ((finish_op || VIsual_active) && oap- … {
<
                    Running this command twice in the same position will give
                    more verbose output.

:MatchupWhereAmI??  Be more verbose about your position in code by displaying
                    several lines.  Example:
>
  1310 do_pending_operator(cmdarg_T *cap, int old_col, int gui_yank) … {
  1349     if ((finish_op || VIsual_active) && oap->op_type != OP_NOP) … {
<
                                          *:MatchupReload*
:MatchupReload      Reload the plugin, mostly for debugging.  Note that
                    this does not reload 'matchpairs' or `b:match_word`.

------------------------------------------------------------------------------
Options~
                                                              *matchup-options*

*g:matchup_enabled*

  Set to 0 to disable the plugin entirely.

  Default: 1

*g:matchup_mappings_enabled*        all mappings
|g:matchup_matchparen_enabled|      match highlighting
*g:matchup_mouse_enabled*           double click to select matches
*g:matchup_motion_enabled*          |matchup-%|, |%|, |[%|, |]%|
*g:matchup_text_obj_enabled*        |a%|, |i%|

  Set to 0 to disable a particular module or feature.

  Defaults: 1

*g:matchup_transmute_enabled*

  Set to 1 to enable the experimental transmute feature (|matchup-transmute|).

  Default: 0

*g:matchup_delim_stopline*

  Configures the number of lines to search in either direction while using
  motions and text objects.  Does not apply to match highlighting
  (see |g:matchup_matchparen_stopline| instead).

  Default: 1500

*g:matchup_delim_noskips*

  This option controls whether matching is done within strings and comments.
  By default, it is set to 0 which means all valid matches are made within
  strings and comments.  If set to 1, symbols like `()` will still be matched
  but words like `for` and `end` will not.  If set to 2, nothing will be
  matched within strings and comments. >

  let g:matchup_delim_noskips = 1
  let g:matchup_delim_noskips = 2
<
  Default: 0 (matching enabled within strings and comments)

*g:matchup_delim_start_plaintext*

  When enabled (the default), the plugin will be loaded for all buffers,
  including ones without a file type set.  This allows matching to be done in
  new buffers and plain text files but adds a small start-up cost to vim.

  Default: 1

Variables~

*b:match_words*
*b:match_skip*
*b:match_ignorecase*

  match-up understands these variables originally from matchit.  These are set
  in the respective |ftplugin| files.  They may not exist for every file type.
  To support a new file type, create a file `after/ftplugin/{filetype}.vim`
  which sets them appropriately.

                                                  *matchup-opts-matchparen*
Module matchparen~

*g:matchup_matchparen_enabled*

  This option will disable match highlighting at |startup|, e.g., use >

    let g:matchup_matchparen_enabled = 0
<
  in your vimrc.

  Note: vim's built-in plugin |pi_paren| plugin is also disabled.  The variable
  `g:loaded_matchparen` has no effect on match-up.

  Default: 1

  You can also enable and disable highlighting for specific buffers using the
  variable |b:matchup_matchparen_enabled|.

  Customizing the highlighting colors~

    match-up uses the |MatchParen| highlighting group by default, which can be
    configured.  For example, >

      :hi MatchParen ctermbg=blue guibg=lightblue cterm=italic gui=italic
<
    You may want to put this inside a |ColorScheme| |autocmd| so it is preserved
    after colorscheme changes: >

      augroup matchup_matchparen_highlight
        autocmd!
        autocmd ColorScheme * hi MatchParen guifg=red
      augroup END
<
    You can also highlight words differently than parentheses using the
    `MatchWord` highlighting group.  You might do this if you find the
    `MatchParen` style distracting for large blocks. >

      :hi MatchWord ctermfg=red guifg=blue cterm=underline gui=underline
<
    There are also `MatchParenCur` and `MatchWordCur` which allow you to configure
    the highlight separately for the match under the cursor. >

      :hi MatchParenCur cterm=underline gui=underline
      :hi MatchWordCur cterm=underline gui=underline
<
*b:matchup_matchparen_enabled*

  Set to 0 to disable highlighting on a per-buffer basis (there is no command
  for this).  By default, when disabling highlighting for a particular buffer,
  the standard plugin |pi_paren| will still be used for that buffer.

  Default: undefined (equivalent to 1)

*b:matchup_matchparen_fallback*

  If highlighting is disabled on a particular buffer, match-up will fall back
  to the vim standard plugin |pi_paren|, which will highlight 'matchpairs' such
  as `()`, `[]`, & `{}`.  To disable this, set this option to 0.

  Default: undefined (equivalent to 1)

  A common usage of these options is to automatically disable matchparen for
  particular file types: >

    augroup matchup_matchparen_disable_ft
      autocmd!
      autocmd FileType tex let [b:matchup_matchparen_fallback,
          \ b:matchup_matchparen_enabled] = [0, 0]
    augroup END
<
*g:matchup_matchparen_singleton*

  Whether or not to highlight recognized words even if there is no match.

  Default: 0

*g:matchup_matchparen_offscreen*

  Dictionary controlling the behavior with off-screen matches.  If empty, this
  feature is disabled.  Else, it should contain the following optional keys:

  method~
    Sets the method to use to show off-screen matches.
    Possible values are:

    `'status'` (default): Replace the |status-line| for off-screen matches.

    If a match is off of the screen, the line belonging to that match will be
    displayed syntax-highlighted in the status line along with the line number
    (if line numbers are enabled).  If the match is above the screen border,
    an additional Δ symbol will be shown to indicate that the matching line is
    really above the cursor line.

    `'status_manual'`: Compute the status-line but do not display it (future
    extension).

    `'popup'`: Use a popup window (requires at least vim 8.1.1406) or
    a floating window (in neovim) to show the off-screen match.

  scrolloff~
    When enabled, off-screen matches will not be shown in the statusline while
    the cursor is at the screen edge (respects the value of 'scrolloff').
    This is intended to prevent flickering while scrolling with j and k.

    Default: 0

  highlight~
    For popup method on vim only: set to a highlight group to override the
    colors in the popup window.  The default is to use *hl-Pmenu*.  Example:
>
      highlight! OffscreenPopup guibg=red guifg=blue
      let g:matchup_matchparen_offscreen
          \ = {'method': 'popup', 'highlight': 'OffscreenPopup'}
<
  Default: `{'method': 'status'}`

*g:matchup_matchparen_stopline*

  The number of lines to search in either direction while highlighting
  matches.  Set this conservatively since high values may cause performance
  issues.

  Default: 400

*g:matchup_matchparen_timeout*
*g:matchup_matchparen_insert_timeout*

  Adjust the timeouts in milliseconds for highlighting.

  Defaults: `g:matchparen_timeout`, `g:matchparen_insert_timeout`
  (300, 60 respectively)

*b:matchup_matchparen_timeout*
*b:matchup_matchparen_insert_timeout*

  Buffer local versions of the above.

*g:matchup_matchparen_deferred*

  Deferred highlighting improves cursor movement performance (for example, when
  using |hjkl|) by delaying highlighting for a short time and waiting to see if
  the cursor continues moving.

  Default: 0 (disabled)

Note: this feature is only available if your vim version has |timers| and
the function |timer_pause|, version 7.4.2180 and after.  For neovim, this
will only work in nvim-0.2.1 and after.

*g:matchup_matchparen_deferred_show_delay*

  Delay, in milliseconds, between when the cursor moves and when we start
  checking if the cursor is on a match.  Applies to both making highlights and
  clearing them for deferred highlighting.

  Note: these delays cannot be changed dynamically and should be configured
  before the plugin loads (e.g., in your vimrc).

  Default: 50

*g:matchup_matchparen_deferred_hide_delay*

  If the cursor has not stopped moving, assume highlight is stale after this
  many milliseconds.  Stale highlights are hidden.

  Note: this option cannot be changed dynamically.

  Default: 700

*g:matchup_matchparen_deferred_fade_time*         *matchup-fading*

  When set to {time} in milliseconds, the deferred highlighting behavior
  is changed in two ways:
    1. Highlighting of matches is preserved for at least {time} even when
       the cursor is moved away.
    2. If the cursor stays on the same match for longer than {time},
       highlighting is cleared.
  The effect is that highlighting occurs momentarily and then disappears,
  regardless of where the cursor is.  It is possible that fading takes
  longer than {time}, if vim is busy doing other things.

  This value should be greater than the deferred show delay.
  Note: this option cannot be changed dynamically.

  Example: >

    let g:matchup_matchparen_deferred = 1
    let g:matchup_matchparen_deferred_fade_time = 450
<
  Default: 0 (fading disabled)

*g:matchup_matchparen_pumvisible*

  If set to 1, matches will be made even when the |popupmenu-completion| is
  visible.  If you use an auto-complete plugin which interacts badly with
  matching, set this option to 0.

  Default: 1

*g:matchup_matchparen_nomode*

  When not empty, match highlighting will be disabled in the specified modes,
  where each mode is a single character like in the |mode()| function.  E.g., to
  disable highlighting in insert mode,
>
    let g:matchup_matchparen_nomode = 'i'
<
  and in visual modes,
>
    let g:matchup_matchparen_nomode = "vV\<c-v>"
<
  Note: In visual modes, this takes effect only after moving the cursor.

  Default: ''

*g:matchup_matchparen_hi_surround_always*

  Always highlight the surrounding words, if possible.  This is like
  |<plug>(matchup-hi-surround)| but is updated each time the cursor moves.
  This requires deferred matching (|g:matchup_matchparen_deferred| = 1).

  Default: 0

*g:matchup_matchparen_hi_background*

  Highlight buffer background between matches.  This uses the `MatchBackground`
  highlighting group and is linked to `ColorColumn` by default but can be
  configured with >

    :hi MatchBackground guibg=grey ctermbg=grey
<
  Default: 0

Module motion~

*g:matchup_motion_override_Npercent*

  In vim, {count}% goes to the {count} percentage in the file (see |N%|).
  match-up overrides this motion for small {count} (by default, anything less
  than 7).  For example, to allow {count}% for {count} up to 11, >
    let g:matchup_motion_override_Npercent = 11
<
  To disable this feature, and restore vim's default {count}%, >
    let g:matchup_motion_override_Npercent = 0
<
*g:matchup_motion_cursor_end*

  If enabled, cursor will land on the end of mid and close words while
  moving downwards (|%|/|]%|).  While moving upwards (|g%|, |[%|) the cursor
  will land on the beginning.  Set to 0 to disable.
  Note: this has no effect on operators: `d%` will delete |inclusive| of the
  ending word (this is compatible with matchit).

  Default: 1

*g:matchup_delim_count_fail*

  When disabled (default), giving an invalid count to the |[%| and |]%| motions
  and the text objects |i%| and |a%| will cause the motion or operation to fail.
  When enabled, they will move as far as possible.
  Note: targeting high counts when this option is enabled can become slow
  because many positions need to be tried before giving up.

  Default: 0

Module text_obj~

*g:matchup_text_obj_linewise_operators*

  Modifies the set of operators which may operate line-wise with |i%|
  (see |matchup-feat-linewise|).

  You may use 'v', 'V', and "\<c-v>" (i.e., an actual CTRL-V character) to the
  specify the corresponding visual mode.

  You can also specify custom plugin operators with 'g@' and optionally, an
  expression separated by a comma.  For example, to make |commentary|'s |gc|
  mapping work likewise when used in the operator `gci%`, >

  function! IsCommentaryOpFunc()
    return &operatorfunc ==? matchstr(maparg('<Plug>Commentary', 'n'),
        \ '\c<SNR>\w\+\ze()\|set op\%(erator\)\?func=\zs.\{-\}\ze<cr>')
  endfunction

  let g:matchup_text_obj_linewise_operators = ['d', 'y',
      \ 'g@,IsCommentaryOpFunc()']
<
  Default: `['d', 'y']`

Module surround~

*g:matchup_surround_enabled*

  Enables the surround module which provides maps |ds%| and |cs%|.

  Default: 0

------------------------------------------------------------------------------
File type options~
                                                           *matchup-file-types*

                                                                *matchup-latex*
LaTeX~

  By default, match-up is disabled for tex files when the plugin |vimtex| is
  detected.  To enable match-up for tex files, use the following in your vimrc: >

    let g:matchup_override_vimtex = 1
<
  This will replace vimtex's built-in highlighting and `%` map.

  Note: matching may be computationally intensive for complex LaTeX documents.
  If you experience slowdowns, consider using the following option: >

    let g:matchup_matchparen_deferred = 1
<
Match preferences~                                        *g:matchup_matchpref*

  A limited number of common preferences are available which affect how
  matching is done for a particular filetype.  They may be set through the
  `matchup_matchpref` dictionary: >

    let g:matchup_matchpref[&filetype].option_name = 1
<
HTML

*g:matchup_matchpref.html.nolists*

  When set to 1, this option disables matching and navigation between groups
  of list items in HTML documents such as the following >

    <ul>
      <li>One</li>
      <li>Two</li>
    </ul>
<
  By default, `%` will navigate from `<ul>` to `<li>` to `<li>` to `</ul>`.

  Default: 0

*g:matchup_matchpref.html.tagnameonly*

  When set to 1, only the tag name will be highlighted, not the rest of the
  tag, e.g., the "a" in >

  <a href="http://example.com">Link</a>
<
  This works for xml, html, and some other html-based types.

  Default: 0

Customization~

*g:matchup_hotfix[&filetype]*                                    *matchup-hotfix*

  For each file type, this option can be set to the string name of a function
  which will be called when loading files, prior to checking |b:match_words|
  and |b:match_skip|.  This option can be used to quickly customize matching for
  particular file types: >

    function! VimHotfix()
      " customization
    endfunction
    let g:matchup_hotfix['vim'] = 'VimHotfix'

*b:matchup_hotfix*

  This is an alternative buffer-local name for adding customization.

*matchup#util#patch_match_words*                                  *matchup-patch*
>
  call matchup#util#patch_match_words(before, after)
<
  This function replaces the literal string `before` contained in |b:match_words|
  with the literal string `after`.  When placed in an autocommand or in the file
  `after/ftplugin/{&filetype}.vim`, it can be used to customize the matching
  regular expressions for a particular file type.

*matchup#util#append_match_words*                                 *matchup-append*
>
  call matchup#util#append_match_words(str)
<
  Adds a set of patterns to |b:match_words|, adding a comma if necessary.

==============================================================================
FAQ                                                               *matchup-faq*

Q match-up doesn't work

A This plugin requires at least vim 7.4. It should work in vim 7.4.898 but at
  least vim 7.4.1689 is better. I recommend using the most recent version of
  vim if possible.

  If you have issues, please tell me your vim version and error messages. Try
  updating vim and see if the problem persists.

Q Why does jumping not work for construct X in language Y?

A Please open a new issue

Q Highlighting is not correct for construct X

A match-up uses matchit's filetype-specific data, which may not give
  enough information to create proper highlights.  To fix this, you may
  need to modify |b:match_words|.

  For help, please open a new issue and be a specific as possible.

Q I'm having performance problems

A match-up aims to be as fast as possible, but highlighting matching words can
  be intensive and may be slow on less powerful machines.  There are a few
  things you can try to improve performance:

  - Update to a recent version of vim.  Newer versions are faster, more
    extensively tested, and better supported by match-up.

  - Try deferred highlighting, which delays highlighting until the cursor is
    stationary to improve cursor movement performance.
    |g:matchup_matchparen_deferred|

  - Lower the highlighting timeouts.  If highlighting takes longer than the
    timeout, highlighting will not be attempted again until the cursor moves.
    |g:matchup_matchparen_timeout|, |g:matchup_matchparen_insert_timeout|

  If are having any other performance issues, please open a new issue and
  report the output of `:MatchupShowTimes`.

Q Why is there a weird entry on the status line?

A This is a feature which helps you see matches that are outside of the
  vim screen, similar to some IDEs.  If you wish to disable it, use >

  let g:matchup_matchparen_offscreen = {}
<
Q Matching does not work when lines are too far apart.

A The number of search lines is limited for performance reasons.  You may
  increase the limits with the following options: >

  let g:matchup_delim_stopline      = 1500 " generally
  let g:matchup_matchparen_stopline = 400  " for match highlighting only
<
Q The maps `1i%` and `1a%` are difficult to press.

A You may use the following maps `I%` and `A%` for convenience: >

  function! s:matchup_convenience_maps()
    xnoremap <sid>(std-I) I
    xnoremap <sid>(std-A) A
    xmap <expr> I mode()=='<c-v>'?'<sid>(std-I)':(v:count?'':'1').'i'
    xmap <expr> A mode()=='<c-v>'?'<sid>(std-A)':(v:count?'':'1').'a'
    for l:v in ['', 'v', 'V', '<c-v>']
      execute 'omap <expr>' l:v.'I%' "(v:count?'':'1').'".l:v."i%'"
      execute 'omap <expr>' l:v.'A%' "(v:count?'':'1').'".l:v."a%'"
    endfor
  endfunction
  call s:matchup_convenience_maps()
<
  Note: this is not compatible with the plugin targets.vim.

Q How can I contribute?

A Read the contribution guidelines (CONTRIBUTING.md) and issue template
  (ISSUE_TEMPLATE.md).  Be as precise and detailed as possible when submitting
  issues and pull requests.

==============================================================================
INTEROPERABILITY                                     *matchup-interoperability*

vimtex, for LaTeX documents~

By default, match-up will be disabled automatically for tex files when vimtex
is detected.  To enable match-up for tex files, use >

  let g:matchup_override_vimtex = 1
<
match-up's matching engine is more advanced than vimtex's and supports middle
delimiters such as `\middle|` and `\else`.  The exact set of delimiters recognized
may differ between the two plugins.  For example, the mappings `da%` and `dad`
will not always match, particularly if you have customized vimtex's delimiters.

Matchit~

matchit.vim should not be loaded.  If it is loaded, it must be loaded after
match-up (in this case, matchit.vim will be disabled).  Note that some plugins,
such as vim-sensible, load matchit.vim so these must also be initialized after
match-up.

Matchparen emulation~

match-up loads |matchparen| if it is not already loaded.  Ordinarily, match-up
disables matchparen's highlighting and emulates it to highlight the symbol
contained in the 'matchpairs' option (by default `()`, `[]`, and `{}`).  If match-up
is disabled per-buffer using |b:matchup_matchparen_enabled|, match-up will use
matchparen instead of its own highlighting.  See |b:matchup_matchparen_fallback|
for more information.

Other plugins~

match-up does not currently provide support for auto-completion.  The
following plugins may be useful for this:

- |vim-endwise|         https://github.com/tpope/vim-endwise
- |auto-pairs|          https://github.com/jiangmiao/auto-pairs
- |delimitMate|         https://github.com/Raimondi/delimitMate
- |splitjoin.vim|       https://github.com/AndrewRadev/splitjoin.vim

There is basic support for deleting and changing surroundings, but you may
prefer to use one of the following:

- |vim-surround|        https://github.com/tpope/vim-surround
- |vim-sandwich|        https://github.com/machakann/vim-sandwich

==============================================================================
ACKNOWLEDGMENTS                                       *matchup-acknowledgments*

Origins~

|match-up| was originally based on Karl Yngve Lervåg's |vimtex|.  The concept
and style of this plugin and its development are heavily influenced by vimtex.

[vimtex]: https://github.com/lervag/vimtex

Other inspirations~

- |matchit|
- |matchparen|
- |MatchTag|            https://github.com/gregsexton/MatchTag
- |MatchTagAlways|      https://github.com/Valloric/MatchTagAlways

==============================================================================
DEVELOPMENT                                                *matchup-development*

Development is tracked at https://github.com/andymass/vim-matchup.

Reporting problems~

This is a new plugin and there are likely to be some bugs.  Thorough
issue reports are encouraged.  Please read the issue template first
(ISSUE_TEMPLATE.md).  Be as precise and detailed as possible when submitting
issues.

Feature requests are also welcome.

Contributing~

Please read the contribution guidelines (CONTRIBUTING.md) before contributing.

==============================================================================
 vim:tw=78:ts=8:ft=help:norl:fen:fdl=0:fdm=marker
