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