feat: more flexible vimtex_syntax_custom_cmds

refer: #2224

autoload/vimtex/syntax/core.vim

@@ -861,6 +861,8 @@ function! vimtex#syntax#core#new_cmd(cfg) abort " {{{1
         \ 'opt': v:true,
         \ 'arg': v:true,
         \ 'argstyle': '',
+        \ 'nextgroup': '',
+        \ 'hlgroup': '',
         \}, a:cfg)
 
   " Intuitive handling of concealchar
@@ -877,72 +879,82 @@ function! vimtex#syntax#core#new_cmd(cfg) abort " {{{1
     let l:cfg.optconceal = l:cfg.conceal
   endif
 
-
   " Define group names
   let l:name = 'C' . toupper(l:cfg.name[0]) . l:cfg.name[1:]
   let l:pre = l:cfg.mathmode ? 'texMath' : 'tex'
   let l:group_cmd = l:pre . 'Cmd' . l:name
   let l:group_opt = l:pre . l:name . 'Opt'
   let l:group_arg = l:pre . l:name . 'Arg'
 
+  " Specify rules for next groups
+  if !empty(l:cfg.nextgroup)
+    let l:nextgroups = 'skipwhite nextgroup=' . l:cfg.nextgroup
+  else
+    " Add syntax rules for the optional group
+    let l:nextgroups = []
+    if l:cfg.opt
+      let l:nextgroups += [l:group_opt]
+
+      let l:opt_cfg = {'opts': l:cfg.optconceal ? 'conceal' : ''}
+      if l:cfg.arg
+        let l:opt_cfg.next = l:group_arg
+      endif
+      call vimtex#syntax#core#new_opt(l:group_opt, l:opt_cfg)
+
+      execute 'highlight def link' l:group_opt 'texOpt'
+    endif
 
-  " Add syntax rules for the argument group and optional group
-  let l:nextgroups = []
-  if l:cfg.opt
-    let l:nextgroups += [l:group_opt]
-
-    let l:opt_cfg = {'opts': l:cfg.optconceal ? 'conceal' : ''}
+    " Add syntax rules for the argument group
     if l:cfg.arg
-      let l:opt_cfg.next = l:group_arg
+      let l:nextgroups += [l:group_arg]
+
+      let l:arg_cfg = {'opts': 'contained'}
+      if l:cfg.conceal && empty(l:cfg.concealchar)
+        let l:arg_cfg.opts .= ' concealends'
+      endif
+      if l:cfg.mathmode
+        let l:arg_cfg.contains = '@texClusterMath'
+      endif
+      call vimtex#syntax#core#new_arg(l:group_arg, l:arg_cfg)
+
+      let l:style = get({
+            \ 'bold': 'texStyleBold',
+            \ 'ital': 'texStyleItal',
+            \ 'under': 'texStyleUnder',
+            \ 'boldital': 'texStyleBoth',
+            \ 'boldunder': 'texStyleBoldUnder',
+            \ 'italunder': 'texStyleItalUnder',
+            \ 'bolditalunder': 'texStyleBoldItalUnder',
+            \}, l:cfg.argstyle,
+            \ l:cfg.mathmode ? 'texMathArg' : '')
+      if !empty(l:style)
+        execute 'highlight def link' l:group_arg l:style
+      endif
     endif
-    call vimtex#syntax#core#new_opt(l:group_opt, l:opt_cfg)
-
-    execute 'highlight def link' l:group_opt 'texOpt'
-  endif
-
-  if l:cfg.arg
-    let l:nextgroups += [l:group_arg]
 
-    let l:arg_cfg = {'opts': 'contained'}
-    if l:cfg.conceal && empty(l:cfg.concealchar)
-      let l:arg_cfg.opts .= ' concealends'
-    endif
-    if l:cfg.mathmode
-      let l:arg_cfg.contains = '@texClusterMath'
-    endif
-    call vimtex#syntax#core#new_arg(l:group_arg, l:arg_cfg)
-
-    let l:style = get({
-          \ 'bold': 'texStyleBold',
-          \ 'ital': 'texStyleItal',
-          \ 'under': 'texStyleUnder',
-          \ 'boldital': 'texStyleBoth',
-          \ 'boldunder': 'texStyleBoldUnder',
-          \ 'italunder': 'texStyleItalUnder',
-          \ 'bolditalunder': 'texStyleBoldItalUnder',
-          \}, l:cfg.argstyle,
-          \ l:cfg.mathmode ? 'texMathArg' : '')
-    if !empty(l:style)
-      execute 'highlight def link' l:group_arg l:style
-    endif
+    let l:nextgroups = !empty(l:nextgroups)
+          \ ? 'skipwhite nextgroup=' . join(l:nextgroups, ',')
+          \ : ''
   endif
 
