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.

Accepted Answer

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?

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

Solution

Problem