" matchit.vim: (global plugin) Extended "%" matching
" autload script of matchit plugin, see ../plugin/matchit.vim
-" Last Change: May 20, 2024
+" Last Change: Jan 06, 2025
" Neovim does not support scriptversion
if has("vimscript-4")
let startpos = [line("."), col(".")]
endif
+ " Check for custom match function hook
+ if exists("b:match_function")
+ let MatchFunc = b:match_function
+ try
+ let result = call(MatchFunc, [a:forward])
+ if !empty(result)
+ call cursor(result)
+ return s:CleanUp(restore_options, a:mode, startpos)
+ endif
+ catch /.*/
+ if exists("b:match_debug")
+ echohl WarningMsg
+ echom 'matchit: b:match_function error: ' .. v:exception
+ echohl NONE
+ endif
+ return s:CleanUp(restore_options, a:mode, startpos)
+ endtry
+ " Empty result: fall through to regular matching
+ endif
+
" First step: if not already done, set the script variables
" s:do_BR flag for whether there are backrefs
" s:pat parsed version of b:match_words
let default = escape(&mps, '[$^.*~\\/?]') .. (strlen(&mps) ? "," : "") ..
\ '\/\*:\*\/,#\s*if\%(n\=def\)\=:#\s*else\>:#\s*elif\%(n\=def\)\=\>:#\s*endif\>'
" s:all = pattern with all the keywords
- let match_words = match_words .. (strlen(match_words) ? "," : "") .. default
+ let match_words = s:Append(match_words, default)
let s:last_words = match_words
if match_words !~ s:notslash .. '\\\d'
let s:do_BR = 0
let s:pat = s:ParseWords(match_words)
endif
let s:all = substitute(s:pat, s:notslash .. '\zs[,:]\+', '\\|', 'g')
- " un-escape \, to ,
- let s:all = substitute(s:all, '\\,', ',', 'g')
+ " un-escape \, and \: to , and :
+ let s:all = substitute(s:all, s:notslash .. '\zs\\\(:\|,\)', '\1', 'g')
" Just in case there are too many '\(...)' groups inside the pattern, make
" sure to use \%(...) groups, so that error E872 can be avoided
let s:all = substitute(s:all, '\\(', '\\%(', 'g')
return ini .. ":" .. tailBR
endfun
+" String append item2 to item and add ',' in between items
+fun! s:Append(item, item2)
+ if a:item == ''
+ return a:item2
+ endif
+ " there is already a trailing comma, don't add another one
+ if a:item[-1:] == ','
+ return a:item .. a:item2
+ endif
+ return a:item .. ',' .. a:item2
+endfun
+
" Input a comma-separated list of groups with backrefs, such as
" a:groups = '\(foo\):end\1,\(bar\):end\1'
" and return a comma-separated list of groups with backrefs replaced:
else
let currpat = substitute(current, s:notslash .. a:branch, '\\|', 'g')
endif
- " un-escape \, to ,
- let currpat = substitute(currpat, '\\,', ',', 'g')
+ " un-escape \, and \: to , and :
+ let currpat = substitute(currpat, s:notslash .. '\zs\\\(:\|,\)', '\1', 'g')
while a:string !~ a:prefix .. currpat .. a:suffix
let tail = strpart(tail, i)
let i = matchend(tail, s:notslash .. a:comma)
else
let currpat = substitute(current, s:notslash .. a:branch, '\\|', 'g')
endif
+ " un-escape \, and \: to , and :
+ let currpat = substitute(currpat, s:notslash .. '\zs\\\(:\|,\)', '\1', 'g')
if a:0
let alttail = strpart(alttail, j)
let j = matchend(alttail, s:notslash .. a:comma)
let default = escape(&mps, '[$^.*~\\/?]') .. (strlen(&mps) ? "," : "") ..
\ '\/\*:\*\/,#\s*if\%(n\=def\)\=:#\s*else\>:#\s*elif\>:#\s*endif\>'
let s:last_mps = &mps
- let match_words = match_words .. (strlen(match_words) ? "," : "") .. default
+ let match_words = s:Append(match_words, default)
let s:last_words = match_words
if match_words !~ s:notslash .. '\\\d'
let s:do_BR = 0
-*matchit.txt* Extended "%" matching
+*matchit.txt* Extended "%" matching Last change: 2026 Jan 06
-For instructions on installing this file, type
- `:help matchit-install`
-inside Vim.
+ VIM REFERENCE MANUAL by Benji Fisher et al
-For Vim version 9.1. Last change: 2024 May 20
-
-
- VIM REFERENCE MANUAL by Benji Fisher et al
*matchit* *matchit.vim*
2.1 Temporarily disable the matchit plugin *matchit-disable* *:MatchDisable*
-To temporarily disable the matchit plugin, after it hat been loaded,
+To temporarily disable the matchit plugin, after it has been loaded,
execute this command: >
:MatchDisable
See the $VIMRUNTIME/ftplugin/vim.vim for an example that uses both
syntax and a regular expression.
+ *b:match_function*
+If b:match_function is defined, matchit.vim will first call this function to
+perform matching. This is useful for languages with an indentation-based block
+structure (such as Python) or other complex matching requirements that cannot
+be expressed with regular expression patterns.
+
+The function should accept one argument:
+ forward - 1 for forward search (% command)
+ 0 for backward search (g% command)
+
+The function should return a list with one of these values:
+ [line, col] - Match found at the specified position
+ [] - No match found; fall through to regular matching
+ (|b:match_words|, matchpairs, etc.)
+
+The cursor position is not changed by the function; matchit handles cursor
+movement based on the returned position.
+
+If the function throws an error, matchit gives up and doesn't continue.
+Enable |b:match_debug| to see error messages from custom match functions.
+
+Python example (simplified): >
+ let s:keywords = {'if': 'elif\|else', 'elif': 'elif\|else'}
+
+ function! s:PythonMatch(forward) abort
+ let keyword = matchstr(getline('.'), '^\s*\zs\w\+')
+ let pattern = get(s:keywords, keyword, '')
+ if empty(pattern) | return [] | endif
+
+ let flags = a:forward ? 'nW' : 'nbW'
+ let [lnum, col] = searchpos('^\s*\%(' . pattern . '\)\>', flags, 0, 0,
+ \ 'indent(".") != ' . indent('.'))
+ return lnum > 0 ? [lnum, col] : []
+ endfunction
+
+ let b:match_function = function('s:PythonMatch')
+<
+See |matchit-newlang| below for more details on supporting new languages.
+
==============================================================================
4. Supporting a New Language *matchit-newlang*
*b:match_words*
The format for |b:match_words| is similar to that of the 'matchpairs' option:
it is a comma (,)-separated list of groups; each group is a colon(:)-separated
-list of patterns (regular expressions). Commas and backslashes that are part
-of a pattern should be escaped with backslashes ('\:' and '\,'). It is OK to
-have only one group; the effect is undefined if a group has only one pattern.
+list of patterns (regular expressions). Commas and colons that are part of a
+pattern should be escaped with backslashes ('\:' and '\,'). It is OK to have
+only one group; the effect is undefined if a group has only one pattern.
A simple example is >
:let b:match_words = '\<if\>:\<endif\>,'
\ . '\<while\>:\<continue\>:\<break\>:\<endwhile\>'
if keywords are only recognized after the start of a line or after a
semicolon (;), with optional white space.
- *matchit-backref* *matchit-\1*
+ *matchit-backref*
In any group, the expressions |\1|, |\2|, ..., |\9| refer to parts of the
INITIAL pattern enclosed in |\(|escaped parentheses|\)|. These are referred
to as back references, or backrefs. For example, >
projects / thirdparty / vim.git / commitdiff