-  let l:nextgroups = !empty(l:nextgroups)
-        \ ? 'skipwhite nextgroup=' . join(l:nextgroups, ',')
-        \ : ''
-
-
-  " Add syntax rule for the command
+  " Add to cluster if necessary
   if l:cfg.mathmode
     execute 'syntax cluster texClusterMath add=' . l:group_cmd
   endif
+
+  " Create the final syntax rule
   execute 'syntax match' l:group_cmd
         \ '"\v\\' . l:cfg.name . '>"'
         \ l:cfg.conceal ? 'conceal' : ''
         \ !empty(l:cfg.concealchar) ? 'cchar=' . l:cfg.concealchar : ''
         \ l:nextgroups
         \ l:cfg.mathmode ? 'contained' : ''
-  execute 'highlight def link' l:group_cmd l:pre . 'Cmd'
+
+  " Define default highlight rule
+  execute 'highlight def link' l:group_cmd
+        \ !empty(l:cfg.hlgroup)
+        \   ? l:cfg.hlgroup
+        \   : l:pre . 'Cmd'
 endfunction
 
 " }}}1

doc/vimtex.txt

@@ -2285,6 +2285,11 @@ OPTIONS                                                        *vimtex-options*
     name~
       The command to highlight (`cmdname`).
 
+    hlgroup~
+      Default: Undefined
+      A string that can be used to indicate the target highlight group of the
+      command (`\cmdname`).
+
     mathmode~
       Default: |v:false|
       If true, then the command is a math mode command.
@@ -2323,13 +2328,20 @@ OPTIONS                                                        *vimtex-options*
         * `italunder`
         * `bolditalunder`
 
+    nextgroup~
+      Default: Undefined
+      This is a string that, if defined and not empty, specifies
+      a comma-separated list of possible next syntax groups.
+
   A couple of examples may be helpful: The first in the following list shows
   how to use bolded style on a custom vector macro such as `\vct{v}`. The
-  second shows how to conceal `\R` with `ℝ`. >
+  second shows how to conceal `\R` with `ℝ`. The third shows how one may use
+  the `nextgroup` key. >
 
     let g:vimtex_syntax_custom_cmds = [
           \ {'name': 'vct', 'mathmode': 1, 'argstyle': 'bold'},
           \ {'name': 'R', 'mathmode': 1, 'concealchar': 'ℝ'},
+          \ {'name': 'mathnote', 'mathmode': 1, 'nextgroup': 'texMathTextArg'},
           \]
 <
   Default value: []

test/test-syntax/test-custom.tex

@@ -13,6 +13,9 @@
 $\R -> ℝ$
 $\E -> 𝔼$
 $\P -> ℙ$
+$\mathnote{$Math$ + text}$
+$\mathnoteC{$Math$ + text concealed}$
+$\text{$Math$ + text reference}$
 
 \undline{underlined}
 

test/test-syntax/test-custom.vim

@@ -12,6 +12,10 @@ let g:vimtex_syntax_custom_cmds = [
       \ {'name': 'E', 'mathmode': v:true, 'concealchar': '𝔼'},
       \ {'name': 'P', 'mathmode': v:true, 'concealchar': 'ℙ'},
       \ {'name': 'undline', 'argstyle': 'bolditalunder'},
+      \ {'name': 'mathnote', 'mathmode': 1,
+      \  'nextgroup': 'texMathTextArg', 'hlgroup': 'texMathCmdText'},
+      \ {'name': 'mathnoteC', 'mathmode': 1, 'conceal': 1,
+      \  'nextgroup': 'texMathTextConcArg', 'hlgroup': 'texMathCmdText'},
       \]
 
 silent edit test-custom.tex