Vim Syntax Clusters and File Inclusion

external sub-expression, you can nest the two, as in "$\z(...$\)". Note that only matches within a single line can be used. Multi-line matches cannot be referred to. ============================================================================== 9. Syntax clusters *:syn-cluster* *E400* :sy[ntax] cluster {cluster-name} [contains={group-name}..] [add={group-name}..] [remove={group-name}..] This command allows you to cluster a list of syntax groups together under a single name. contains={group-name}.. The cluster is set to the specified list of groups. add={group-name}.. The specified groups are added to the cluster. remove={group-name}.. The specified groups are removed from the cluster. A cluster so defined may be referred to in a contains=.., containedin=.., nextgroup=.., add=.. or remove=.. list with a "@" prefix. You can also use this notation to implicitly declare a cluster before specifying its contents. Example: > :syntax match Thing "# [^#]\+ #" contains=@ThingMembers :syntax cluster ThingMembers contains=ThingMember1,ThingMember2 As the previous example suggests, modifications to a cluster are effectively retroactive; the membership of the cluster is checked at the last minute, so to speak: > :syntax keyword A aaa :syntax keyword B bbb :syntax cluster AandB contains=A :syntax match Stuff "( aaa bbb )" contains=@AandB :syntax cluster AandB add=B " now both keywords are matched in Stuff This also has implications for nested clusters: > :syntax keyword A aaa :syntax keyword B bbb :syntax cluster SmallGroup contains=B :syntax cluster BigGroup contains=A,@SmallGroup :syntax match Stuff "( aaa bbb )" contains=@BigGroup :syntax cluster BigGroup remove=B " no effect, since B isn't in BigGroup :syntax cluster SmallGroup remove=B " now bbb isn't matched within Stuff < *E848* The maximum number of clusters is 9767. ============================================================================== 10. Including syntax files *:syn-include* *E397* It is often useful for one language's syntax file to include a syntax file for a related language. Depending on the exact relationship, this can be done in two different ways: - If top-level syntax items in the included syntax file are to be allowed at the top level in the including syntax, you can simply use the |:runtime| command: > " In cpp.vim: :runtime! syntax/c.vim :unlet b:current_syntax < - If top-level syntax items in the included syntax file are to be contained within a region in the including syntax, you can use the ":syntax include" command: :sy[ntax] include [@{grouplist-name}] {file-name} All syntax items declared in the included file will have the "contained" flag added. In addition, if a group list is specified, all top-level syntax items in the included file will be added to that list. > " In perl.vim: :syntax include @Pod <sfile>:p:h/pod.vim :syntax region perlPOD start="^=head" end="^=cut" contains=@Pod < When {file-name} is an absolute path (starts with "/", "c:", "$VAR" or "<sfile>") that file is sourced. When it is a relative path (e.g., "syntax/pod.vim") the file is searched for in 'runtimepath'. All matching files are loaded. Using a relative path is recommended, because it allows a user to replace the included file with their own version, without replacing the file that does the ":syn include". *E847* The maximum number of includes is 999. ============================================================================== 11. Synchronizing *:syn-sync* *E403* *E404* Vim wants to be able to start redrawing in any position in the document. To make this possible it needs to know the syntax state at the position where redrawing starts. :sy[ntax] sync [ccomment [group-name] | minlines={N} | ...] There are four ways to synchronize: 1. Always parse from the start of the file. |:syn-sync-first| 2. Based on

This section covers the usage of syntax clusters, including examples of how to add and remove syntax groups, highlighting the retroactive nature of cluster membership changes. It also addresses nested clusters and limitations on the number of clusters. The section then moves on to syntax file inclusion, explaining how to include syntax files for related languages using `:runtime!` or `:syntax include`. It details how `:syntax include` automatically adds the 'contained' flag and allows specifying a group list. The section also covers specifying absolute and relative paths for included files, and the limit on the number of includes. Finally, it introduces the concept of synchronizing, essential for Vim's ability to start redrawing at any position in the document.