Add support for custom match functions

autoload/matchit.vim

@@ -1,6 +1,6 @@
 "  matchit.vim: (global plugin) Extended "%" matching
 "  autload script of matchit plugin, see ../plugin/matchit.vim
-"  Last Change: Jan 06, 2025
+"  Last Change: Dec 23, 2025
 
 " Neovim does not support scriptversion
 if has("vimscript-4")
@@ -69,6 +69,26 @@ function matchit#Match_wrapper(word, forward, mode) range
     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

doc/matchit.txt

@@ -1,4 +1,4 @@
-*matchit.txt* Extended "%" matching  Last change: 2025 Aug 07
+*matchit.txt* Extended "%" matching  Last change: 2025 Dec 23
 
 		VIM REFERENCE MANUAL    by Benji Fisher et al
 
@@ -253,6 +253,45 @@ Examples:
 	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*