Mercurial > vim
annotate runtime/doc/usr_44.txt @ 14572:7bf554378133
Added tag v8.1.0299 for changeset 44df6e5c17c3a3771089efc3e4c2da0b3cc340b5
| author | Christian Brabandt <cb@256bit.org> |
|---|---|
| date | Sun, 19 Aug 2018 17:15:06 +0200 |
| parents | 5c5908e81e93 |
| children | af69c9335223 |
| rev | line source |
|---|---|
| 13963 | 1 *usr_44.txt* For Vim version 8.1. Last change: 2017 May 06 |
| 7 | 2 |
| 3 VIM USER MANUAL - by Bram Moolenaar | |
| 4 | |
| 5 Your own syntax highlighted | |
| 6 | |
| 7 | |
| 8 Vim comes with highlighting for a couple of hundred different file types. If | |
| 9 the file you are editing isn't included, read this chapter to find out how to | |
| 10 get this type of file highlighted. Also see |:syn-define| in the reference | |
| 11 manual. | |
| 12 | |
| 13 |44.1| Basic syntax commands | |
| 14 |44.2| Keywords | |
| 15 |44.3| Matches | |
| 16 |44.4| Regions | |
| 17 |44.5| Nested items | |
| 18 |44.6| Following groups | |
| 19 |44.7| Other arguments | |
| 20 |44.8| Clusters | |
| 21 |44.9| Including another syntax file | |
| 22 |44.10| Synchronizing | |
| 23 |44.11| Installing a syntax file | |
| 24 |44.12| Portable syntax file layout | |
| 25 | |
| 26 Next chapter: |usr_45.txt| Select your language | |
| 27 Previous chapter: |usr_43.txt| Using filetypes | |
| 28 Table of contents: |usr_toc.txt| | |
| 29 | |
| 30 ============================================================================== | |
| 31 *44.1* Basic syntax commands | |
| 32 | |
| 33 Using an existing syntax file to start with will save you a lot of time. Try | |
| 34 finding a syntax file in $VIMRUNTIME/syntax for a language that is similar. | |
| 35 These files will also show you the normal layout of a syntax file. To | |
| 36 understand it, you need to read the following. | |
| 37 | |
| 38 Let's start with the basic arguments. Before we start defining any new | |
| 39 syntax, we need to clear out any old definitions: > | |
| 40 | |
| 41 :syntax clear | |
| 42 | |
| 43 This isn't required in the final syntax file, but very useful when | |
| 44 experimenting. | |
| 45 | |
| 46 There are more simplifications in this chapter. If you are writing a syntax | |
| 47 file to be used by others, read all the way through the end to find out the | |
| 48 details. | |
| 49 | |
| 50 | |
| 51 LISTING DEFINED ITEMS | |
| 52 | |
| 53 To check which syntax items are currently defined, use this command: > | |
| 54 | |
| 55 :syntax | |
| 56 | |
| 57 You can use this to check which items have actually been defined. Quite | |
| 58 useful when you are experimenting with a new syntax file. It also shows the | |
| 59 colors used for each item, which helps to find out what is what. | |
| 60 To list the items in a specific syntax group use: > | |
| 61 | |
| 62 :syntax list {group-name} | |
| 63 | |
| 64 This also can be used to list clusters (explained in |44.8|). Just include | |
| 65 the @ in the name. | |
| 66 | |
| 67 | |
| 68 MATCHING CASE | |
| 69 | |
| 70 Some languages are not case sensitive, such as Pascal. Others, such as C, are | |
| 71 case sensitive. You need to tell which type you have with the following | |
| 72 commands: > | |
| 73 :syntax case match | |
| 74 :syntax case ignore | |
| 75 | |
| 76 The "match" argument means that Vim will match the case of syntax elements. | |
| 77 Therefore, "int" differs from "Int" and "INT". If the "ignore" argument is | |
| 78 used, the following are equivalent: "Procedure", "PROCEDURE" and "procedure". | |
| 79 The ":syntax case" commands can appear anywhere in a syntax file and affect | |
| 80 the syntax definitions that follow. In most cases, you have only one ":syntax | |
| 81 case" command in your syntax file; if you work with an unusual language that | |
| 82 contains both case-sensitive and non-case-sensitive elements, however, you can | |
| 83 scatter the ":syntax case" command throughout the file. | |
| 84 | |
| 85 ============================================================================== | |
| 86 *44.2* Keywords | |
| 87 | |
| 88 The most basic syntax elements are keywords. To define a keyword, use the | |
| 89 following form: > | |
| 90 | |
| 91 :syntax keyword {group} {keyword} ... | |
| 92 | |
| 93 The {group} is the name of a syntax group. With the ":highlight" command you | |
| 94 can assign colors to a {group}. The {keyword} argument is an actual keyword. | |
| 95 Here are a few examples: > | |
| 96 | |
| 97 :syntax keyword xType int long char | |
| 98 :syntax keyword xStatement if then else endif | |
| 99 | |
| 100 This example uses the group names "xType" and "xStatement". By convention, | |
| 101 each group name is prefixed by the filetype for the language being defined. | |
| 102 This example defines syntax for the x language (eXample language without an | |
| 103 interesting name). In a syntax file for "csh" scripts the name "cshType" | |
| 104 would be used. Thus the prefix is equal to the value of 'filetype'. | |
| 105 These commands cause the words "int", "long" and "char" to be highlighted | |
| 106 one way and the words "if", "then", "else" and "endif" to be highlighted | |
| 107 another way. Now you need to connect the x group names to standard Vim | |
| 108 names. You do this with the following commands: > | |
| 109 | |
| 110 :highlight link xType Type | |
| 111 :highlight link xStatement Statement | |
| 112 | |
| 113 This tells Vim to highlight "xType" like "Type" and "xStatement" like | |
| 114 "Statement". See |group-name| for the standard names. | |
| 115 | |
| 116 | |
| 117 UNUSUAL KEYWORDS | |
| 118 | |
| 119 The characters used in a keyword must be in the 'iskeyword' option. If you | |
| 120 use another character, the word will never match. Vim doesn't give a warning | |
| 121 message for this. | |
| 122 The x language uses the '-' character in keywords. This is how it's done: | |
| 123 > | |
| 124 :setlocal iskeyword+=- | |
| 125 :syntax keyword xStatement when-not | |
| 126 | |
| 127 The ":setlocal" command is used to change 'iskeyword' only for the current | |
| 128 buffer. Still it does change the behavior of commands like "w" and "*". If | |
| 129 that is not wanted, don't define a keyword but use a match (explained in the | |
| 130 next section). | |
| 131 | |
| 132 The x language allows for abbreviations. For example, "next" can be | |
| 133 abbreviated to "n", "ne" or "nex". You can define them by using this command: | |
| 134 > | |
| 135 :syntax keyword xStatement n[ext] | |
| 136 | |
| 137 This doesn't match "nextone", keywords always match whole words only. | |
| 138 | |
| 139 ============================================================================== | |
| 140 *44.3* Matches | |
| 141 | |
| 142 Consider defining something a bit more complex. You want to match ordinary | |
| 143 identifiers. To do this, you define a match syntax item. This one matches | |
| 144 any word consisting of only lowercase letters: > | |
| 145 | |
| 146 :syntax match xIdentifier /\<\l\+\>/ | |
| 147 < | |
| 148 Note: | |
| 149 Keywords overrule any other syntax item. Thus the keywords "if", | |
| 150 "then", etc., will be keywords, as defined with the ":syntax keyword" | |
| 151 commands above, even though they also match the pattern for | |
| 152 xIdentifier. | |
| 153 | |
| 154 The part at the end is a pattern, like it's used for searching. The // is | |
| 155 used to surround the pattern (like how it's done in a ":substitute" command). | |
| 156 You can use any other character, like a plus or a quote. | |
| 157 | |
| 158 Now define a match for a comment. In the x language it is anything from # to | |
| 159 the end of a line: > | |
| 160 | |
| 161 :syntax match xComment /#.*/ | |
| 162 | |
| 163 Since you can use any search pattern, you can highlight very complex things | |
| 164 with a match item. See |pattern| for help on search patterns. | |
| 165 | |
| 166 ============================================================================== | |
| 167 *44.4* Regions | |
| 168 | |
| 169 In the example x language, strings are enclosed in double quotation marks ("). | |
| 170 To highlight strings you define a region. You need a region start (double | |
| 171 quote) and a region end (double quote). The definition is as follows: > | |
| 172 | |
| 173 :syntax region xString start=/"/ end=/"/ | |
| 174 | |
| 175 The "start" and "end" directives define the patterns used to find the start | |
| 176 and end of the region. But what about strings that look like this? | |
| 177 | |
| 178 "A string with a double quote (\") in it" ~ | |
| 179 | |
| 180 This creates a problem: The double quotation marks in the middle of the string | |
| 181 will end the region. You need to tell Vim to skip over any escaped double | |
| 182 quotes in the string. Do this with the skip keyword: > | |
| 183 | |
| 184 :syntax region xString start=/"/ skip=/\\"/ end=/"/ | |
| 185 | |
| 186 The double backslash matches a single backslash, since the backslash is a | |
| 187 special character in search patterns. | |
| 188 | |
| 189 When to use a region instead of a match? The main difference is that a match | |
| 190 item is a single pattern, which must match as a whole. A region starts as | |
| 191 soon as the "start" pattern matches. Whether the "end" pattern is found or | |
| 192 not doesn't matter. Thus when the item depends on the "end" pattern to match, | |
| 193 you cannot use a region. Otherwise, regions are often simpler to define. And | |
| 194 it is easier to use nested items, as is explained in the next section. | |
| 195 | |
| 196 ============================================================================== | |
| 197 *44.5* Nested items | |
| 198 | |
| 199 Take a look at this comment: | |
| 200 | |
| 201 %Get input TODO: Skip white space ~ | |
| 202 | |
| 203 You want to highlight TODO in big yellow letters, even though it is in a | |
| 204 comment that is highlighted blue. To let Vim know about this, you define the | |
| 205 following syntax groups: > | |
| 206 | |
| 207 :syntax keyword xTodo TODO contained | |
| 208 :syntax match xComment /%.*/ contains=xTodo | |
| 209 | |
| 210 In the first line, the "contained" argument tells Vim that this keyword can | |
| 211 exist only inside another syntax item. The next line has "contains=xTodo". | |
| 212 This indicates that the xTodo syntax element is inside it. The result is that | |
| 213 the comment line as a whole is matched with "xComment" and made blue. The | |
| 214 word TODO inside it is matched by xTodo and highlighted yellow (highlighting | |
| 215 for xTodo was setup for this). | |
| 216 | |
| 217 | |
| 218 RECURSIVE NESTING | |
| 219 | |
| 220 The x language defines code blocks in curly braces. And a code block may | |
| 221 contain other code blocks. This can be defined this way: > | |
| 222 | |
| 223 :syntax region xBlock start=/{/ end=/}/ contains=xBlock | |
| 224 | |
| 225 Suppose you have this text: | |
| 226 | |
| 227 while i < b { ~ | |
| 228 if a { ~ | |
| 229 b = c; ~ | |
| 230 } ~ | |
| 231 } ~ | |
| 232 | |
| 233 First a xBlock starts at the { in the first line. In the second line another | |
| 234 { is found. Since we are inside a xBlock item, and it contains itself, a | |
| 235 nested xBlock item will start here. Thus the "b = c" line is inside the | |
| 236 second level xBlock region. Then a } is found in the next line, which matches | |
| 237 with the end pattern of the region. This ends the nested xBlock. Because the | |
| 238 } is included in the nested region, it is hidden from the first xBlock region. | |
| 239 Then at the last } the first xBlock region ends. | |
| 240 | |
| 241 | |
| 242 KEEPING THE END | |
| 243 | |
| 244 Consider the following two syntax items: > | |
| 245 | |
| 246 :syntax region xComment start=/%/ end=/$/ contained | |
| 247 :syntax region xPreProc start=/#/ end=/$/ contains=xComment | |
| 248 | |
| 249 You define a comment as anything from % to the end of the line. A | |
| 250 preprocessor directive is anything from # to the end of the line. Because you | |
| 251 can have a comment on a preprocessor line, the preprocessor definition | |
| 252 includes a "contains=xComment" argument. Now look what happens with this | |
| 253 text: | |
| 254 | |
| 255 #define X = Y % Comment text ~ | |
| 256 int foo = 1; ~ | |
| 257 | |
| 258 What you see is that the second line is also highlighted as xPreProc. The | |
| 259 preprocessor directive should end at the end of the line. That is why | |
| 260 you have used "end=/$/". So what is going wrong? | |
| 261 The problem is the contained comment. The comment starts with % and ends | |
| 262 at the end of the line. After the comment ends, the preprocessor syntax | |
| 263 continues. This is after the end of the line has been seen, so the next | |
| 264 line is included as well. | |
| 265 To avoid this problem and to avoid a contained syntax item eating a needed | |
| 266 end of line, use the "keepend" argument. This takes care of | |
| 267 the double end-of-line matching: > | |
| 268 | |
| 269 :syntax region xComment start=/%/ end=/$/ contained | |
| 270 :syntax region xPreProc start=/#/ end=/$/ contains=xComment keepend | |
| 271 | |
| 272 | |
| 273 CONTAINING MANY ITEMS | |
| 274 | |
| 275 You can use the contains argument to specify that everything can be contained. | |
| 276 For example: > | |
| 277 | |
| 278 :syntax region xList start=/\[/ end=/\]/ contains=ALL | |
| 279 | |
| 280 All syntax items will be contained in this one. It also contains itself, but | |
| 281 not at the same position (that would cause an endless loop). | |
| 282 You can specify that some groups are not contained. Thus contain all | |
| 283 groups but the ones that are listed: | |
| 284 > | |
| 285 :syntax region xList start=/\[/ end=/\]/ contains=ALLBUT,xString | |
| 286 | |
| 287 With the "TOP" item you can include all items that don't have a "contained" | |
| 288 argument. "CONTAINED" is used to only include items with a "contained" | |
| 289 argument. See |:syn-contains| for the details. | |
| 290 | |
| 291 ============================================================================== | |
| 292 *44.6* Following groups | |
| 293 | |
| 294 The x language has statements in this form: | |
| 295 | |
| 296 if (condition) then ~ | |
| 297 | |
| 298 You want to highlight the three items differently. But "(condition)" and | |
| 299 "then" might also appear in other places, where they get different | |
| 300 highlighting. This is how you can do this: > | |
| 301 | |
| 302 :syntax match xIf /if/ nextgroup=xIfCondition skipwhite | |
| 303 :syntax match xIfCondition /([^)]*)/ contained nextgroup=xThen skipwhite | |
| 304 :syntax match xThen /then/ contained | |
| 305 | |
| 306 The "nextgroup" argument specifies which item can come next. This is not | |
| 307 required. If none of the items that are specified are found, nothing happens. | |
| 308 For example, in this text: | |
| 309 | |
| 310 if not (condition) then ~ | |
| 311 | |
| 312 The "if" is matched by xIf. "not" doesn't match the specified nextgroup | |
| 313 xIfCondition, thus only the "if" is highlighted. | |
| 314 | |
| 315 The "skipwhite" argument tells Vim that white space (spaces and tabs) may | |
| 316 appear in between the items. Similar arguments are "skipnl", which allows a | |
| 317 line break in between the items, and "skipempty", which allows empty lines. | |
| 318 Notice that "skipnl" doesn't skip an empty line, something must match after | |
| 319 the line break. | |
| 320 | |
| 321 ============================================================================== | |
| 322 *44.7* Other arguments | |
| 323 | |
| 324 MATCHGROUP | |
| 325 | |
| 326 When you define a region, the entire region is highlighted according to the | |
| 327 group name specified. To highlight the text enclosed in parentheses () with | |
| 328 the group xInside, for example, use the following command: > | |
| 329 | |
| 330 :syntax region xInside start=/(/ end=/)/ | |
| 331 | |
| 332 Suppose, that you want to highlight the parentheses differently. You can do | |
| 333 this with a lot of convoluted region statements, or you can use the | |
| 334 "matchgroup" argument. This tells Vim to highlight the start and end of a | |
| 335 region with a different highlight group (in this case, the xParen group): > | |
| 336 | |
| 337 :syntax region xInside matchgroup=xParen start=/(/ end=/)/ | |
| 338 | |
| 339 The "matchgroup" argument applies to the start or end match that comes after | |
| 340 it. In the previous example both start and end are highlighted with xParen. | |
| 341 To highlight the end with xParenEnd: > | |
| 342 | |
| 343 :syntax region xInside matchgroup=xParen start=/(/ | |
| 344 \ matchgroup=xParenEnd end=/)/ | |
| 345 | |
| 346 A side effect of using "matchgroup" is that contained items will not match in | |
| 347 the start or end of the region. The example for "transparent" uses this. | |
| 348 | |
| 349 | |
| 350 TRANSPARENT | |
| 351 | |
| 352 In a C language file you would like to highlight the () text after a "while" | |
| 353 differently from the () text after a "for". In both of these there can be | |
| 354 nested () items, which should be highlighted in the same way. You must make | |
| 355 sure the () highlighting stops at the matching ). This is one way to do this: | |
| 356 > | |
| 357 :syntax region cWhile matchgroup=cWhile start=/while\s*(/ end=/)/ | |
| 358 \ contains=cCondNest | |
| 359 :syntax region cFor matchgroup=cFor start=/for\s*(/ end=/)/ | |
| 360 \ contains=cCondNest | |
| 361 :syntax region cCondNest start=/(/ end=/)/ contained transparent | |
| 362 | |
| 363 Now you can give cWhile and cFor different highlighting. The cCondNest item | |
| 364 can appear in either of them, but take over the highlighting of the item it is | |
| 365 contained in. The "transparent" argument causes this. | |
| 366 Notice that the "matchgroup" argument has the same group as the item | |
| 367 itself. Why define it then? Well, the side effect of using a matchgroup is | |
| 368 that contained items are not found in the match with the start item then. | |
| 369 This avoids that the cCondNest group matches the ( just after the "while" or | |
| 370 "for". If this would happen, it would span the whole text until the matching | |
| 371 ) and the region would continue after it. Now cCondNest only matches after | |
| 372 the match with the start pattern, thus after the first (. | |
| 373 | |
| 374 | |
| 375 OFFSETS | |
| 376 | |
| 377 Suppose you want to define a region for the text between ( and ) after an | |
| 378 "if". But you don't want to include the "if" or the ( and ). You can do this | |
| 379 by specifying offsets for the patterns. Example: > | |
| 380 | |
| 381 :syntax region xCond start=/if\s*(/ms=e+1 end=/)/me=s-1 | |
| 382 | |
| 383 The offset for the start pattern is "ms=e+1". "ms" stands for Match Start. | |
| 384 This defines an offset for the start of the match. Normally the match starts | |
| 385 where the pattern matches. "e+1" means that the match now starts at the end | |
| 386 of the pattern match, and then one character further. | |
| 387 The offset for the end pattern is "me=s-1". "me" stands for Match End. | |
| 388 "s-1" means the start of the pattern match and then one character back. The | |
| 389 result is that in this text: | |
| 390 | |
| 391 if (foo == bar) ~ | |
| 392 | |
| 393 Only the text "foo == bar" will be highlighted as xCond. | |
| 394 | |
| 395 More about offsets here: |:syn-pattern-offset|. | |
| 396 | |
| 397 | |
| 398 ONELINE | |
| 399 | |
| 400 The "oneline" argument indicates that the region does not cross a line | |
| 401 boundary. For example: > | |
| 402 | |
| 403 :syntax region xIfThen start=/if/ end=/then/ oneline | |
| 404 | |
| 405 This defines a region that starts at "if" and ends at "then". But if there is | |
| 406 no "then" after the "if", the region doesn't match. | |
| 407 | |
| 408 Note: | |
| 409 When using "oneline" the region doesn't start if the end pattern | |
| 410 doesn't match in the same line. Without "oneline" Vim does _not_ | |
| 411 check if there is a match for the end pattern. The region starts even | |
| 412 when the end pattern doesn't match in the rest of the file. | |
| 413 | |
| 414 | |
| 415 CONTINUATION LINES AND AVOIDING THEM | |
| 416 | |
| 417 Things now become a little more complex. Let's define a preprocessor line. | |
| 418 This starts with a # in the first column and continues until the end of the | |
| 419 line. A line that ends with \ makes the next line a continuation line. The | |
| 420 way you handle this is to allow the syntax item to contain a continuation | |
| 421 pattern: > | |
| 422 | |
| 423 :syntax region xPreProc start=/^#/ end=/$/ contains=xLineContinue | |
| 424 :syntax match xLineContinue "\\$" contained | |
| 425 | |
| 426 In this case, although xPreProc normally matches a single line, the group | |
| 427 contained in it (namely xLineContinue) lets it go on for more than one line. | |
| 428 For example, it would match both of these lines: | |
| 429 | |
| 430 #define SPAM spam spam spam \ ~ | |
| 431 bacon and spam ~ | |
| 432 | |
| 433 In this case, this is what you want. If it is not what you want, you can call | |
| 434 for the region to be on a single line by adding "excludenl" to the contained | |
| 435 pattern. For example, you want to highlight "end" in xPreProc, but only at | |
| 436 the end of the line. To avoid making the xPreProc continue on the next line, | |
| 437 like xLineContinue does, use "excludenl" like this: > | |
| 438 | |
| 439 :syntax region xPreProc start=/^#/ end=/$/ | |
| 440 \ contains=xLineContinue,xPreProcEnd | |
| 441 :syntax match xPreProcEnd excludenl /end$/ contained | |
| 442 :syntax match xLineContinue "\\$" contained | |
| 443 | |
| 444 "excludenl" must be placed before the pattern. Since "xLineContinue" doesn't | |
| 445 have "excludenl", a match with it will extend xPreProc to the next line as | |
| 446 before. | |
| 447 | |
| 448 ============================================================================== | |
| 449 *44.8* Clusters | |
| 450 | |
| 451 One of the things you will notice as you start to write a syntax file is that | |
| 452 you wind up generating a lot of syntax groups. Vim enables you to define a | |
| 453 collection of syntax groups called a cluster. | |
| 454 Suppose you have a language that contains for loops, if statements, while | |
| 455 loops, and functions. Each of them contains the same syntax elements: numbers | |
| 456 and identifiers. You define them like this: > | |
| 457 | |
| 458 :syntax match xFor /^for.*/ contains=xNumber,xIdent | |
| 459 :syntax match xIf /^if.*/ contains=xNumber,xIdent | |
| 460 :syntax match xWhile /^while.*/ contains=xNumber,xIdent | |
| 461 | |
| 462 You have to repeat the same "contains=" every time. If you want to add | |
| 463 another contained item, you have to add it three times. Syntax clusters | |
| 464 simplify these definitions by enabling you to have one cluster stand for | |
| 465 several syntax groups. | |
| 466 To define a cluster for the two items that the three groups contain, use | |
| 467 the following command: > | |
| 468 | |
| 469 :syntax cluster xState contains=xNumber,xIdent | |
| 470 | |
| 471 Clusters are used inside other syntax items just like any syntax group. | |
| 472 Their names start with @. Thus, you can define the three groups like this: > | |
| 473 | |
| 474 :syntax match xFor /^for.*/ contains=@xState | |
| 475 :syntax match xIf /^if.*/ contains=@xState | |
| 476 :syntax match xWhile /^while.*/ contains=@xState | |
| 477 | |
| 478 You can add new group names to this cluster with the "add" argument: > | |
| 479 | |
| 480 :syntax cluster xState add=xString | |
| 481 | |
| 482 You can remove syntax groups from this list as well: > | |
| 483 | |
| 484 :syntax cluster xState remove=xNumber | |
| 485 | |
| 486 ============================================================================== | |
| 487 *44.9* Including another syntax file | |
| 488 | |
| 489 The C++ language syntax is a superset of the C language. Because you do not | |
| 490 want to write two syntax files, you can have the C++ syntax file read in the | |
| 491 one for C by using the following command: > | |
| 492 | |
| 493 :runtime! syntax/c.vim | |
| 494 | |
| 495 The ":runtime!" command searches 'runtimepath' for all "syntax/c.vim" files. | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
496 This makes the C parts of the C++ syntax be defined like for C files. If you |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
497 have replaced the c.vim syntax file, or added items with an extra file, these |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
498 will be loaded as well. |
| 7 | 499 After loading the C syntax items the specific C++ items can be defined. |
| 500 For example, add keywords that are not used in C: > | |
| 501 | |
| 502 :syntax keyword cppStatement new delete this friend using | |
| 503 | |
| 504 This works just like in any other syntax file. | |
| 505 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
506 Now consider the Perl language. A Perl script consists of two distinct parts: |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
507 a documentation section in POD format, and a program written in Perl itself. |
| 7 | 508 The POD section starts with "=head" and ends with "=cut". |
| 509 You want to define the POD syntax in one file, and use it from the Perl | |
| 510 syntax file. The ":syntax include" command reads in a syntax file and stores | |
| 511 the elements it defined in a syntax cluster. For Perl, the statements are as | |
| 512 follows: > | |
| 513 | |
| 514 :syntax include @Pod <sfile>:p:h/pod.vim | |
| 515 :syntax region perlPOD start=/^=head/ end=/^=cut/ contains=@Pod | |
| 516 | |
| 517 When "=head" is found in a Perl file, the perlPOD region starts. In this | |
| 518 region the @Pod cluster is contained. All the items defined as top-level | |
| 519 items in the pod.vim syntax files will match here. When "=cut" is found, the | |
| 520 region ends and we go back to the items defined in the Perl file. | |
| 521 The ":syntax include" command is clever enough to ignore a ":syntax clear" | |
| 522 command in the included file. And an argument such as "contains=ALL" will | |
| 523 only contain items defined in the included file, not in the file that includes | |
| 524 it. | |
| 525 The "<sfile>:p:h/" part uses the name of the current file (<sfile>), | |
| 526 expands it to a full path (:p) and then takes the head (:h). This results in | |
| 527 the directory name of the file. This causes the pod.vim file in the same | |
| 528 directory to be included. | |
| 529 | |
| 530 ============================================================================== | |
| 531 *44.10* Synchronizing | |
| 532 | |
| 533 Compilers have it easy. They start at the beginning of a file and parse it | |
| 534 straight through. Vim does not have it so easy. It must start in the middle, | |
| 535 where the editing is being done. So how does it tell where it is? | |
| 536 The secret is the ":syntax sync" command. This tells Vim how to figure out | |
| 537 where it is. For example, the following command tells Vim to scan backward | |
| 538 for the beginning or end of a C-style comment and begin syntax coloring from | |
| 539 there: > | |
| 540 | |
| 541 :syntax sync ccomment | |
| 542 | |
| 543 You can tune this processing with some arguments. The "minlines" argument | |
| 544 tells Vim the minimum number of lines to look backward, and "maxlines" tells | |
| 545 the editor the maximum number of lines to scan. | |
| 546 For example, the following command tells Vim to look at least 10 lines | |
| 547 before the top of the screen: > | |
| 548 | |
| 549 :syntax sync ccomment minlines=10 maxlines=500 | |
| 550 | |
| 551 If it cannot figure out where it is in that space, it starts looking farther | |
| 552 and farther back until it figures out what to do. But it looks no farther | |
| 236 | 553 back than 500 lines. (A large "maxlines" slows down processing. A small one |
| 7 | 554 might cause synchronization to fail.) |
| 555 To make synchronizing go a bit faster, tell Vim which syntax items can be | |
| 556 skipped. Every match and region that only needs to be used when actually | |
| 557 displaying text can be given the "display" argument. | |
| 558 By default, the comment to be found will be colored as part of the Comment | |
| 559 syntax group. If you want to color things another way, you can specify a | |
| 560 different syntax group: > | |
| 561 | |
| 562 :syntax sync ccomment xAltComment | |
| 563 | |
| 564 If your programming language does not have C-style comments in it, you can try | |
| 565 another method of synchronization. The simplest way is to tell Vim to space | |
| 566 back a number of lines and try to figure out things from there. The following | |
| 567 command tells Vim to go back 150 lines and start parsing from there: > | |
| 568 | |
| 569 :syntax sync minlines=150 | |
| 570 | |
| 571 A large "minlines" value can make Vim slower, especially when scrolling | |
| 572 backwards in the file. | |
| 573 Finally, you can specify a syntax group to look for by using this command: | |
| 574 > | |
| 575 :syntax sync match {sync-group-name} | |
| 576 \ grouphere {group-name} {pattern} | |
| 577 | |
| 578 This tells Vim that when it sees {pattern} the syntax group named {group-name} | |
| 579 begins just after the pattern given. The {sync-group-name} is used to give a | |
| 580 name to this synchronization specification. For example, the sh scripting | |
| 581 language begins an if statement with "if" and ends it with "fi": | |
| 582 | |
| 583 if [ --f file.txt ] ; then ~ | |
| 584 echo "File exists" ~ | |
| 585 fi ~ | |
| 586 | |
| 587 To define a "grouphere" directive for this syntax, you use the following | |
| 588 command: > | |
| 589 | |
| 590 :syntax sync match shIfSync grouphere shIf "\<if\>" | |
| 591 | |
| 592 The "groupthere" argument tells Vim that the pattern ends a group. For | |
| 593 example, the end of the if/fi group is as follows: > | |
| 594 | |
| 595 :syntax sync match shIfSync groupthere NONE "\<fi\>" | |
| 596 | |
| 597 In this example, the NONE tells Vim that you are not in any special syntax | |
| 598 region. In particular, you are not inside an if block. | |
| 599 | |
| 600 You also can define matches and regions that are with no "grouphere" or | |
| 601 "groupthere" arguments. These groups are for syntax groups skipped during | |
| 602 synchronization. For example, the following skips over anything inside {}, | |
| 603 even if it would normally match another synchronization method: > | |
| 604 | |
| 605 :syntax sync match xSpecial /{.*}/ | |
| 606 | |
| 607 More about synchronizing in the reference manual: |:syn-sync|. | |
| 608 | |
| 609 ============================================================================== | |
| 610 *44.11* Installing a syntax file | |
| 611 | |
| 612 When your new syntax file is ready to be used, drop it in a "syntax" directory | |
| 613 in 'runtimepath'. For Unix that would be "~/.vim/syntax". | |
| 614 The name of the syntax file must be equal to the file type, with ".vim" | |
| 615 added. Thus for the x language, the full path of the file would be: | |
| 616 | |
| 617 ~/.vim/syntax/x.vim ~ | |
| 618 | |
| 619 You must also make the file type be recognized. See |43.2|. | |
| 620 | |
| 621 If your file works well, you might want to make it available to other Vim | |
| 622 users. First read the next section to make sure your file works well for | |
| 623 others. Then e-mail it to the Vim maintainer: <maintainer@vim.org>. Also | |
| 624 explain how the filetype can be detected. With a bit of luck your file will | |
| 625 be included in the next Vim version! | |
| 626 | |
| 627 | |
| 628 ADDING TO AN EXISTING SYNTAX FILE | |
| 629 | |
| 630 We were assuming you were adding a completely new syntax file. When an existing | |
| 631 syntax file works, but is missing some items, you can add items in a separate | |
| 632 file. That avoids changing the distributed syntax file, which will be lost | |
| 633 when installing a new version of Vim. | |
| 634 Write syntax commands in your file, possibly using group names from the | |
| 635 existing syntax. For example, to add new variable types to the C syntax file: | |
| 636 > | |
| 637 :syntax keyword cType off_t uint | |
| 638 | |
| 639 Write the file with the same name as the original syntax file. In this case | |
| 640 "c.vim". Place it in a directory near the end of 'runtimepath'. This makes | |
| 641 it loaded after the original syntax file. For Unix this would be: | |
| 642 | |
| 643 ~/.vim/after/syntax/c.vim ~ | |
| 644 | |
| 645 ============================================================================== | |
| 646 *44.12* Portable syntax file layout | |
| 647 | |
| 648 Wouldn't it be nice if all Vim users exchange syntax files? To make this | |
| 649 possible, the syntax file must follow a few guidelines. | |
| 650 | |
| 651 Start with a header that explains what the syntax file is for, who maintains | |
| 652 it and when it was last updated. Don't include too much information about | |
| 653 changes history, not many people will read it. Example: > | |
| 654 | |
| 655 " Vim syntax file | |
| 656 " Language: C | |
| 657 " Maintainer: Bram Moolenaar <Bram@vim.org> | |
| 658 " Last Change: 2001 Jun 18 | |
| 659 " Remark: Included by the C++ syntax. | |
| 660 | |
| 661 Use the same layout as the other syntax files. Using an existing syntax file | |
| 662 as an example will save you a lot of time. | |
| 663 | |
| 664 Choose a good, descriptive name for your syntax file. Use lowercase letters | |
| 665 and digits. Don't make it too long, it is used in many places: The name of | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
666 the syntax file "name.vim", 'filetype', b:current_syntax and the start of each |
| 7 | 667 syntax group (nameType, nameStatement, nameString, etc). |
| 668 | |
| 669 Start with a check for "b:current_syntax". If it is defined, some other | |
| 836 | 670 syntax file, earlier in 'runtimepath' was already loaded: > |
| 671 | |
| 672 if exists("b:current_syntax") | |
| 673 finish | |
| 674 endif | |
| 675 | |
| 676 To be compatible with Vim 5.8 use: > | |
| 7 | 677 |
| 678 if version < 600 | |
| 679 syntax clear | |
| 680 elseif exists("b:current_syntax") | |
| 681 finish | |
| 682 endif | |
| 683 | |
| 684 Set "b:current_syntax" to the name of the syntax at the end. Don't forget | |
| 685 that included files do this too, you might have to reset "b:current_syntax" if | |
| 686 you include two files. | |
| 687 | |
| 688 If you want your syntax file to work with Vim 5.x, add a check for v:version. | |
| 11442 | 689 Find an syntax file in the Vim 7.2 distribution for an example. |
| 7 | 690 |
| 691 Do not include anything that is a user preference. Don't set 'tabstop', | |
| 692 'expandtab', etc. These belong in a filetype plugin. | |
| 693 | |
| 694 Do not include mappings or abbreviations. Only include setting 'iskeyword' if | |
| 695 it is really necessary for recognizing keywords. | |
| 696 | |
| 811 | 697 To allow users select their own preferred colors, make a different group name |
| 698 for every kind of highlighted item. Then link each of them to one of the | |
| 699 standard highlight groups. That will make it work with every color scheme. | |
| 700 If you select specific colors it will look bad with some color schemes. And | |
| 701 don't forget that some people use a different background color, or have only | |
| 702 eight colors available. | |
| 7 | 703 |
| 811 | 704 For the linking use "hi def link", so that the user can select different |
| 705 highlighting before your syntax file is loaded. Example: > | |
| 7 | 706 |
| 811 | 707 hi def link nameString String |
| 708 hi def link nameNumber Number | |
| 709 hi def link nameCommand Statement | |
| 7 | 710 ... etc ... |
| 711 | |
| 712 Add the "display" argument to items that are not used when syncing, to speed | |
| 713 up scrolling backwards and CTRL-L. | |
| 714 | |
| 715 ============================================================================== | |
| 716 | |
| 717 Next chapter: |usr_45.txt| Select your language | |
| 718 | |
| 14519 | 719 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |