Keeping the End, Containing Many Items, Following Groups, and Other Arguments

nested region, it is hidden from the first xBlock region. Then at the last } the first xBlock region ends. KEEPING THE END Consider the following two syntax items: > :syntax region xComment start=/%/ end=/$/ contained :syntax region xPreProc start=/#/ end=/$/ contains=xComment You define a comment as anything from % to the end of the line. A preprocessor directive is anything from # to the end of the line. Because you can have a comment on a preprocessor line, the preprocessor definition includes a "contains=xComment" argument. Now look what happens with this text: #define X = Y % Comment text ~ int foo = 1; ~ What you see is that the second line is also highlighted as xPreProc. The preprocessor directive should end at the end of the line. That is why you have used "end=/$/". So what is going wrong? The problem is the contained comment. The comment starts with % and ends at the end of the line. After the comment ends, the preprocessor syntax continues. This is after the end of the line has been seen, so the next line is included as well. To avoid this problem and to avoid a contained syntax item eating a needed end of line, use the "keepend" argument. This takes care of the double end-of-line matching: > :syntax region xComment start=/%/ end=/$/ contained :syntax region xPreProc start=/#/ end=/$/ contains=xComment keepend CONTAINING MANY ITEMS You can use the contains argument to specify that everything can be contained. For example: > :syntax region xList start=/\[/ end=/\]/ contains=ALL All syntax items will be contained in this one. It also contains itself, but not at the same position (that would cause an endless loop). You can specify that some groups are not contained. Thus contain all groups but the ones that are listed: > :syntax region xList start=/\[/ end=/\]/ contains=ALLBUT,xString With the "TOP" item you can include all items that don't have a "contained" argument. "CONTAINED" is used to only include items with a "contained" argument. See |:syn-contains| for the details. ============================================================================== *44.6* Following groups The x language has statements in this form: if (condition) then ~ You want to highlight the three items differently. But "(condition)" and "then" might also appear in other places, where they get different highlighting. This is how you can do this: > :syntax match xIf /if/ nextgroup=xIfCondition skipwhite :syntax match xIfCondition /([^)]*)/ contained nextgroup=xThen skipwhite :syntax match xThen /then/ contained The "nextgroup" argument specifies which item can come next. This is not required. If none of the items that are specified are found, nothing happens. For example, in this text: if not (condition) then ~ The "if" is matched by xIf. "not" doesn't match the specified nextgroup xIfCondition, thus only the "if" is highlighted. The "skipwhite" argument tells Vim that white space (spaces and tabs) may appear in between the items. Similar arguments are "skipnl", which allows a line break in between the items, and "skipempty", which allows empty lines. Notice that "skipnl" doesn't skip an empty line, something must match after the line break. ============================================================================== *44.7* Other arguments MATCHGROUP When you define a region, the entire region is highlighted according to the group name specified. To highlight the text enclosed in parentheses () with the group xInside, for example, use the following command: > :syntax region xInside start=/(/ end=/)/ Suppose, that you want to highlight the parentheses differently. You can do this with a lot of convoluted region statements, or you can use the "matchgroup" argument. This tells Vim to highlight the start and end of a region with a different highlight group (in this case, the xParen group): > :syntax region xInside matchgroup=xParen start=/(/ end=/)/ The "matchgroup" argument

This section discusses how to handle contained syntax items that might inadvertently consume the end-of-line character using the 'keepend' argument. It then explores how to contain many or all syntax items within a region using 'contains=ALL' and 'contains=ALLBUT'. The section also explains how to use 'nextgroup' to define a sequence of syntax items, and introduces the 'skipwhite', 'skipnl', and 'skipempty' arguments for handling whitespace and line breaks. Finally, it touches on using 'matchgroup' to highlight the start and end of a region differently.