1*quickfix.txt* For Vim version 8.2. Last change: 2020 Jan 06 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7This subject is introduced in section |30.1| of the user manual. 8 91. Using QuickFix commands |quickfix| 102. The error window |quickfix-window| 113. Using more than one list of errors |quickfix-error-lists| 124. Using :make |:make_makeprg| 135. Using :grep |grep| 146. Selecting a compiler |compiler-select| 157. The error format |error-file-format| 168. The directory stack |quickfix-directory-stack| 179. Specific error file formats |errorformats| 18 19The quickfix commands are not available when the |+quickfix| feature was 20disabled at compile time. 21 22============================================================================= 231. Using QuickFix commands *quickfix* *Quickfix* *E42* 24 25Vim has a special mode to speedup the edit-compile-edit cycle. This is 26inspired by the quickfix option of the Manx's Aztec C compiler on the Amiga. 27The idea is to save the error messages from the compiler in a file and use Vim 28to jump to the errors one by one. You can examine each problem and fix it, 29without having to remember all the error messages. 30 31In Vim the quickfix commands are used more generally to find a list of 32positions in files. For example, |:vimgrep| finds pattern matches. You can 33use the positions in a script with the |getqflist()| function. Thus you can 34do a lot more than the edit/compile/fix cycle! 35 36If you have the error messages in a file you can start Vim with: > 37 vim -q filename 38 39From inside Vim an easy way to run a command and handle the output is with the 40|:make| command (see below). 41 42The 'errorformat' option should be set to match the error messages from your 43compiler (see |errorformat| below). 44 45 *quickfix-ID* 46Each quickfix list has a unique identifier called the quickfix ID and this 47number will not change within a Vim session. The |getqflist()| function can be 48used to get the identifier assigned to a list. There is also a quickfix list 49number which may change whenever more than ten lists are added to a quickfix 50stack. 51 52 *location-list* *E776* 53A location list is a window-local quickfix list. You get one after commands 54like `:lvimgrep`, `:lgrep`, `:lhelpgrep`, `:lmake`, etc., which create a 55location list instead of a quickfix list as the corresponding `:vimgrep`, 56`:grep`, `:helpgrep`, `:make` do. 57 *location-list-file-window* 58A location list is associated with a window and each window can have a 59separate location list. A location list can be associated with only one 60window. The location list is independent of the quickfix list. 61 62When a window with a location list is split, the new window gets a copy of the 63location list. When there are no longer any references to a location list, 64the location list is destroyed. 65 66 *quickfix-changedtick* 67Every quickfix and location list has a read-only changedtick variable that 68tracks the total number of changes made to the list. Every time the quickfix 69list is modified, this count is incremented. This can be used to perform an 70action only when the list has changed. The |getqflist()| and |getloclist()| 71functions can be used to query the current value of changedtick. You cannot 72change the changedtick variable. 73 74The following quickfix commands can be used. The location list commands are 75similar to the quickfix commands, replacing the 'c' prefix in the quickfix 76command with 'l'. 77 78 *E924* 79If the current window was closed by an |autocommand| while processing a 80location list command, it will be aborted. 81 82 *E925* *E926* 83If the current quickfix or location list was changed by an |autocommand| while 84processing a quickfix or location list command, it will be aborted. 85 86 *:cc* 87:cc[!] [nr] Display error [nr]. If [nr] is omitted, the same 88:[nr]cc[!] error is displayed again. Without [!] this doesn't 89 work when jumping to another buffer, the current buffer 90 has been changed, there is the only window for the 91 buffer and both 'hidden' and 'autowrite' are off. 92 When jumping to another buffer with [!] any changes to 93 the current buffer are lost, unless 'hidden' is set or 94 there is another window for this buffer. 95 The 'switchbuf' settings are respected when jumping 96 to a buffer. 97 When used in the quickfix window the line number can 98 be used, including "." for the current line and "$" 99 for the last line. 100 101 *:ll* 102:ll[!] [nr] Same as ":cc", except the location list for the 103:[nr]ll[!] current window is used instead of the quickfix list. 104 105 *:cn* *:cne* *:cnext* *E553* 106:[count]cn[ext][!] Display the [count] next error in the list that 107 includes a file name. If there are no file names at 108 all, go to the [count] next error. See |:cc| for 109 [!] and 'switchbuf'. 110 111 *:lne* *:lnext* 112:[count]lne[xt][!] Same as ":cnext", except the location list for the 113 current window is used instead of the quickfix list. 114 115:[count]cN[ext][!] *:cp* *:cprevious* *:cprev* *:cN* *:cNext* 116:[count]cp[revious][!] Display the [count] previous error in the list that 117 includes a file name. If there are no file names at 118 all, go to the [count] previous error. See |:cc| for 119 [!] and 'switchbuf'. 120 121 122:[count]lN[ext][!] *:lp* *:lprevious* *:lprev* *:lN* *:lNext* 123:[count]lp[revious][!] Same as ":cNext" and ":cprevious", except the location 124 list for the current window is used instead of the 125 quickfix list. 126 127 *:cabo* *:cabove* 128:[count]cabo[ve] Go to the [count] error above the current line in the 129 current buffer. If [count] is omitted, then 1 is 130 used. If there are no errors, then an error message 131 is displayed. Assumes that the entries in a quickfix 132 list are sorted by their buffer number and line 133 number. If there are multiple errors on the same line, 134 then only the first entry is used. If [count] exceeds 135 the number of entries above the current line, then the 136 first error in the file is selected. 137 138 *:lab* *:labove* 139:[count]lab[ove] Same as ":cabove", except the location list for the 140 current window is used instead of the quickfix list. 141 142 *:cbel* *:cbelow* 143:[count]cbel[ow] Go to the [count] error below the current line in the 144 current buffer. If [count] is omitted, then 1 is 145 used. If there are no errors, then an error message 146 is displayed. Assumes that the entries in a quickfix 147 list are sorted by their buffer number and line 148 number. If there are multiple errors on the same 149 line, then only the first entry is used. If [count] 150 exceeds the number of entries below the current line, 151 then the last error in the file is selected. 152 153 *:lbel* *:lbelow* 154:[count]lbel[ow] Same as ":cbelow", except the location list for the 155 current window is used instead of the quickfix list. 156 157 *:cbe* *:cbefore* 158:[count]cbe[fore] Go to the [count] error before the current cursor 159 position in the current buffer. If [count] is 160 omitted, then 1 is used. If there are no errors, then 161 an error message is displayed. Assumes that the 162 entries in a quickfix list are sorted by their buffer, 163 line and column numbers. If [count] exceeds the 164 number of entries before the current position, then 165 the first error in the file is selected. 166 167 *:lbe* *:lbefore* 168:[count]lbe[fore] Same as ":cbefore", except the location list for the 169 current window is used instead of the quickfix list. 170 171 *:caf* *:cafter* 172:[count]caf[ter] Go to the [count] error after the current cursor 173 position in the current buffer. If [count] is 174 omitted, then 1 is used. If there are no errors, then 175 an error message is displayed. Assumes that the 176 entries in a quickfix list are sorted by their buffer, 177 line and column numbers. If [count] exceeds the 178 number of entries after the current position, then 179 the last error in the file is selected. 180 181 *:laf* *:lafter* 182:[count]laf[ter] Same as ":cafter", except the location list for the 183 current window is used instead of the quickfix list. 184 185 *:cnf* *:cnfile* 186:[count]cnf[ile][!] Display the first error in the [count] next file in 187 the list that includes a file name. If there are no 188 file names at all or if there is no next file, go to 189 the [count] next error. See |:cc| for [!] and 190 'switchbuf'. 191 192 *:lnf* *:lnfile* 193:[count]lnf[ile][!] Same as ":cnfile", except the location list for the 194 current window is used instead of the quickfix list. 195 196:[count]cNf[ile][!] *:cpf* *:cpfile* *:cNf* *:cNfile* 197:[count]cpf[ile][!] Display the last error in the [count] previous file in 198 the list that includes a file name. If there are no 199 file names at all or if there is no next file, go to 200 the [count] previous error. See |:cc| for [!] and 201 'switchbuf'. 202 203 204:[count]lNf[ile][!] *:lpf* *:lpfile* *:lNf* *:lNfile* 205:[count]lpf[ile][!] Same as ":cNfile" and ":cpfile", except the location 206 list for the current window is used instead of the 207 quickfix list. 208 209 *:crewind* *:cr* 210:cr[ewind][!] [nr] Display error [nr]. If [nr] is omitted, the FIRST 211 error is displayed. See |:cc|. 212 213 *:lrewind* *:lr* 214:lr[ewind][!] [nr] Same as ":crewind", except the location list for the 215 current window is used instead of the quickfix list. 216 217 *:cfirst* *:cfir* 218:cfir[st][!] [nr] Same as ":crewind". 219 220 *:lfirst* *:lfir* 221:lfir[st][!] [nr] Same as ":lrewind". 222 223 *:clast* *:cla* 224:cla[st][!] [nr] Display error [nr]. If [nr] is omitted, the LAST 225 error is displayed. See |:cc|. 226 227 *:llast* *:lla* 228:lla[st][!] [nr] Same as ":clast", except the location list for the 229 current window is used instead of the quickfix list. 230 231 *:cq* *:cquit* 232:cq[uit][!] 233:{N}cq[uit][!] 234:cq[uit][!] {N} Quit Vim with error code {N}. {N} defaults to one. 235 Useful when Vim is called from another program: 236 e.g., a compiler will not compile the same file again, 237 `git commit` will abort the committing process, `fc` 238 (built-in for shells like bash and zsh) will not 239 execute the command, etc. 240 {N} can also be zero, in which case Vim exits 241 normally. 242 WARNING: All changes in files are lost! Also when the 243 [!] is not used. It works like ":qall!" |:qall|, 244 except that Vim returns a non-zero exit code. 245 246 *:cf* *:cfile* 247:cf[ile][!] [errorfile] Read the error file and jump to the first error. 248 This is done automatically when Vim is started with 249 the -q option. You can use this command when you 250 keep Vim running while compiling. If you give the 251 name of the errorfile, the 'errorfile' option will 252 be set to [errorfile]. See |:cc| for [!]. 253 If the encoding of the error file differs from the 254 'encoding' option, you can use the 'makeencoding' 255 option to specify the encoding. 256 257 *:lf* *:lfi* *:lfile* 258:lf[ile][!] [errorfile] Same as ":cfile", except the location list for the 259 current window is used instead of the quickfix list. 260 You can not use the -q command-line option to set 261 the location list. 262 263 264:cg[etfile] [errorfile] *:cg* *:cgetfile* 265 Read the error file. Just like ":cfile" but don't 266 jump to the first error. 267 If the encoding of the error file differs from the 268 'encoding' option, you can use the 'makeencoding' 269 option to specify the encoding. 270 271 272:lg[etfile] [errorfile] *:lg* *:lge* *:lgetfile* 273 Same as ":cgetfile", except the location list for the 274 current window is used instead of the quickfix list. 275 276 *:caddf* *:caddfile* 277:caddf[ile] [errorfile] Read the error file and add the errors from the 278 errorfile to the current quickfix list. If a quickfix 279 list is not present, then a new list is created. 280 If the encoding of the error file differs from the 281 'encoding' option, you can use the 'makeencoding' 282 option to specify the encoding. 283 284 *:laddf* *:laddfile* 285:laddf[ile] [errorfile] Same as ":caddfile", except the location list for the 286 current window is used instead of the quickfix list. 287 288 *:cb* *:cbuffer* *E681* 289:cb[uffer][!] [bufnr] Read the error list from the current buffer. 290 When [bufnr] is given it must be the number of a 291 loaded buffer. That buffer will then be used instead 292 of the current buffer. 293 A range can be specified for the lines to be used. 294 Otherwise all lines in the buffer are used. 295 See |:cc| for [!]. 296 297 *:lb* *:lbuffer* 298:lb[uffer][!] [bufnr] Same as ":cbuffer", except the location list for the 299 current window is used instead of the quickfix list. 300 301 *:cgetb* *:cgetbuffer* 302:cgetb[uffer] [bufnr] Read the error list from the current buffer. Just 303 like ":cbuffer" but don't jump to the first error. 304 305 *:lgetb* *:lgetbuffer* 306:lgetb[uffer] [bufnr] Same as ":cgetbuffer", except the location list for 307 the current window is used instead of the quickfix 308 list. 309 310 *:cad* *:cadd* *:caddbuffer* 311:cad[dbuffer] [bufnr] Read the error list from the current buffer and add 312 the errors to the current quickfix list. If a 313 quickfix list is not present, then a new list is 314 created. Otherwise, same as ":cbuffer". 315 316 *:laddb* *:laddbuffer* 317:laddb[uffer] [bufnr] Same as ":caddbuffer", except the location list for 318 the current window is used instead of the quickfix 319 list. 320 321 *:cex* *:cexpr* *E777* 322:cex[pr][!] {expr} Create a quickfix list using the result of {expr} and 323 jump to the first error. 324 If {expr} is a String, then each newline terminated 325 line in the String is processed using the global value 326 of 'errorformat' and the result is added to the 327 quickfix list. 328 If {expr} is a List, then each String item in the list 329 is processed and added to the quickfix list. Non 330 String items in the List are ignored. 331 See |:cc| for [!]. 332 Examples: > 333 :cexpr system('grep -n xyz *') 334 :cexpr getline(1, '$') 335< 336 *:lex* *:lexpr* 337:lex[pr][!] {expr} Same as |:cexpr|, except the location list for the 338 current window is used instead of the quickfix list. 339 340 *:cgete* *:cgetexpr* 341:cgete[xpr] {expr} Create a quickfix list using the result of {expr}. 342 Just like |:cexpr|, but don't jump to the first error. 343 344 *:lgete* *:lgetexpr* 345:lgete[xpr] {expr} Same as |:cgetexpr|, except the location list for the 346 current window is used instead of the quickfix list. 347 348 *:cadde* *:caddexpr* 349:cadde[xpr] {expr} Evaluate {expr} and add the resulting lines to the 350 current quickfix list. If a quickfix list is not 351 present, then a new list is created. The current 352 cursor position will not be changed. See |:cexpr| for 353 more information. 354 Example: > 355 :g/mypattern/caddexpr expand("%") . ":" . line(".") . ":" . getline(".") 356< 357 *:lad* *:addd* *:laddexpr* 358:lad[dexpr] {expr} Same as ":caddexpr", except the location list for the 359 current window is used instead of the quickfix list. 360 361 *:cl* *:clist* 362:cl[ist] [from] [, [to]] 363 List all errors that are valid |quickfix-valid|. 364 If numbers [from] and/or [to] are given, the respective 365 range of errors is listed. A negative number counts 366 from the last error backwards, -1 being the last error. 367 The 'switchbuf' settings are respected when jumping 368 to a buffer. 369 The |:filter| command can be used to display only the 370 quickfix entries matching a supplied pattern. The 371 pattern is matched against the filename, module name, 372 pattern and text of the entry. 373 374:cl[ist] +{count} List the current and next {count} valid errors. This 375 is similar to ":clist from from+count", where "from" 376 is the current error position. 377 378:cl[ist]! [from] [, [to]] 379 List all errors. 380 381:cl[ist]! +{count} List the current and next {count} error lines. This 382 is useful to see unrecognized lines after the current 383 one. For example, if ":clist" shows: 384 8384 testje.java:252: error: cannot find symbol ~ 385 Then using ":cl! +3" shows the reason: 386 8384 testje.java:252: error: cannot find symbol ~ 387 8385: ZexitCode = Fmainx(); ~ 388 8386: ^ ~ 389 8387: symbol: method Fmainx() ~ 390 391:lli[st] [from] [, [to]] *:lli* *:llist* 392 Same as ":clist", except the location list for the 393 current window is used instead of the quickfix list. 394 395:lli[st]! [from] [, [to]] 396 List all the entries in the location list for the 397 current window. 398 399If you insert or delete lines, mostly the correct error location is still 400found because hidden marks are used. Sometimes, when the mark has been 401deleted for some reason, the message "line changed" is shown to warn you that 402the error location may not be correct. If you quit Vim and start again the 403marks are lost and the error locations may not be correct anymore. 404 405Two autocommands are available for running commands before and after a 406quickfix command (':make', ':grep' and so on) is executed. See 407|QuickFixCmdPre| and |QuickFixCmdPost| for details. 408 409 *QuickFixCmdPost-example* 410When 'encoding' differs from the locale, the error messages may have a 411different encoding from what Vim is using. To convert the messages you can 412use this code: > 413 function QfMakeConv() 414 let qflist = getqflist() 415 for i in qflist 416 let i.text = iconv(i.text, "cp936", "utf-8") 417 endfor 418 call setqflist(qflist) 419 endfunction 420 421 au QuickfixCmdPost make call QfMakeConv() 422Another option is using 'makeencoding'. 423 424 *quickfix-title* 425Every quickfix and location list has a title. By default the title is set to 426the command that created the list. The |getqflist()| and |getloclist()| 427functions can be used to get the title of a quickfix and a location list 428respectively. The |setqflist()| and |setloclist()| functions can be used to 429modify the title of a quickfix and location list respectively. Examples: > 430 call setqflist([], 'a', {'title' : 'Cmd output'}) 431 echo getqflist({'title' : 1}) 432 call setloclist(3, [], 'a', {'title' : 'Cmd output'}) 433 echo getloclist(3, {'title' : 1}) 434< 435 *quickfix-index* 436When you jump to a quickfix/location list entry using any of the quickfix 437commands (e.g. |:cc|, |:cnext|, |:cprev|, etc.), that entry becomes the 438currently selected entry. The index of the currently selected entry in a 439quickfix/location list can be obtained using the getqflist()/getloclist() 440functions. Examples: > 441 echo getqflist({'idx' : 0}).idx 442 echo getqflist({'id' : qfid, 'idx' : 0}).idx 443 echo getloclist(2, {'idx' : 0}).idx 444< 445For a new quickfix list, the first entry is selected and the index is 1. Any 446entry in any quickfix/location list can be set as the currently selected entry 447using the setqflist() function. Examples: > 448 call setqflist([], 'a', {'idx' : 12}) 449 call setqflist([], 'a', {'id' : qfid, 'idx' : 7}) 450 call setloclist(1, [], 'a', {'idx' : 7}) 451< 452 *quickfix-size* 453You can get the number of entries (size) in a quickfix and a location list 454using the |getqflist()| and |getloclist()| functions respectively. Examples: > 455 echo getqflist({'size' : 1}) 456 echo getloclist(5, {'size' : 1}) 457< 458 *quickfix-context* 459Any Vim type can be associated as a context with a quickfix or location list. 460The |setqflist()| and the |setloclist()| functions can be used to associate a 461context with a quickfix and a location list respectively. The |getqflist()| 462and the |getloclist()| functions can be used to retrieve the context of a 463quickfix and a location list respectively. This is useful for a Vim plugin 464dealing with multiple quickfix/location lists. 465Examples: > 466 467 let somectx = {'name' : 'Vim', 'type' : 'Editor'} 468 call setqflist([], 'a', {'context' : somectx}) 469 echo getqflist({'context' : 1}) 470 471 let newctx = ['red', 'green', 'blue'] 472 call setloclist(2, [], 'a', {'id' : qfid, 'context' : newctx}) 473 echo getloclist(2, {'id' : qfid, 'context' : 1}) 474< 475 *quickfix-parse* 476You can parse a list of lines using 'errorformat' without creating or 477modifying a quickfix list using the |getqflist()| function. Examples: > 478 echo getqflist({'lines' : ["F1:10:Line10", "F2:20:Line20"]}) 479 echo getqflist({'lines' : systemlist('grep -Hn quickfix *')}) 480This returns a dictionary where the 'items' key contains the list of quickfix 481entries parsed from lines. The following shows how to use a custom 482'errorformat' to parse the lines without modifying the 'errorformat' option: > 483 echo getqflist({'efm' : '%f#%l#%m', 'lines' : ['F1#10#Line']}) 484< 485 486EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST: 487 *:cdo* 488:cdo[!] {cmd} Execute {cmd} in each valid entry in the quickfix list. 489 It works like doing this: > 490 :cfirst 491 :{cmd} 492 :cnext 493 :{cmd} 494 etc. 495< When the current file can't be |abandon|ed and the [!] 496 is not present, the command fails. 497 When going to the next entry fails execution stops. 498 The last buffer (or where an error occurred) becomes 499 the current buffer. 500 {cmd} can contain '|' to concatenate several commands. 501 502 Only valid entries in the quickfix list are used. 503 A range can be used to select entries, e.g.: > 504 :10,$cdo cmd 505< To skip entries 1 to 9. 506 507 Note: While this command is executing, the Syntax 508 autocommand event is disabled by adding it to 509 'eventignore'. This considerably speeds up editing 510 each buffer. 511 Also see |:bufdo|, |:tabdo|, |:argdo|, |:windo|, 512 |:ldo|, |:cfdo| and |:lfdo|. 513 514 *:cfdo* 515:cfdo[!] {cmd} Execute {cmd} in each file in the quickfix list. 516 It works like doing this: > 517 :cfirst 518 :{cmd} 519 :cnfile 520 :{cmd} 521 etc. 522< Otherwise it works the same as `:cdo`. 523 524 *:ldo* 525:ld[o][!] {cmd} Execute {cmd} in each valid entry in the location list 526 for the current window. 527 It works like doing this: > 528 :lfirst 529 :{cmd} 530 :lnext 531 :{cmd} 532 etc. 533< Only valid entries in the location list are used. 534 Otherwise it works the same as `:cdo`. 535 536 *:lfdo* 537:lfdo[!] {cmd} Execute {cmd} in each file in the location list for 538 the current window. 539 It works like doing this: > 540 :lfirst 541 :{cmd} 542 :lnfile 543 :{cmd} 544 etc. 545< Otherwise it works the same as `:ldo`. 546 547FILTERING A QUICKFIX OR LOCATION LIST: 548 *cfilter-plugin* *:Cfilter* *:Lfilter* 549If you have too many entries in a quickfix list, you can use the cfilter 550plugin to reduce the number of entries. Load the plugin with: > 551 552 packadd cfilter 553 554Then you can use the following commands to filter a quickfix/location list: > 555 556 :Cfilter[!] /{pat}/ 557 :Lfilter[!] /{pat}/ 558 559The |:Cfilter| command creates a new quickfix list from the entries matching 560{pat} in the current quickfix list. {pat} is a Vim |regular-expression| 561pattern. Both the file name and the text of the entries are matched against 562{pat}. If the optional ! is supplied, then the entries not matching {pat} are 563used. The pattern can be optionally enclosed using one of the following 564characters: ', ", /. If the pattern is empty, then the last used search 565pattern is used. 566 567The |:Lfilter| command does the same as |:Cfilter| but operates on the current 568location list. 569 570============================================================================= 5712. The error window *quickfix-window* 572 573 *:cope* *:copen* *w:quickfix_title* 574:cope[n] [height] Open a window to show the current list of errors. 575 576 When [height] is given, the window becomes that high 577 (if there is room). When [height] is omitted the 578 window is made ten lines high. 579 580 If there already is a quickfix window, it will be made 581 the current window. It is not possible to open a 582 second quickfix window. If [height] is given the 583 existing window will be resized to it. 584 585 *quickfix-buffer* 586 The window will contain a special buffer, with 587 'buftype' equal to "quickfix". Don't change this! 588 The window will have the w:quickfix_title variable set 589 which will indicate the command that produced the 590 quickfix list. This can be used to compose a custom 591 status line if the value of 'statusline' is adjusted 592 properly. Whenever this buffer is modified by a 593 quickfix command or function, the |b:changedtick| 594 variable is incremented. You can get the number of 595 this buffer using the getqflist() and getloclist() 596 functions by passing the 'qfbufnr' item. For a 597 location list, this buffer is wiped out when the 598 location list is removed. 599 600 *:lop* *:lopen* 601:lop[en] [height] Open a window to show the location list for the 602 current window. Works only when the location list for 603 the current window is present. You can have more than 604 one location window opened at a time. Otherwise, it 605 acts the same as ":copen". 606 607 *:ccl* *:cclose* 608:ccl[ose] Close the quickfix window. 609 610 *:lcl* *:lclose* 611:lcl[ose] Close the window showing the location list for the 612 current window. 613 614 *:cw* *:cwindow* 615:cw[indow] [height] Open the quickfix window when there are recognized 616 errors. If the window is already open and there are 617 no recognized errors, close the window. 618 619 *:lw* *:lwindow* 620:lw[indow] [height] Same as ":cwindow", except use the window showing the 621 location list for the current window. 622 623 *:cbo* *:cbottom* 624:cbo[ttom] Put the cursor in the last line of the quickfix window 625 and scroll to make it visible. This is useful for 626 when errors are added by an asynchronous callback. 627 Only call it once in a while if there are many 628 updates to avoid a lot of redrawing. 629 630 *:lbo* *:lbottom* 631:lbo[ttom] Same as ":cbottom", except use the window showing the 632 location list for the current window. 633 634Normally the quickfix window is at the bottom of the screen. If there are 635vertical splits, it's at the bottom of the rightmost column of windows. To 636make it always occupy the full width: > 637 :botright cwindow 638You can move the window around with |window-moving| commands. 639For example, to move it to the top: CTRL-W K 640The 'winfixheight' option will be set, which means that the window will mostly 641keep its height, ignoring 'winheight' and 'equalalways'. You can change the 642height manually (e.g., by dragging the status line above it with the mouse). 643 644In the quickfix window, each line is one error. The line number is equal to 645the error number. The current entry is highlighted with the QuickFixLine 646highlighting. You can change it to your liking, e.g.: > 647 :hi QuickFixLine ctermbg=Yellow guibg=Yellow 648 649You can use ":.cc" to jump to the error under the cursor. 650Hitting the <Enter> key or double-clicking the mouse on a line has the same 651effect. The file containing the error is opened in the window above the 652quickfix window. If there already is a window for that file, it is used 653instead. If the buffer in the used window has changed, and the error is in 654another file, jumping to the error will fail. You will first have to make 655sure the window contains a buffer which can be abandoned. 656 *CTRL-W_<Enter>* *CTRL-W_<CR>* 657You can use CTRL-W <Enter> to open a new window and jump to the error there. 658 659When the quickfix window has been filled, two autocommand events are 660triggered. First the 'filetype' option is set to "qf", which triggers the 661FileType event (also see |qf.vim|). Then the BufReadPost event is triggered, 662using "quickfix" for the buffer name. This can be used to perform some action 663on the listed errors. Example: > 664 au BufReadPost quickfix setlocal modifiable 665 \ | silent exe 'g/^/s//\=line(".")." "/' 666 \ | setlocal nomodifiable 667This prepends the line number to each line. Note the use of "\=" in the 668substitute string of the ":s" command, which is used to evaluate an 669expression. 670The BufWinEnter event is also triggered, again using "quickfix" for the buffer 671name. 672 673Note: When adding to an existing quickfix list the autocommand are not 674triggered. 675 676Note: Making changes in the quickfix window has no effect on the list of 677errors. 'modifiable' is off to avoid making changes. If you delete or insert 678lines anyway, the relation between the text and the error number is messed up. 679If you really want to do this, you could write the contents of the quickfix 680window to a file and use ":cfile" to have it parsed and used as the new error 681list. 682 683 *location-list-window* 684The location list window displays the entries in a location list. When you 685open a location list window, it is created below the current window and 686displays the location list for the current window. The location list window 687is similar to the quickfix window, except that you can have more than one 688location list window open at a time. When you use a location list command in 689this window, the displayed location list is used. 690 691When you select a file from the location list window, the following steps are 692used to find a window to edit the file: 693 6941. If a window with the location list displayed in the location list window is 695 present, then the file is opened in that window. 6962. If the above step fails and if the file is already opened in another 697 window, then that window is used. 6983. If the above step fails then an existing window showing a buffer with 699 'buftype' not set is used. 7004. If the above step fails, then the file is edited in a new window. 701 702In all of the above cases, if the location list for the selected window is not 703yet set, then it is set to the location list displayed in the location list 704window. 705 706 *quickfix-window-ID* 707You can use the |getqflist()| and |getloclist()| functions to obtain the 708window ID of the quickfix window and location list window respectively (if 709present). Examples: > 710 echo getqflist({'winid' : 1}).winid 711 echo getloclist(2, {'winid' : 1}).winid 712< 713 *getqflist-examples* 714The |getqflist()| and |getloclist()| functions can be used to get the various 715attributes of a quickfix and location list respectively. Some examples for 716using these functions are below: 717> 718 " get the title of the current quickfix list 719 :echo getqflist({'title' : 0}).title 720 721 " get the identifier of the current quickfix list 722 :let qfid = getqflist({'id' : 0}).id 723 724 " get the identifier of the fourth quickfix list in the stack 725 :let qfid = getqflist({'nr' : 4, 'id' : 0}).id 726 727 " check whether a quickfix list with a specific identifier exists 728 :if getqflist({'id' : qfid}).id == qfid 729 730 " get the index of the current quickfix list in the stack 731 :let qfnum = getqflist({'nr' : 0}).nr 732 733 " get the items of a quickfix list specified by an identifier 734 :echo getqflist({'id' : qfid, 'items' : 0}).items 735 736 " get the number of entries in a quickfix list specified by an id 737 :echo getqflist({'id' : qfid, 'size' : 0}).size 738 739 " get the context of the third quickfix list in the stack 740 :echo getqflist({'nr' : 3, 'context' : 0}).context 741 742 " get the number of quickfix lists in the stack 743 :echo getqflist({'nr' : '$'}).nr 744 745 " get the number of times the current quickfix list is changed 746 :echo getqflist({'changedtick' : 0}).changedtick 747 748 " get the current entry in a quickfix list specified by an identifier 749 :echo getqflist({'id' : qfid, 'idx' : 0}).idx 750 751 " get all the quickfix list attributes using an identifier 752 :echo getqflist({'id' : qfid, 'all' : 0}) 753 754 " parse text from a List of lines and return a quickfix list 755 :let myList = ["a.java:10:L10", "b.java:20:L20"] 756 :echo getqflist({'lines' : myList}).items 757 758 " parse text using a custom 'efm' and return a quickfix list 759 :echo getqflist({'lines' : ['a.c#10#Line 10'], 'efm':'%f#%l#%m'}).items 760 761 " get the quickfix list window id 762 :echo getqflist({'winid' : 0}).winid 763 764 " get the quickfix list window buffer number 765 :echo getqflist({'qfbufnr' : 0}).qfbufnr 766 767 " get the context of the current location list 768 :echo getloclist(0, {'context' : 0}).context 769 770 " get the location list window id of the third window 771 :echo getloclist(3, {'winid' : 0}).winid 772 773 " get the location list window buffer number of the third window 774 :echo getloclist(3, {'qfbufnr' : 0}).qfbufnr 775 776 " get the file window id of a location list window (winnr: 4) 777 :echo getloclist(4, {'filewinid' : 0}).filewinid 778< 779 *setqflist-examples* 780The |setqflist()| and |setloclist()| functions can be used to set the various 781attributes of a quickfix and location list respectively. Some examples for 782using these functions are below: 783> 784 " create an empty quickfix list with a title and a context 785 :let t = 'Search results' 786 :let c = {'cmd' : 'grep'} 787 :call setqflist([], ' ', {'title' : t, 'context' : c}) 788 789 " set the title of the current quickfix list 790 :call setqflist([], 'a', {'title' : 'Mytitle'}) 791 792 " change the current entry in the list specified by an identifier 793 :call setqflist([], 'a', {'id' : qfid, 'idx' : 10}) 794 795 " set the context of a quickfix list specified by an identifier 796 :call setqflist([], 'a', {'id' : qfid, 'context' : {'val' : 100}}) 797 798 " create a new quickfix list from a command output 799 :call setqflist([], ' ', {'lines' : systemlist('grep -Hn main *.c')}) 800 801 " parse text using a custom efm and add to a particular quickfix list 802 :call setqflist([], 'a', {'id' : qfid, 803 \ 'lines' : ["a.c#10#L10", "b.c#20#L20"], 'efm':'%f#%l#%m'}) 804 805 " add items to the quickfix list specified by an identifier 806 :let newItems = [{'filename' : 'a.txt', 'lnum' : 10, 'text' : "Apple"}, 807 \ {'filename' : 'b.txt', 'lnum' : 20, 'text' : "Orange"}] 808 :call setqflist([], 'a', {'id' : qfid, 'items' : newItems}) 809 810 " empty a quickfix list specified by an identifier 811 :call setqflist([], 'r', {'id' : qfid, 'items' : []}) 812 813 " free all the quickfix lists in the stack 814 :call setqflist([], 'f') 815 816 " set the title of the fourth quickfix list 817 :call setqflist([], 'a', {'nr' : 4, 'title' : 'SomeTitle'}) 818 819 " create a new quickfix list at the end of the stack 820 :call setqflist([], ' ', {'nr' : '$', 821 \ 'lines' : systemlist('grep -Hn class *.java')}) 822 823 " create a new location list from a command output 824 :call setloclist(0, [], ' ', {'lines' : systemlist('grep -Hn main *.c')}) 825 826 " replace the location list entries for the third window 827 :call setloclist(3, [], 'r', {'items' : newItems}) 828< 829============================================================================= 8303. Using more than one list of errors *quickfix-error-lists* 831 832So far has been assumed that there is only one list of errors. Actually the 833ten last used lists are remembered. When starting a new list, the previous 834ones are automatically kept. Two commands can be used to access older error 835lists. They set one of the existing error lists as the current one. 836 837 *:colder* *:col* *E380* 838:col[der] [count] Go to older error list. When [count] is given, do 839 this [count] times. When already at the oldest error 840 list, an error message is given. 841 842 *:lolder* *:lol* 843:lol[der] [count] Same as `:colder`, except use the location list for 844 the current window instead of the quickfix list. 845 846 *:cnewer* *:cnew* *E381* 847:cnew[er] [count] Go to newer error list. When [count] is given, do 848 this [count] times. When already at the newest error 849 list, an error message is given. 850 851 *:lnewer* *:lnew* 852:lnew[er] [count] Same as `:cnewer`, except use the location list for 853 the current window instead of the quickfix list. 854 855 *:chistory* *:chi* 856:[count]chi[story] Show the list of error lists. The current list is 857 marked with ">". The output looks like: 858 error list 1 of 3; 43 errors ~ 859 > error list 2 of 3; 0 errors ~ 860 error list 3 of 3; 15 errors ~ 861 862 When [count] is given, then the count'th quickfix 863 list is made the current list. Example: > 864 " Make the 4th quickfix list current 865 :4chistory 866< 867 *:lhistory* *:lhi* 868:[count]lhi[story] Show the list of location lists, otherwise like 869 `:chistory`. 870 871When adding a new error list, it becomes the current list. 872 873When ":colder" has been used and ":make" or ":grep" is used to add a new error 874list, one newer list is overwritten. This is especially useful if you are 875browsing with ":grep" |grep|. If you want to keep the more recent error 876lists, use ":cnewer 99" first. 877 878To get the number of lists in the quickfix and location list stack, you can 879use the |getqflist()| and |getloclist()| functions respectively with the list 880number set to the special value '$'. Examples: > 881 echo getqflist({'nr' : '$'}).nr 882 echo getloclist(3, {'nr' : '$'}).nr 883To get the number of the current list in the stack: > 884 echo getqflist({'nr' : 0}).nr 885< 886============================================================================= 8874. Using :make *:make_makeprg* 888 889 *:mak* *:make* 890:mak[e][!] [arguments] 1. All relevant |QuickFixCmdPre| autocommands are 891 executed. 892 2. If the 'autowrite' option is on, write any changed 893 buffers 894 3. An errorfile name is made from 'makeef'. If 895 'makeef' doesn't contain "##", and a file with this 896 name already exists, it is deleted. 897 4. The program given with the 'makeprg' option is 898 started (default "make") with the optional 899 [arguments] and the output is saved in the 900 errorfile (for Unix it is also echoed on the 901 screen). 902 5. The errorfile is read using 'errorformat'. 903 6. All relevant |QuickFixCmdPost| autocommands are 904 executed. See example below. 905 7. If [!] is not given the first error is jumped to. 906 8. The errorfile is deleted. 907 9. You can now move through the errors with commands 908 like |:cnext| and |:cprevious|, see above. 909 This command does not accept a comment, any " 910 characters are considered part of the arguments. 911 If the encoding of the program output differs from the 912 'encoding' option, you can use the 'makeencoding' 913 option to specify the encoding. 914 915 *:lmak* *:lmake* 916:lmak[e][!] [arguments] 917 Same as ":make", except the location list for the 918 current window is used instead of the quickfix list. 919 920The ":make" command executes the command given with the 'makeprg' option. 921This is done by passing the command to the shell given with the 'shell' 922option. This works almost like typing 923 924 ":!{makeprg} [arguments] {shellpipe} {errorfile}". 925 926{makeprg} is the string given with the 'makeprg' option. Any command can be 927used, not just "make". Characters '%' and '#' are expanded as usual on a 928command-line. You can use "%<" to insert the current file name without 929extension, or "#<" to insert the alternate file name without extension, for 930example: > 931 :set makeprg=make\ #<.o 932 933[arguments] is anything that is typed after ":make". 934{shellpipe} is the 'shellpipe' option. 935{errorfile} is the 'makeef' option, with ## replaced to make it unique. 936 937The placeholder "$*" can be used for the argument list in {makeprg} if the 938command needs some additional characters after its arguments. The $* is 939replaced then by all arguments. Example: > 940 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*} 941or simpler > 942 :let &mp = 'latex \\nonstopmode \\input\{$*}' 943"$*" can be given multiple times, for example: > 944 :set makeprg=gcc\ -o\ $*\ $* 945 946The 'shellpipe' option defaults to ">" for the Amiga and ">%s 2>&1" for Win32. 947This means that the output of the compiler is saved in a file and not shown on 948the screen directly. For Unix "| tee" is used. The compiler output is shown 949on the screen and saved in a file the same time. Depending on the shell used 950"|& tee" or "2>&1| tee" is the default, so stderr output will be included. 951 952If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful 953for compilers that write to an errorfile themselves (e.g., Manx's Amiga C). 954 955 956Using QuickFixCmdPost to fix the encoding ~ 957 958It may be that 'encoding' is set to an encoding that differs from the messages 959your build program produces. This example shows how to fix this after Vim has 960read the error messages: > 961 962 function QfMakeConv() 963 let qflist = getqflist() 964 for i in qflist 965 let i.text = iconv(i.text, "cp936", "utf-8") 966 endfor 967 call setqflist(qflist) 968 endfunction 969 970 au QuickfixCmdPost make call QfMakeConv() 971 972(Example by Faque Cheng) 973Another option is using 'makeencoding'. 974 975============================================================================== 9765. Using :vimgrep and :grep *grep* *lid* 977 978Vim has two ways to find matches for a pattern: Internal and external. The 979advantage of the internal grep is that it works on all systems and uses the 980powerful Vim search patterns. An external grep program can be used when the 981Vim grep does not do what you want. 982 983The internal method will be slower, because files are read into memory. The 984advantages are: 985- Line separators and encoding are automatically recognized, as if a file is 986 being edited. 987- Uses Vim search patterns. Multi-line patterns can be used. 988- When plugins are enabled: compressed and remote files can be searched. 989 |gzip| |netrw| 990 991To be able to do this Vim loads each file as if it is being edited. When 992there is no match in the file the associated buffer is wiped out again. The 993'hidden' option is ignored here to avoid running out of memory or file 994descriptors when searching many files. However, when the |:hide| command 995modifier is used the buffers are kept loaded. This makes following searches 996in the same files a lot faster. 997 998Note that |:copen| (or |:lopen| for |:lgrep|) may be used to open a buffer 999containing the search results in linked form. The |:silent| command may be 1000used to suppress the default full screen grep output. The ":grep!" form of 1001the |:grep| command doesn't jump to the first match automatically. These 1002commands can be combined to create a NewGrep command: > 1003 1004 command! -nargs=+ NewGrep execute 'silent grep! <args>' | copen 42 1005 1006 10075.1 using Vim's internal grep 1008 1009 *:vim* *:vimgrep* *E682* *E683* 1010:vim[grep][!] /{pattern}/[g][j] {file} ... 1011 Search for {pattern} in the files {file} ... and set 1012 the error list to the matches. Files matching 1013 'wildignore' are ignored; files in 'suffixes' are 1014 searched last. 1015 Without the 'g' flag each line is added only once. 1016 With 'g' every match is added. 1017 1018 {pattern} is a Vim search pattern. Instead of 1019 enclosing it in / any non-ID character (see 1020 |'isident'|) can be used, so long as it does not 1021 appear in {pattern}. 1022 'ignorecase' applies. To overrule it put |/\c| in the 1023 pattern to ignore case or |/\C| to match case. 1024 'smartcase' is not used. 1025 If {pattern} is empty (e.g. // is specified), the last 1026 used search pattern is used. |last-pattern| 1027:{count}vim[grep] ... 1028 When a number is put before the command this is used 1029 as the maximum number of matches to find. Use 1030 ":1vimgrep pattern file" to find only the first. 1031 Useful if you only want to check if there is a match 1032 and quit quickly when it's found. 1033 1034 Without the 'j' flag Vim jumps to the first match. 1035 With 'j' only the quickfix list is updated. 1036 With the [!] any changes in the current buffer are 1037 abandoned. 1038 1039 Every second or so the searched file name is displayed 1040 to give you an idea of the progress made. 1041 Examples: > 1042 :vimgrep /an error/ *.c 1043 :vimgrep /\<FileName\>/ *.h include/* 1044 :vimgrep /myfunc/ **/*.c 1045< For the use of "**" see |starstar-wildcard|. 1046 1047:vim[grep][!] {pattern} {file} ... 1048 Like above, but instead of enclosing the pattern in a 1049 non-ID character use a white-separated pattern. The 1050 pattern must start with an ID character. 1051 Example: > 1052 :vimgrep Error *.c 1053< 1054 *:lv* *:lvimgrep* 1055:lv[imgrep][!] /{pattern}/[g][j] {file} ... 1056:lv[imgrep][!] {pattern} {file} ... 1057 Same as ":vimgrep", except the location list for the 1058 current window is used instead of the quickfix list. 1059 1060 *:vimgrepa* *:vimgrepadd* 1061:vimgrepa[dd][!] /{pattern}/[g][j] {file} ... 1062:vimgrepa[dd][!] {pattern} {file} ... 1063 Just like ":vimgrep", but instead of making a new list 1064 of errors the matches are appended to the current 1065 list. 1066 1067 *:lvimgrepa* *:lvimgrepadd* 1068:lvimgrepa[dd][!] /{pattern}/[g][j] {file} ... 1069:lvimgrepa[dd][!] {pattern} {file} ... 1070 Same as ":vimgrepadd", except the location list for 1071 the current window is used instead of the quickfix 1072 list. 1073 10745.2 External grep 1075 1076Vim can interface with "grep" and grep-like programs (such as the GNU 1077id-utils) in a similar way to its compiler integration (see |:make| above). 1078 1079[Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where 1080"re" stands for Regular Expression.] 1081 1082 *:gr* *:grep* 1083:gr[ep][!] [arguments] Just like ":make", but use 'grepprg' instead of 1084 'makeprg' and 'grepformat' instead of 'errorformat'. 1085 When 'grepprg' is "internal" this works like 1086 |:vimgrep|. Note that the pattern needs to be 1087 enclosed in separator characters then. 1088 If the encoding of the program output differs from the 1089 'encoding' option, you can use the 'makeencoding' 1090 option to specify the encoding. 1091 1092 *:lgr* *:lgrep* 1093:lgr[ep][!] [arguments] Same as ":grep", except the location list for the 1094 current window is used instead of the quickfix list. 1095 1096 *:grepa* *:grepadd* 1097:grepa[dd][!] [arguments] 1098 Just like ":grep", but instead of making a new list of 1099 errors the matches are appended to the current list. 1100 Example: > 1101 :call setqflist([]) 1102 :bufdo grepadd! something % 1103< The first command makes a new error list which is 1104 empty. The second command executes "grepadd" for each 1105 listed buffer. Note the use of ! to avoid that 1106 ":grepadd" jumps to the first error, which is not 1107 allowed with |:bufdo|. 1108 An example that uses the argument list and avoids 1109 errors for files without matches: > 1110 :silent argdo try 1111 \ | grepadd! something % 1112 \ | catch /E480:/ 1113 \ | endtry" 1114< 1115 If the encoding of the program output differs from the 1116 'encoding' option, you can use the 'makeencoding' 1117 option to specify the encoding. 1118 1119 *:lgrepa* *:lgrepadd* 1120:lgrepa[dd][!] [arguments] 1121 Same as ":grepadd", except the location list for the 1122 current window is used instead of the quickfix list. 1123 11245.3 Setting up external grep 1125 1126If you have a standard "grep" program installed, the :grep command may work 1127well with the defaults. The syntax is very similar to the standard command: > 1128 1129 :grep foo *.c 1130 1131Will search all files with the .c extension for the substring "foo". The 1132arguments to :grep are passed straight to the "grep" program, so you can use 1133whatever options your "grep" supports. 1134 1135By default, :grep invokes grep with the -n option (show file and line 1136numbers). You can change this with the 'grepprg' option. You will need to set 1137'grepprg' if: 1138 1139a) You are using a program that isn't called "grep" 1140b) You have to call grep with a full path 1141c) You want to pass other options automatically (e.g. case insensitive 1142 search.) 1143 1144Once "grep" has executed, Vim parses the results using the 'grepformat' 1145option. This option works in the same way as the 'errorformat' option - see 1146that for details. You may need to change 'grepformat' from the default if 1147your grep outputs in a non-standard format, or you are using some other 1148program with a special format. 1149 1150Once the results are parsed, Vim loads the first file containing a match and 1151jumps to the appropriate line, in the same way that it jumps to a compiler 1152error in |quickfix| mode. You can then use the |:cnext|, |:clist|, etc. 1153commands to see the other matches. 1154 1155 11565.4 Using :grep with id-utils 1157 1158You can set up :grep to work with the GNU id-utils like this: > 1159 1160 :set grepprg=lid\ -Rgrep\ -s 1161 :set grepformat=%f:%l:%m 1162 1163then > 1164 :grep (regexp) 1165 1166works just as you'd expect. 1167(provided you remembered to mkid first :) 1168 1169 11705.5 Browsing source code with :vimgrep or :grep 1171 1172Using the stack of error lists that Vim keeps, you can browse your files to 1173look for functions and the functions they call. For example, suppose that you 1174have to add an argument to the read_file() function. You enter this command: > 1175 1176 :vimgrep /\<read_file\>/ *.c 1177 1178You use ":cn" to go along the list of matches and add the argument. At one 1179place you have to get the new argument from a higher level function msg(), and 1180need to change that one too. Thus you use: > 1181 1182 :vimgrep /\<msg\>/ *.c 1183 1184While changing the msg() functions, you find another function that needs to 1185get the argument from a higher level. You can again use ":vimgrep" to find 1186these functions. Once you are finished with one function, you can use > 1187 1188 :colder 1189 1190to go back to the previous one. 1191 1192This works like browsing a tree: ":vimgrep" goes one level deeper, creating a 1193list of branches. ":colder" goes back to the previous level. You can mix 1194this use of ":vimgrep" and "colder" to browse all the locations in a tree-like 1195way. If you do this consistently, you will find all locations without the 1196need to write down a "todo" list. 1197 1198============================================================================= 11996. Selecting a compiler *compiler-select* 1200 1201 *:comp* *:compiler* *E666* 1202:comp[iler][!] {name} Set options to work with compiler {name}. 1203 Without the "!" options are set for the 1204 current buffer. With "!" global options are 1205 set. 1206 If you use ":compiler foo" in "file.foo" and 1207 then ":compiler! bar" in another buffer, Vim 1208 will keep on using "foo" in "file.foo". 1209 {not available when compiled without the 1210 |+eval| feature} 1211 1212 1213The Vim plugins in the "compiler" directory will set options to use the 1214selected compiler. For `:compiler` local options are set, for `:compiler!` 1215global options. 1216 *current_compiler* 1217To support older Vim versions, the plugins always use "current_compiler" and 1218not "b:current_compiler". What the command actually does is the following: 1219 1220- Delete the "current_compiler" and "b:current_compiler" variables. 1221- Define the "CompilerSet" user command. With "!" it does ":set", without "!" 1222 it does ":setlocal". 1223- Execute ":runtime! compiler/{name}.vim". The plugins are expected to set 1224 options with "CompilerSet" and set the "current_compiler" variable to the 1225 name of the compiler. 1226- Delete the "CompilerSet" user command. 1227- Set "b:current_compiler" to the value of "current_compiler". 1228- Without "!" the old value of "current_compiler" is restored. 1229 1230 1231For writing a compiler plugin, see |write-compiler-plugin|. 1232 1233 1234GCC *quickfix-gcc* *compiler-gcc* 1235 1236There's one variable you can set for the GCC compiler: 1237 1238g:compiler_gcc_ignore_unmatched_lines 1239 Ignore lines that don't match any patterns 1240 defined for GCC. Useful if output from 1241 commands run from make are generating false 1242 positives. 1243 1244 1245MANX AZTEC C *quickfix-manx* *compiler-manx* 1246 1247To use Vim with Manx's Aztec C compiler on the Amiga you should do the 1248following: 1249- Set the CCEDIT environment variable with the command: > 1250 mset "CCEDIT=vim -q" 1251- Compile with the -qf option. If the compiler finds any errors, Vim is 1252 started and the cursor is positioned on the first error. The error message 1253 will be displayed on the last line. You can go to other errors with the 1254 commands mentioned above. You can fix the errors and write the file(s). 1255- If you exit Vim normally the compiler will re-compile the same file. If you 1256 exit with the :cq command, the compiler will terminate. Do this if you 1257 cannot fix the error, or if another file needs to be compiled first. 1258 1259There are some restrictions to the Quickfix mode on the Amiga. The 1260compiler only writes the first 25 errors to the errorfile (Manx's 1261documentation does not say how to get more). If you want to find the others, 1262you will have to fix a few errors and exit the editor. After recompiling, 1263up to 25 remaining errors will be found. 1264 1265If Vim was started from the compiler, the :sh and some :! commands will not 1266work, because Vim is then running in the same process as the compiler and 1267stdin (standard input) will not be interactive. 1268 1269 1270PERL *quickfix-perl* *compiler-perl* 1271 1272The Perl compiler plugin doesn't actually compile, but invokes Perl's internal 1273syntax checking feature and parses the output for possible errors so you can 1274correct them in quick-fix mode. 1275 1276Warnings are forced regardless of "no warnings" or "$^W = 0" within the file 1277being checked. To disable this set g:perl_compiler_force_warnings to a zero 1278value. For example: > 1279 let g:perl_compiler_force_warnings = 0 1280 1281 1282PYUNIT COMPILER *compiler-pyunit* 1283 1284This is not actually a compiler, but a unit testing framework for the 1285Python language. It is included into standard Python distribution 1286starting from version 2.0. For older versions, you can get it from 1287http://pyunit.sourceforge.net. 1288 1289When you run your tests with the help of the framework, possible errors 1290are parsed by Vim and presented for you in quick-fix mode. 1291 1292Unfortunately, there is no standard way to run the tests. 1293The alltests.py script seems to be used quite often, that's all. 1294Useful values for the 'makeprg' options therefore are: 1295 setlocal makeprg=./alltests.py " Run a testsuite 1296 setlocal makeprg=python\ %:S " Run a single testcase 1297 1298Also see http://vim.sourceforge.net/tip_view.php?tip_id=280. 1299 1300 1301TEX COMPILER *compiler-tex* 1302 1303Included in the distribution compiler for TeX ($VIMRUNTIME/compiler/tex.vim) 1304uses make command if possible. If the compiler finds a file named "Makefile" 1305or "makefile" in the current directory, it supposes that you want to process 1306your *TeX files with make, and the makefile does the right work. In this case 1307compiler sets 'errorformat' for *TeX output and leaves 'makeprg' untouched. If 1308neither "Makefile" nor "makefile" is found, the compiler will not use make. 1309You can force the compiler to ignore makefiles by defining 1310b:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked for 1311existence only). 1312 1313If the compiler chose not to use make, it needs to choose a right program for 1314processing your input. If b:tex_flavor or g:tex_flavor (in this precedence) 1315variable exists, it defines TeX flavor for :make (actually, this is the name 1316of executed command), and if both variables do not exist, it defaults to 1317"latex". For example, while editing chapter2.tex \input-ed from mypaper.tex 1318written in AMS-TeX: > 1319 1320 :let b:tex_flavor = 'amstex' 1321 :compiler tex 1322< [editing...] > 1323 :make mypaper 1324 1325Note that you must specify a name of the file to process as an argument (to 1326process the right file when editing \input-ed or \include-ed file; portable 1327solution for substituting % for no arguments is welcome). This is not in the 1328semantics of make, where you specify a target, not source, but you may specify 1329filename without extension ".tex" and mean this as "make filename.dvi or 1330filename.pdf or filename.some_result_extension according to compiler". 1331 1332Note: tex command line syntax is set to usable both for MikTeX (suggestion 1333by Srinath Avadhanula) and teTeX (checked by Artem Chuprina). Suggestion 1334from |errorformat-LaTeX| is too complex to keep it working for different 1335shells and OSes and also does not allow to use other available TeX options, 1336if any. If your TeX doesn't support "-interaction=nonstopmode", please 1337report it with different means to express \nonstopmode from the command line. 1338 1339============================================================================= 13407. The error format *error-file-format* 1341 1342 *errorformat* *E372* *E373* *E374* 1343 *E375* *E376* *E377* *E378* 1344The 'errorformat' option specifies a list of formats that are recognized. The 1345first format that matches with an error message is used. You can add several 1346formats for different messages your compiler produces, or even entries for 1347multiple compilers. See |efm-entries|. 1348 1349Each entry in 'errorformat' is a scanf-like string that describes the format. 1350First, you need to know how scanf works. Look in the documentation of your 1351C compiler. Below you find the % items that Vim understands. Others are 1352invalid. 1353 1354Special characters in 'errorformat' are comma and backslash. See 1355|efm-entries| for how to deal with them. Note that a literal "%" is matched 1356by "%%", thus it is not escaped with a backslash. 1357Keep in mind that in the `:make` and `:grep` output all NUL characters are 1358replaced with SOH (0x01). 1359 1360Note: By default the difference between upper and lowercase is ignored. If 1361you want to match case, add "\C" to the pattern |/\C|. 1362 1363Vim will read lines of any length, but only the first 4095 bytes are used, the 1364rest is ignored. Items can only be 1023 bytes long. 1365 1366 1367Basic items 1368 1369 %f file name (finds a string) 1370 %o module name (finds a string) 1371 %l line number (finds a number) 1372 %c column number (finds a number representing character 1373 column of the error, (1 <tab> == 1 character column)) 1374 %v virtual column number (finds a number representing 1375 screen column of the error (1 <tab> == 8 screen 1376 columns)) 1377 %t error type (finds a single character) 1378 %n error number (finds a number) 1379 %m error message (finds a string) 1380 %r matches the "rest" of a single-line file message %O/P/Q 1381 %p pointer line (finds a sequence of '-', '.', ' ' or 1382 tabs and uses the length for the column number) 1383 %*{conv} any scanf non-assignable conversion 1384 %% the single '%' character 1385 %s search text (finds a string) 1386 1387The "%f" conversion may depend on the current 'isfname' setting. "~/" is 1388expanded to the home directory and environment variables are expanded. 1389 1390The "%f" and "%m" conversions have to detect the end of the string. This 1391normally happens by matching following characters and items. When nothing is 1392following the rest of the line is matched. If "%f" is followed by a '%' or a 1393backslash, it will look for a sequence of 'isfname' characters. 1394 1395On MS-Windows a leading "C:" will be included in "%f", even when using "%f:". 1396This means that a file name which is a single alphabetical letter will not be 1397detected. 1398 1399The "%p" conversion is normally followed by a "^". It's used for compilers 1400that output a line like: > 1401 ^ 1402or > 1403 ---------^ 1404to indicate the column of the error. This is to be used in a multi-line error 1405message. See |errorformat-javac| for a useful example. 1406 1407The "%s" conversion specifies the text to search for, to locate the error line. 1408The text is used as a literal string. The anchors "^" and "$" are added to 1409the text to locate the error line exactly matching the search text and the 1410text is prefixed with the "\V" atom to make it "very nomagic". The "%s" 1411conversion can be used to locate lines without a line number in the error 1412output. Like the output of the "grep" shell command. 1413When the pattern is present the line number will not be used. 1414 1415The "%o" conversion specifies the module name in quickfix entry. If present 1416it will be used in quickfix error window instead of the filename. The module 1417name is used only for displaying purposes, the file name is used when jumping 1418to the file. 1419 1420Changing directory 1421 1422The following uppercase conversion characters specify the type of special 1423format strings. At most one of them may be given as a prefix at the beginning 1424of a single comma-separated format pattern. 1425Some compilers produce messages that consist of directory names that have to 1426be prepended to each file name read by %f (example: GNU make). The following 1427codes can be used to scan these directory names; they will be stored in an 1428internal directory stack. *E379* 1429 %D "enter directory" format string; expects a following 1430 %f that finds the directory name 1431 %X "leave directory" format string; expects following %f 1432 1433When defining an "enter directory" or "leave directory" format, the "%D" or 1434"%X" has to be given at the start of that substring. Vim tracks the directory 1435changes and prepends the current directory to each erroneous file found with a 1436relative path. See |quickfix-directory-stack| for details, tips and 1437limitations. 1438 1439 1440Multi-line messages *errorformat-multi-line* 1441 1442It is possible to read the output of programs that produce multi-line 1443messages, i.e. error strings that consume more than one line. Possible 1444prefixes are: 1445 %E start of a multi-line error message 1446 %W start of a multi-line warning message 1447 %I start of a multi-line informational message 1448 %A start of a multi-line message (unspecified type) 1449 %> for next line start with current pattern again |efm-%>| 1450 %C continuation of a multi-line message 1451 %Z end of a multi-line message 1452These can be used with '+' and '-', see |efm-ignore| below. 1453 1454Using "\n" in the pattern won't work to match multi-line messages. 1455 1456Example: Your compiler happens to write out errors in the following format 1457(leading line numbers not being part of the actual output): 1458 1459 1 Error 275 ~ 1460 2 line 42 ~ 1461 3 column 3 ~ 1462 4 ' ' expected after '--' ~ 1463 1464The appropriate error format string has to look like this: > 1465 :set efm=%EError\ %n,%Cline\ %l,%Ccolumn\ %c,%Z%m 1466 1467And the |:clist| error message generated for this error is: 1468 1469 1:42 col 3 error 275: ' ' expected after '--' 1470 1471Another example: Think of a Python interpreter that produces the following 1472error message (line numbers are not part of the actual output): 1473 1474 1 ============================================================== 1475 2 FAIL: testGetTypeIdCachesResult (dbfacadeTest.DjsDBFacadeTest) 1476 3 -------------------------------------------------------------- 1477 4 Traceback (most recent call last): 1478 5 File "unittests/dbfacadeTest.py", line 89, in testFoo 1479 6 self.assertEquals(34, dtid) 1480 7 File "/usr/lib/python2.2/unittest.py", line 286, in 1481 8 failUnlessEqual 1482 9 raise self.failureException, \ 1483 10 AssertionError: 34 != 33 1484 11 1485 12 -------------------------------------------------------------- 1486 13 Ran 27 tests in 0.063s 1487 1488Say you want |:clist| write the relevant information of this message only, 1489namely: 1490 5 unittests/dbfacadeTest.py:89: AssertionError: 34 != 33 1491 1492Then the error format string could be defined as follows: > 1493 :set efm=%C\ %.%#,%A\ \ File\ \"%f\"\\,\ line\ %l%.%#,%Z%[%^\ ]%\\@=%m 1494 1495Note that the %C string is given before the %A here: since the expression 1496' %.%#' (which stands for the regular expression ' .*') matches every line 1497starting with a space, followed by any characters to the end of the line, 1498it also hides line 7 which would trigger a separate error message otherwise. 1499Error format strings are always parsed pattern by pattern until the first 1500match occurs. 1501 *efm-%>* 1502The %> item can be used to avoid trying patterns that appear earlier in 1503'errorformat'. This is useful for patterns that match just about anything. 1504For example, if the error looks like this: 1505 1506 Error in line 123 of foo.c: ~ 1507 unknown variable "i" ~ 1508 1509This can be found with: > 1510 :set efm=xxx,%E%>Error in line %l of %f:,%Z%m 1511Where "xxx" has a pattern that would also match the second line. 1512 1513Important: There is no memory of what part of the errorformat matched before; 1514every line in the error file gets a complete new run through the error format 1515lines. For example, if one has: > 1516 setlocal efm=aa,bb,cc,dd,ee 1517Where aa, bb, etc. are error format strings. Each line of the error file will 1518be matched to the pattern aa, then bb, then cc, etc. Just because cc matched 1519the previous error line does _not_ mean that dd will be tried first on the 1520current line, even if cc and dd are multi-line errorformat strings. 1521 1522 1523 1524Separate file name *errorformat-separate-filename* 1525 1526These prefixes are useful if the file name is given once and multiple messages 1527follow that refer to this file name. 1528 %O single-line file message: overread the matched part 1529 %P single-line file message: push file %f onto the stack 1530 %Q single-line file message: pop the last file from stack 1531 1532Example: Given a compiler that produces the following error logfile (without 1533leading line numbers): 1534 1535 1 [a1.tt] 1536 2 (1,17) error: ';' missing 1537 3 (21,2) warning: variable 'z' not defined 1538 4 (67,3) error: end of file found before string ended 1539 5 1540 6 [a2.tt] 1541 7 1542 8 [a3.tt] 1543 9 NEW compiler v1.1 1544 10 (2,2) warning: variable 'x' not defined 1545 11 (67,3) warning: 's' already defined 1546 1547This logfile lists several messages for each file enclosed in [...] which are 1548properly parsed by an error format like this: > 1549 :set efm=%+P[%f],(%l\\,%c)%*[\ ]%t%*[^:]:\ %m,%-Q 1550 1551A call of |:clist| writes them accordingly with their correct filenames: 1552 1553 2 a1.tt:1 col 17 error: ';' missing 1554 3 a1.tt:21 col 2 warning: variable 'z' not defined 1555 4 a1.tt:67 col 3 error: end of file found before string ended 1556 8 a3.tt:2 col 2 warning: variable 'x' not defined 1557 9 a3.tt:67 col 3 warning: 's' already defined 1558 1559Unlike the other prefixes that all match against whole lines, %P, %Q and %O 1560can be used to match several patterns in the same line. Thus it is possible 1561to parse even nested files like in the following line: 1562 {"file1" {"file2" error1} error2 {"file3" error3 {"file4" error4 error5}}} 1563The %O then parses over strings that do not contain any push/pop file name 1564information. See |errorformat-LaTeX| for an extended example. 1565 1566 1567Ignoring and using whole messages *efm-ignore* 1568 1569The codes '+' or '-' can be combined with the uppercase codes above; in that 1570case they have to precede the letter, e.g. '%+A' or '%-G': 1571 %- do not include the matching multi-line in any output 1572 %+ include the whole matching line in the %m error string 1573 1574One prefix is only useful in combination with '+' or '-', namely %G. It parses 1575over lines containing general information like compiler version strings or 1576other headers that can be skipped. 1577 %-G ignore this message 1578 %+G general message 1579 1580 1581Pattern matching 1582 1583The scanf()-like "%*[]" notation is supported for backward-compatibility 1584with previous versions of Vim. However, it is also possible to specify 1585(nearly) any Vim supported regular expression in format strings. 1586Since meta characters of the regular expression language can be part of 1587ordinary matching strings or file names (and therefore internally have to 1588be escaped), meta symbols have to be written with leading '%': 1589 %\ The single '\' character. Note that this has to be 1590 escaped ("%\\") in ":set errorformat=" definitions. 1591 %. The single '.' character. 1592 %# The single '*'(!) character. 1593 %^ The single '^' character. Note that this is not 1594 useful, the pattern already matches start of line. 1595 %$ The single '$' character. Note that this is not 1596 useful, the pattern already matches end of line. 1597 %[ The single '[' character for a [] character range. 1598 %~ The single '~' character. 1599When using character classes in expressions (see |/\i| for an overview), 1600terms containing the "\+" quantifier can be written in the scanf() "%*" 1601notation. Example: "%\\d%\\+" ("\d\+", "any number") is equivalent to "%*\\d". 1602Important note: The \(...\) grouping of sub-matches can not be used in format 1603specifications because it is reserved for internal conversions. 1604 1605 1606Multiple entries in 'errorformat' *efm-entries* 1607 1608To be able to detect output from several compilers, several format patterns 1609may be put in 'errorformat', separated by commas (note: blanks after the comma 1610are ignored). The first pattern that has a complete match is used. If no 1611match is found, matching parts from the last one will be used, although the 1612file name is removed and the error message is set to the whole message. If 1613there is a pattern that may match output from several compilers (but not in a 1614right way), put it after one that is more restrictive. 1615 1616To include a comma in a pattern precede it with a backslash (you have to type 1617two in a ":set" command). To include a backslash itself give two backslashes 1618(you have to type four in a ":set" command). You also need to put a backslash 1619before a space for ":set". 1620 1621 1622Valid matches *quickfix-valid* 1623 1624If a line does not completely match one of the entries in 'errorformat', the 1625whole line is put in the error message and the entry is marked "not valid" 1626These lines are skipped with the ":cn" and ":cp" commands (unless there is 1627no valid line at all). You can use ":cl!" to display all the error messages. 1628 1629If the error format does not contain a file name Vim cannot switch to the 1630correct file. You will have to do this by hand. 1631 1632 1633Examples 1634 1635The format of the file from the Amiga Aztec compiler is: 1636 1637 filename>linenumber:columnnumber:errortype:errornumber:errormessage 1638 1639 filename name of the file in which the error was detected 1640 linenumber line number where the error was detected 1641 columnnumber column number where the error was detected 1642 errortype type of the error, normally a single 'E' or 'W' 1643 errornumber number of the error (for lookup in the manual) 1644 errormessage description of the error 1645 1646This can be matched with this 'errorformat' entry: 1647 %f>%l:%c:%t:%n:%m 1648 1649Some examples for C compilers that produce single-line error outputs: 1650%f:%l:\ %t%*[^0123456789]%n:\ %m for Manx/Aztec C error messages 1651 (scanf() doesn't understand [0-9]) 1652%f\ %l\ %t%*[^0-9]%n:\ %m for SAS C 1653\"%f\"\\,%*[^0-9]%l:\ %m for generic C compilers 1654%f:%l:\ %m for GCC 1655%f:%l:\ %m,%Dgmake[%*\\d]:\ Entering\ directory\ `%f', 1656%Dgmake[%*\\d]:\ Leaving\ directory\ `%f' 1657 for GCC with gmake (concat the lines!) 1658%f(%l)\ :\ %*[^:]:\ %m old SCO C compiler (pre-OS5) 1659%f(%l)\ :\ %t%*[^0-9]%n:\ %m idem, with error type and number 1660%f:%l:\ %m,In\ file\ included\ from\ %f:%l:,\^I\^Ifrom\ %f:%l%m 1661 for GCC, with some extras 1662 1663Extended examples for the handling of multi-line messages are given below, 1664see |errorformat-Jikes| and |errorformat-LaTeX|. 1665 1666Note the backslash in front of a space and double quote. It is required for 1667the :set command. There are two backslashes in front of a comma, one for the 1668:set command and one to avoid recognizing the comma as a separator of error 1669formats. 1670 1671 1672Filtering messages 1673 1674If you have a compiler that produces error messages that do not fit in the 1675format string, you could write a program that translates the error messages 1676into this format. You can use this program with the ":make" command by 1677changing the 'makeprg' option. For example: > 1678 :set mp=make\ \\\|&\ error_filter 1679The backslashes before the pipe character are required to avoid it to be 1680recognized as a command separator. The backslash before each space is 1681required for the set command. 1682 1683============================================================================= 16848. The directory stack *quickfix-directory-stack* 1685 1686Quickfix maintains a stack for saving all used directories parsed from the 1687make output. For GNU-make this is rather simple, as it always prints the 1688absolute path of all directories it enters and leaves. Regardless if this is 1689done via a 'cd' command in the makefile or with the parameter "-C dir" (change 1690to directory before reading the makefile). It may be useful to use the switch 1691"-w" to force GNU-make to print out the working directory before and after 1692processing. 1693 1694Maintaining the correct directory is more complicated if you don't use 1695GNU-make. AIX-make for example doesn't print any information about its 1696working directory. Then you need to enhance the makefile. In the makefile of 1697LessTif there is a command which echoes "Making {target} in {dir}". The 1698special problem here is that it doesn't print information on leaving the 1699directory and that it doesn't print the absolute path. 1700 1701To solve the problem with relative paths and missing "leave directory" 1702messages Vim uses following algorithm: 1703 17041) Check if the given directory is a subdirectory of the current directory. 1705 If this is true, store it as the current directory. 17062) If it is not a subdir of the current directory, try if this is a 1707 subdirectory of one of the upper directories. 17083) If the directory still isn't found, it is assumed to be a subdirectory 1709 of Vim's current directory. 1710 1711Additionally it is checked for every file, if it really exists in the 1712identified directory. If not, it is searched in all other directories of the 1713directory stack (NOT the directory subtree!). If it is still not found, it is 1714assumed that it is in Vim's current directory. 1715 1716There are limitations in this algorithm. These examples assume that make just 1717prints information about entering a directory in the form "Making all in dir". 1718 17191) Assume you have following directories and files: 1720 ./dir1 1721 ./dir1/file1.c 1722 ./file1.c 1723 1724 If make processes the directory "./dir1" before the current directory and 1725 there is an error in the file "./file1.c", you will end up with the file 1726 "./dir1/file.c" loaded by Vim. 1727 1728 This can only be solved with a "leave directory" message. 1729 17302) Assume you have following directories and files: 1731 ./dir1 1732 ./dir1/dir2 1733 ./dir2 1734 1735 You get the following: 1736 1737 Make output Directory interpreted by Vim 1738 ------------------------ ---------------------------- 1739 Making all in dir1 ./dir1 1740 Making all in dir2 ./dir1/dir2 1741 Making all in dir2 ./dir1/dir2 1742 1743 This can be solved by printing absolute directories in the "enter directory" 1744 message or by printing "leave directory" messages. 1745 1746To avoid this problem, ensure to print absolute directory names and "leave 1747directory" messages. 1748 1749Examples for Makefiles: 1750 1751Unix: 1752 libs: 1753 for dn in $(LIBDIRS); do \ 1754 (cd $$dn; echo "Entering dir '$$(pwd)'"; make); \ 1755 echo "Leaving dir"; \ 1756 done 1757 1758Add 1759 %DEntering\ dir\ '%f',%XLeaving\ dir 1760to your 'errorformat' to handle the above output. 1761 1762Note that Vim doesn't check if the directory name in a "leave directory" 1763messages is the current directory. This is why you could just use the message 1764"Leaving dir". 1765 1766============================================================================= 17679. Specific error file formats *errorformats* 1768 1769 *errorformat-Jikes* 1770Jikes(TM), a source-to-bytecode Java compiler published by IBM Research, 1771produces simple multi-line error messages. 1772 1773An 'errorformat' string matching the produced messages is shown below. 1774The following lines can be placed in the user's |vimrc| to overwrite Vim's 1775recognized default formats, or see |:set+=| how to install this format 1776additionally to the default. > 1777 1778 :set efm=%A%f:%l:%c:%*\\d:%*\\d:, 1779 \%C%*\\s%trror:%m, 1780 \%+C%*[^:]%trror:%m, 1781 \%C%*\\s%tarning:%m, 1782 \%C%m 1783< 1784Jikes(TM) produces a single-line error message when invoked with the option 1785"+E", and can be matched with the following: > 1786 1787 :setl efm=%f:%l:%v:%*\\d:%*\\d:%*\\s%m 1788< 1789 *errorformat-javac* 1790This 'errorformat' has been reported to work well for javac, which outputs a 1791line with "^" to indicate the column of the error: > 1792 :setl efm=%A%f:%l:\ %m,%-Z%p^,%-C%.%# 1793or: > 1794 :setl efm=%A%f:%l:\ %m,%+Z%p^,%+C%.%#,%-G%.%# 1795< 1796Here is an alternative from Michael F. Lamb for Unix that filters the errors 1797first: > 1798 :setl errorformat=%Z%f:%l:\ %m,%A%p^,%-G%*[^sl]%.%# 1799 :setl makeprg=javac\ %:S\ 2>&1\ \\\|\ vim-javac-filter 1800 1801You need to put the following in "vim-javac-filter" somewhere in your path 1802(e.g., in ~/bin) and make it executable: > 1803 #!/bin/sed -f 1804 /\^$/s/\t/\ /g;/:[0-9]\+:/{h;d};/^[ \t]*\^/G; 1805 1806In English, that sed script: 1807- Changes single tabs to single spaces and 1808- Moves the line with the filename, line number, error message to just after 1809 the pointer line. That way, the unused error text between doesn't break 1810 vim's notion of a "multi-line message" and also doesn't force us to include 1811 it as a "continuation of a multi-line message." 1812 1813 *errorformat-ant* 1814For ant (http://jakarta.apache.org/) the above errorformat has to be modified 1815to honour the leading [javac] in front of each javac output line: > 1816 :set efm=%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%# 1817 1818The 'errorformat' can also be configured to handle ant together with either 1819javac or jikes. If you're using jikes, you should tell ant to use jikes' +E 1820command line switch which forces jikes to generate one-line error messages. 1821This is what the second line (of a build.xml file) below does: > 1822 <property name = "build.compiler" value = "jikes"/> 1823 <property name = "build.compiler.emacs" value = "true"/> 1824 1825The 'errorformat' which handles ant with both javac and jikes is: > 1826 :set efm=\ %#[javac]\ %#%f:%l:%c:%*\\d:%*\\d:\ %t%[%^:]%#:%m, 1827 \%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%# 1828< 1829 *errorformat-jade* 1830parsing jade (see http://www.jclark.com/) errors is simple: > 1831 :set efm=jade:%f:%l:%c:%t:%m 1832< 1833 *errorformat-LaTeX* 1834The following is an example how an 'errorformat' string can be specified 1835for the (La)TeX typesetting system which displays error messages over 1836multiple lines. The output of ":clist" and ":cc" etc. commands displays 1837multi-lines in a single line, leading white space is removed. 1838It should be easy to adopt the above LaTeX errorformat to any compiler output 1839consisting of multi-line errors. 1840 1841The commands can be placed in a |vimrc| file or some other Vim script file, 1842e.g. a script containing LaTeX related stuff which is loaded only when editing 1843LaTeX sources. 1844Make sure to copy all lines of the example (in the given order), afterwards 1845remove the comment lines. For the '\' notation at the start of some lines see 1846|line-continuation|. 1847 1848 First prepare 'makeprg' such that LaTeX will report multiple 1849 errors; do not stop when the first error has occurred: > 1850 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*} 1851< 1852 Start of multi-line error messages: > 1853 :set efm=%E!\ LaTeX\ %trror:\ %m, 1854 \%E!\ %m, 1855< Start of multi-line warning messages; the first two also 1856 include the line number. Meaning of some regular expressions: 1857 - "%.%#" (".*") matches a (possibly empty) string 1858 - "%*\\d" ("\d\+") matches a number > 1859 \%+WLaTeX\ %.%#Warning:\ %.%#line\ %l%.%#, 1860 \%+W%.%#\ at\ lines\ %l--%*\\d, 1861 \%WLaTeX\ %.%#Warning:\ %m, 1862< Possible continuations of error/warning messages; the first 1863 one also includes the line number: > 1864 \%Cl.%l\ %m, 1865 \%+C\ \ %m., 1866 \%+C%.%#-%.%#, 1867 \%+C%.%#[]%.%#, 1868 \%+C[]%.%#, 1869 \%+C%.%#%[{}\\]%.%#, 1870 \%+C<%.%#>%.%#, 1871 \%C\ \ %m, 1872< Lines that match the following patterns do not contain any 1873 important information; do not include them in messages: > 1874 \%-GSee\ the\ LaTeX%m, 1875 \%-GType\ \ H\ <return>%m, 1876 \%-G\ ...%.%#, 1877 \%-G%.%#\ (C)\ %.%#, 1878 \%-G(see\ the\ transcript%.%#), 1879< Generally exclude any empty or whitespace-only line from 1880 being displayed: > 1881 \%-G\\s%#, 1882< The LaTeX output log does not specify the names of erroneous 1883 source files per line; rather they are given globally, 1884 enclosed in parentheses. 1885 The following patterns try to match these names and store 1886 them in an internal stack. The patterns possibly scan over 1887 the same input line (one after another), the trailing "%r" 1888 conversion indicates the "rest" of the line that will be 1889 parsed in the next go until the end of line is reached. 1890 1891 Overread a file name enclosed in '('...')'; do not push it 1892 on a stack since the file apparently does not contain any 1893 error: > 1894 \%+O(%f)%r, 1895< Push a file name onto the stack. The name is given after '(': > 1896 \%+P(%f%r, 1897 \%+P\ %\\=(%f%r, 1898 \%+P%*[^()](%f%r, 1899 \%+P[%\\d%[^()]%#(%f%r, 1900< Pop the last stored file name when a ')' is scanned: > 1901 \%+Q)%r, 1902 \%+Q%*[^()])%r, 1903 \%+Q[%\\d%*[^()])%r 1904 1905Note that in some cases file names in the LaTeX output log cannot be parsed 1906properly. The parser might have been messed up by unbalanced parentheses 1907then. The above example tries to catch the most relevant cases only. 1908You can customize the given setting to suit your own purposes, for example, 1909all the annoying "Overfull ..." warnings could be excluded from being 1910recognized as an error. 1911Alternatively to filtering the LaTeX compiler output, it is also possible 1912to directly read the *.log file that is produced by the [La]TeX compiler. 1913This contains even more useful information about possible error causes. 1914However, to properly parse such a complex file, an external filter should 1915be used. See the description further above how to make such a filter known 1916by Vim. 1917 1918 *errorformat-Perl* 1919In $VIMRUNTIME/tools you can find the efm_perl.pl script, which filters Perl 1920error messages into a format that quickfix mode will understand. See the 1921start of the file about how to use it. (This script is deprecated, see 1922|compiler-perl|.) 1923 1924 1925 1926 vim:tw=78:ts=8:noet:ft=help:norl: 1927