Vim syntax files ... trying to understand "contains"

Question

I'm trying to patch up a new vim syntax file for some custom format I'm using. Most of it I can understand, but the keyword "contains" is giving me trouble.

Is there anyone here who could give me an explanation of what it does (I've read the help -> didn't quite get it) in a way as if he were explaining it to a tree.

Answer 1

In general, you can only have one syntax highlighting method in one place. Therefore, to use C-like syntaxes as an example, if you define a region to start on an opening brace '{' and end on a closing brace '}', the syntax highlighting for that region will be the same.

contains= allows you to configure other syntax highlighting groups to be contained within an outer group. To follow the previous example, you may want int to be highlighted even when it is in the outer region. You could then have something like:

syn keyword Keyword int
syn region BraceBlock start='{' end='}' contains=Keyword

It is quite common to need to add items later to the list of contained keywords. There are a few ways of doing this. Firstly, you can use contains=ALL or contains=ALLBUT,Error to allow anything to be in a region. Secondly, you can use containedin to push something into the contains of another region:

syn region BraceBlock start='{' end='}'
syn keyword Keyword int containedin=BraceBlock

Thirdly, you can define anything that is "contained" as valid in this group:

syn region BraceBlock start='{' end='}' contains=CONTAINED
syn keyword Keyword int contained

Finally, you can use clusters, which make it quite easy to decide what goes where:

syn region BraceBlock start='{' end='}' contains=@MyCluster
syn keyword Keyword int
syn cluster MyCluster contains=Keyword
syn keyword Conditional if else
syn cluster MyCluster add=Conditional
" Now conditionals and keywords can appear in a BraceBlock

Without knowing exactly what you want to understand, I'm not sure what else to say - what are you trying to achieve and what is causing you problems?