quickfix.txt (105531B)
1 *quickfix.txt* For Vim version 9.2. Last change: 2026 Sep 25 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 This subject is introduced in section |30.1| of the user manual. 8 9 1. Using QuickFix commands |quickfix| 10 2. The error window |quickfix-window| 11 3. Using more than one list of errors |quickfix-error-lists| 12 4. Using :make |:make_makeprg| 13 5. Using :grep |grep| 14 6. Selecting a compiler |compiler-select| 15 7. The error format |error-file-format| 16 8. The directory stack |quickfix-directory-stack| 17 9. Specific error file formats |errorformats| 18 10. Customizing the quickfix window |quickfix-window-function| 19 20 The quickfix commands are not available when the |+quickfix| feature was 21 disabled at compile time. 22 23 ============================================================================= 24 1. Using QuickFix commands *quickfix* *Quickfix* *E42* 25 26 Vim has a special mode to speedup the edit-compile-edit cycle. This is 27 inspired by the quickfix option of the Manx's Aztec C compiler on the Amiga. 28 The idea is to save the error messages from the compiler in a file and use Vim 29 to jump to the errors one by one. You can examine each problem and fix it, 30 without having to remember all the error messages. 31 32 In Vim the quickfix commands are used more generally to find a list of 33 positions in files. For example, |:vimgrep| finds pattern matches. You can 34 use the positions in a script with the |getqflist()| function. Thus you can 35 do a lot more than the edit/compile/fix cycle! 36 37 If you have the error messages in a file you can start Vim with: > 38 vim -q filename 39 40 From inside Vim an easy way to run a command and handle the output is with the 41 |:make| command (see below). 42 43 The 'errorformat' option should be set to match the error messages from your 44 compiler (see |errorformat| below). Vim uses it to extract information such 45 as the file name, line number and message from each line of compiler output. 46 Lines that do not match are kept as invalid entries and are skipped by 47 commands such as |:cnext|. Use |:clist|! to display them as well. 48 49 *quickfix-stack* *quickfix-ID* *E1545* 50 Each quickfix list has a unique identifier called the quickfix ID and this 51 number will not change within a Vim session. The |getqflist()| function can be 52 used to get the identifier assigned to a list. There is also a quickfix list 53 number, which is its position in the quickfix stack. This number may change 54 when lists are added or removed, or when more than 'chistory' lists are kept. 55 Use the ID when a script needs to refer to the same list reliably; use the 56 list number when referring to its current position in the stack. 57 58 *location-list* *E776* 59 A location list is a quickfix list tied to one window. Each window can have a 60 separate location list, and commands such as `:lvimgrep`, `:lgrep`, 61 `:lhelpgrep` and `:lmake` use it instead of the global quickfix list. The 62 corresponding commands without the "l" prefix use the quickfix list. 63 *location-list-file-window* 64 The location list is independent of the quickfix list. A location list can 65 be associated with only one window. 66 67 When a window with a location list is split, the new window gets a copy of the 68 location list. When there are no longer any references to a location list, 69 the location list is destroyed. 70 71 *quickfix-changedtick* 72 Every quickfix and location list has a read-only changedtick variable that 73 tracks the total number of changes made to the list. Every time the quickfix 74 list is modified, this count is incremented. This can be used to perform an 75 action only when the list has changed. The |getqflist()| and |getloclist()| 76 functions can be used to query the current value of changedtick. You cannot 77 change the changedtick variable. 78 79 The following quickfix commands can be used. The location list commands are 80 similar to the quickfix commands, replacing the 'c' prefix in the quickfix 81 command with 'l'. 82 83 *E924* 84 If the current window was closed by an |autocommand| while processing a 85 location list command, it will be aborted. 86 87 *E925* *E926* 88 If the current quickfix or location list was changed by an |autocommand| while 89 processing a quickfix or location list command, it will be aborted. 90 91 *:cc* 92 :cc[!] [nr] Display error [nr]. If [nr] is omitted, the same 93 :[nr]cc[!] error is displayed again. Without [!] this doesn't 94 work when jumping to another buffer, the current 95 buffer has been changed, there is the only window for 96 the buffer and both 'hidden' and 'autowrite' are off. 97 When jumping to another buffer with [!] any changes to 98 the current buffer are lost, unless 'hidden' is set or 99 there is another window for this buffer. 100 The 'switchbuf' settings are respected when jumping 101 to a buffer. 102 When used in the quickfix window the line number can 103 be used, including "." for the current line and "$" 104 for the last line. 105 106 *:ll* 107 :ll[!] [nr] Same as ":cc", except the location list for the 108 :[nr]ll[!] current window is used instead of the quickfix list. 109 110 *:cn* *:cne* *:cnext* *E553* 111 :[count]cn[ext][!] Display the [count] next error in the list that 112 includes a file name. Entries without a file name are 113 skipped, since Vim cannot use them to jump to a file. 114 If there are no file names at all, go to the [count] 115 next error. See |:cc| for [!] and 'switchbuf'. 116 117 :[count]cN[ext][!] *:cp* *:cprevious* *:cprev* *:cN* *:cNext* 118 :[count]cp[revious][!] Display the [count] previous error in the list that 119 includes a file name. Entries without a file name are 120 skipped, since Vim cannot use them to jump to a file. 121 If there are no file names at all, go to the [count] 122 previous error. See |:cc| for [!] and 'switchbuf'. 123 124 *:lne* *:lnext* 125 :[count]lne[xt][!] Same as ":cnext", except the location list for the 126 current window is used instead of the quickfix list. 127 128 129 :[count]lN[ext][!] *:lp* *:lprevious* *:lprev* *:lN* *:lNext* 130 :[count]lp[revious][!] Same as ":cNext" and ":cprevious", except the location 131 list for the current window is used instead of the 132 quickfix list. 133 134 *:cabo* *:cabove* 135 :[count]cabo[ve] Go to the [count] error above the current line in the 136 current buffer. If [count] is omitted, then 1 is 137 used. If there are no errors, then an error message 138 is displayed. Assumes that the entries in a quickfix 139 list are sorted by their buffer number and line 140 number. If there are multiple errors on the same 141 line, then only the first entry is used. If [count] 142 exceeds the number of entries above the current line, 143 then the first error in the file is selected. 144 145 *:lab* *:labove* 146 :[count]lab[ove] Same as ":cabove", except the location list for the 147 current window is used instead of the quickfix list. 148 149 *:cbel* *:cbelow* 150 :[count]cbel[ow] Go to the [count] error below the current line in the 151 current buffer. If [count] is omitted, then 1 is 152 used. If there are no errors, then an error message 153 is displayed. Assumes that the entries in a quickfix 154 list are sorted by their buffer number and line 155 number. If there are multiple errors on the same 156 line, then only the first entry is used. If [count] 157 exceeds the number of entries below the current line, 158 then the last error in the file is selected. 159 160 *:lbel* *:lbelow* 161 :[count]lbel[ow] Same as ":cbelow", except the location list for the 162 current window is used instead of the quickfix list. 163 164 *:cbe* *:cbefore* 165 :[count]cbe[fore] Go to the [count] error before the current cursor 166 position in the current buffer. If [count] is 167 omitted, then 1 is used. If there are no errors, then 168 an error message is displayed. Assumes that the 169 entries in a quickfix list are sorted by their buffer, 170 line and column numbers. If [count] exceeds the 171 number of entries before the current position, then 172 the first error in the file is selected. 173 174 *:lbe* *:lbefore* 175 :[count]lbe[fore] Same as ":cbefore", except the location list for the 176 current window is used instead of the quickfix list. 177 178 *:caf* *:cafter* 179 :[count]caf[ter] Go to the [count] error after the current cursor 180 position in the current buffer. If [count] is 181 omitted, then 1 is used. If there are no errors, then 182 an error message is displayed. Assumes that the 183 entries in a quickfix list are sorted by their buffer, 184 line and column numbers. If [count] exceeds the 185 number of entries after the current position, then 186 the last error in the file is selected. 187 188 *:laf* *:lafter* 189 :[count]laf[ter] Same as ":cafter", except the location list for the 190 current window is used instead of the quickfix list. 191 192 *:cnf* *:cnfile* 193 :[count]cnf[ile][!] Display the first error in the [count] next file in 194 the list that includes a file name. If there are no 195 file names at all or if there is no next file, go to 196 the [count] next error. See |:cc| for [!] and 197 'switchbuf'. 198 199 *:lnf* *:lnfile* 200 :[count]lnf[ile][!] Same as ":cnfile", except the location list for the 201 current window is used instead of the quickfix list. 202 203 :[count]cNf[ile][!] *:cpf* *:cpfile* *:cNf* *:cNfile* 204 :[count]cpf[ile][!] Display the last error in the [count] previous file in 205 the list that includes a file name. If there are no 206 file names at all or if there is no next file, go to 207 the [count] previous error. See |:cc| for [!] and 208 'switchbuf'. 209 210 211 :[count]lNf[ile][!] *:lpf* *:lpfile* *:lNf* *:lNfile* 212 :[count]lpf[ile][!] Same as ":cNfile" and ":cpfile", except the location 213 list for the current window is used instead of the 214 quickfix list. 215 216 *:crewind* *:cr* 217 :cr[ewind][!] [nr] Display error [nr]. If [nr] is omitted, the FIRST 218 error is displayed. See |:cc|. 219 220 *:lrewind* *:lr* 221 :lr[ewind][!] [nr] Same as ":crewind", except the location list for the 222 current window is used instead of the quickfix list. 223 224 *:cfirst* *:cfir* 225 :cfir[st][!] [nr] Same as ":crewind". 226 227 *:lfirst* *:lfir* 228 :lfir[st][!] [nr] Same as ":lrewind". 229 230 *:clast* *:cla* 231 :cla[st][!] [nr] Display error [nr]. If [nr] is omitted, the LAST 232 error is displayed. See |:cc|. 233 234 *:llast* *:lla* 235 :lla[st][!] [nr] Same as ":clast", except the location list for the 236 current window is used instead of the quickfix list. 237 238 *:cq* *:cquit* 239 :cq[uit][!] 240 :{N}cq[uit][!] 241 :cq[uit][!] {N} Quit Vim with error code {N}. {N} defaults to one. 242 Useful when Vim is called from another program: 243 e.g., a compiler will not compile the same file again, 244 `git commit` will abort the committing process, `fc` 245 (built-in for shells like bash and zsh) will not 246 execute the command, etc. 247 {N} can also be zero, in which case Vim exits 248 normally. 249 WARNING: This abandons changes in all files, like 250 |:qall|!. 251 The [!] does not change this. Vim returns a non-zero 252 exit code, unless {N} is zero. 253 254 *:cf* *:cfi* *:cfile* 255 :cf[ile][!] [errorfile] Read the error file and jump to the first error. 256 This is done automatically when Vim is started with 257 the -q option. You can use this command when you 258 keep Vim running while compiling. If you give the 259 name of the errorfile, the 'errorfile' option will 260 be set to [errorfile]. See |:cc| for [!]. 261 If the encoding of the error file differs from the 262 'encoding' option, you can use the 'makeencoding' 263 option to specify the encoding. 264 265 *:lf* *:lfi* *:lfile* 266 :lf[ile][!] [errorfile] Same as ":cfile", except the location list for the 267 current window is used instead of the quickfix list. 268 You can not use the -q command-line option to set 269 the location list. 270 271 272 :cg[etfile] [errorfile] *:cg* *:cgetfile* 273 Read the error file. Just like ":cfile" but don't 274 jump to the first error. 275 If the encoding of the error file differs from the 276 'encoding' option, you can use the 'makeencoding' 277 option to specify the encoding. 278 279 280 :lg[etfile] [errorfile] *:lg* *:lge* *:lgetfile* 281 Same as ":cgetfile", except the location list for the 282 current window is used instead of the quickfix list. 283 284 *:caddf* *:caddfile* 285 :caddf[ile] [errorfile] Read the error file and add the errors from the 286 errorfile to the current quickfix list. If a quickfix 287 list is not present, then a new list is created. 288 If the encoding of the error file differs from the 289 'encoding' option, you can use the 'makeencoding' 290 option to specify the encoding. 291 292 *:laddf* *:laddfile* 293 :laddf[ile] [errorfile] Same as ":caddfile", except the location list for the 294 current window is used instead of the quickfix list. 295 296 The following commands read error messages from a buffer: 297 `:cbuffer` creates a list and jumps to its first error, `:cgetbuffer` creates 298 a list without jumping, and `:caddbuffer` adds entries to the current list 299 without changing the cursor position. The corresponding commands with an "l" 300 prefix use the location list. 301 302 *:cb* *:cbuffer* *E681* 303 :[range]cb[uffer][!] [bufnr] 304 Read the error list from the current buffer. 305 When [bufnr] is given it must be the number of a 306 loaded buffer. That buffer will then be used instead 307 of the current buffer. 308 A range can be specified for the lines to be used, for 309 example `:10,20cbuffer`. Otherwise all lines in the 310 buffer are used. 311 See |:cc| for [!]. 312 313 *:lb* *:lbuffer* 314 :[range]lb[uffer][!] [bufnr] 315 Same as ":cbuffer", except the location list for the 316 current window is used instead of the quickfix list. 317 318 *:cgetb* *:cgetbuffer* 319 :[range]cgetb[uffer] [bufnr] 320 Read the error list from the current buffer. Just 321 like ":cbuffer" but don't jump to the first error. 322 323 *:lgetb* *:lgetbuffer* 324 :[range]lgetb[uffer] [bufnr] 325 Same as ":cgetbuffer", except the location list for 326 the current window is used instead of the quickfix 327 list. 328 329 *:cad* *:cadd* *:caddbuffer* 330 :[range]cad[dbuffer] [bufnr] 331 Read the error list from the current buffer and add 332 the errors to the current quickfix list. If a 333 quickfix list is not present, then a new list is 334 created. Otherwise, same as ":cbuffer". 335 336 *:laddb* *:laddbuffer* 337 :[range]laddb[uffer] [bufnr] 338 Same as ":caddbuffer", except the location list for 339 the current window is used instead of the quickfix 340 list. 341 342 The following commands create or update a quickfix list from an expression: 343 `:cexpr` creates a list and jumps to its first error, `:cgetexpr` creates a 344 list without jumping, and `:caddexpr` adds entries to the current list without 345 changing the cursor position. The corresponding commands with an "l" prefix 346 use the location list. 347 348 *:cex* *:cexpr* *E777* 349 :cex[pr][!] {expr} Create a quickfix list using the result of {expr} and 350 jump to the first error. 351 If {expr} is a String, then each newline terminated 352 line in the String is processed using the global value 353 of 'errorformat' and the result is added to the 354 quickfix list. 355 If {expr} is a List, then each String item in the list 356 is processed and added to the quickfix list. Non 357 String items in the List are ignored. 358 See |:cc| for [!]. 359 Examples: > 360 :cexpr system('grep -n xyz *') 361 :cexpr getline(1, '$') 362 < 363 *:lex* *:lexpr* 364 :lex[pr][!] {expr} Same as |:cexpr|, except the location list for the 365 current window is used instead of the quickfix list. 366 367 *:cgete* *:cgetexpr* 368 :cgete[xpr] {expr} Create a quickfix list using the result of {expr}. 369 Just like |:cexpr|, but don't jump to the first error. 370 371 *:lgete* *:lgetexpr* 372 :lgete[xpr] {expr} Same as |:cgetexpr|, except the location list for the 373 current window is used instead of the quickfix list. 374 375 *:cadde* *:caddexpr* 376 :cadde[xpr] {expr} Evaluate {expr} and add the resulting lines to the 377 current quickfix list. If a quickfix list is not 378 present, then a new list is created. The current 379 cursor position will not be changed. See |:cexpr| for 380 more information. 381 Example: > 382 :g/mypattern/caddexpr expand("%") .. ":" .. line(".") .. ":" .. getline(".") 383 < 384 *:lad* *:ladd* *:laddexpr* 385 :lad[dexpr] {expr} Same as ":caddexpr", except the location list for the 386 current window is used instead of the quickfix list. 387 388 *:cl* *:clist* 389 :cl[ist] [from] [, [to]] 390 List all errors that are valid |quickfix-valid|. 391 If numbers [from] and/or [to] are given, the 392 respective range of errors is listed. A negative 393 number counts from the last error backwards, -1 being 394 the last error. 395 The |:filter| command can be used to display only the 396 quickfix entries matching a supplied pattern. The 397 pattern is matched against the filename, module name, 398 pattern and text of the entry. 399 For example, `:filter /\.c:/clist` lists only entries 400 whose displayed text contains `.c:`. See |:filter|. 401 402 :cl[ist] +{count} List the current and next {count} valid errors. This 403 is similar to ":clist from from+count", where "from" 404 is the current error position. 405 406 :cl[ist]! [from] [, [to]] 407 List all errors. 408 409 :cl[ist]! +{count} List the current and next {count} error lines. This 410 is useful to see unrecognized lines after the current 411 one. For example, if ":clist" shows: 412 8384 testje.java:252: error: cannot find symbol ~ 413 Then using ":cl! +3" shows the reason: 414 8384 testje.java:252: error: cannot find symbol ~ 415 8385: ZexitCode = Fmainx(); ~ 416 8386: ^ ~ 417 8387: symbol: method Fmainx() ~ 418 419 :lli[st] [from] [, [to]] *:lli* *:llist* 420 Same as ":clist", except the location list for the 421 current window is used instead of the quickfix list. 422 423 :lli[st]! [from] [, [to]] 424 List all the entries in the location list for the 425 current window. 426 427 If you insert or delete lines, mostly the correct error location is still 428 found because hidden marks are used. Sometimes, when the mark has been 429 deleted for some reason, the message "line changed" is shown to warn you that 430 the error location may not be correct. If you quit Vim and start again the 431 marks are lost and the error locations may not be correct anymore. 432 433 Two autocommands are available for running commands before and after a 434 quickfix command (':make', ':grep' and so on) is executed. See 435 |QuickFixCmdPre| and |QuickFixCmdPost| for details. 436 437 *QuickFixCmdPost-example* 438 When 'encoding' differs from the locale, the error messages may have a 439 different encoding from what Vim is using. To convert the messages you can 440 use this code: > 441 function QfMakeConv() 442 let qflist = getqflist() 443 for i in qflist 444 let i.text = iconv(i.text, "cp936", "utf-8") 445 endfor 446 call setqflist(qflist) 447 endfunction 448 449 au QuickFixCmdPost make call QfMakeConv() 450 Another option is using 'makeencoding'. 451 452 *quickfix-title* 453 Every quickfix and location list has a title. By default the title is set to 454 the command that created the list. The |getqflist()| and |getloclist()| 455 functions can be used to get the title of a quickfix and a location list 456 respectively. The |setqflist()| and |setloclist()| functions can be used to 457 modify the title of a quickfix and location list respectively. Examples: > 458 call setqflist([], 'a', {'title' : 'Cmd output'}) 459 echo getqflist({'title' : 1}) 460 call setloclist(3, [], 'a', {'title' : 'Cmd output'}) 461 echo getloclist(3, {'title' : 1}) 462 < 463 *quickfix-index* 464 When you jump to a quickfix/location list entry using any of the quickfix 465 commands (e.g. |:cc|, |:cnext|, |:cprev|, etc.), that entry becomes the 466 currently selected entry. The index of the currently selected entry in a 467 quickfix/location list can be obtained using the getqflist()/getloclist() 468 functions. Examples: > 469 echo getqflist({'idx' : 0}).idx 470 echo getqflist({'id' : qfid, 'idx' : 0}).idx 471 echo getloclist(2, {'idx' : 0}).idx 472 < 473 For a new quickfix list, the first entry is selected and the index is 1. Any 474 entry in any quickfix/location list can be set as the currently selected entry 475 using the setqflist() function. Examples: > 476 call setqflist([], 'a', {'idx' : 12}) 477 call setqflist([], 'a', {'id' : qfid, 'idx' : 7}) 478 call setloclist(1, [], 'a', {'idx' : 7}) 479 < 480 *quickfix-size* 481 You can get the number of entries (size) in a quickfix and a location list 482 using the |getqflist()| and |getloclist()| functions respectively. Examples: > 483 echo getqflist({'size' : 1}) 484 echo getloclist(5, {'size' : 1}) 485 < 486 *quickfix-context* 487 Any Vim type can be associated as a context with a quickfix or location list. 488 The |setqflist()| and the |setloclist()| functions can be used to associate a 489 context with a quickfix and a location list respectively. The |getqflist()| 490 and the |getloclist()| functions can be used to retrieve the context of a 491 quickfix and a location list respectively. This is useful for a Vim plugin 492 dealing with multiple quickfix/location lists. 493 Examples: > 494 495 let somectx = {'name' : 'Vim', 'type' : 'Editor'} 496 call setqflist([], 'a', {'context' : somectx}) 497 echo getqflist({'context' : 1}) 498 499 let newctx = ['red', 'green', 'blue'] 500 call setloclist(2, [], 'a', {'id' : qfid, 'context' : newctx}) 501 echo getloclist(2, {'id' : qfid, 'context' : 1}) 502 < 503 *quickfix-parse* 504 You can parse a list of lines using 'errorformat' without creating or 505 modifying a quickfix list using the |getqflist()| function. Examples: > 506 echo getqflist({'lines' : ["F1:10:Line10", "F2:20:Line20"]}) 507 echo getqflist({'lines' : systemlist('grep -Hn quickfix *')}) 508 This returns a dictionary where the "items" key contains the list of quickfix 509 entries parsed from lines. The following shows how to use a custom 510 'errorformat' to parse the lines without modifying the 'errorformat' option: > 511 echo getqflist({'efm' : '%f#%l#%m', 'lines' : ['F1#10#Line']}) 512 < 513 514 To execute a command for entries or files in a list, use: 515 516 Quickfix list Location list 517 Each entry :cdo :ldo 518 Each file :cfdo :lfdo 519 520 Use `:cdo` when a command should run for every valid entry, for example 521 `:cdo s/old/new/g` to change each matching line. Use `:cfdo` when it should 522 run once for each file, for example `:cfdo update` to write each affected file 523 once. Add the "l" prefix to use the location list instead. 524 525 The commands below describe these differences in more detail. 526 527 EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST: 528 *:cdo* 529 :cdo[!] {cmd} Execute {cmd} in each valid entry in the quickfix 530 list. It works like doing this: > 531 :cfirst 532 :{cmd} 533 :cnext 534 :{cmd} 535 etc. 536 < When the current file can't be |abandon|ed and the [!] 537 is not present, the command fails. 538 When going to the next entry fails execution stops. 539 The last buffer (or where an error occurred) becomes 540 the current buffer. 541 {cmd} can contain '|' to concatenate several commands. 542 543 Only valid entries in the quickfix list are used. 544 A range can be used to select entries, e.g.: > 545 :10,$cdo cmd 546 < To skip entries 1 to 9. 547 548 Note: While this command is executing, the Syntax 549 autocommand event is disabled by adding it to 550 'eventignore'. This considerably speeds up editing 551 each buffer. 552 Also see |:bufdo|, |:tabdo|, |:argdo|, |:windo|, 553 |:ldo|, |:cfdo| and |:lfdo|. 554 555 *:cfd* *:cfdo* 556 :cfd[o][!] {cmd} Execute {cmd} in each file in the quickfix list. 557 It works like doing this: > 558 :cfirst 559 :{cmd} 560 :cnfile 561 :{cmd} 562 etc. 563 < Otherwise it works the same as `:cdo`. 564 565 *:ld* *:ldo* 566 :ld[o][!] {cmd} Execute {cmd} in each valid entry in the location list 567 for the current window. 568 It works like doing this: > 569 :lfirst 570 :{cmd} 571 :lnext 572 :{cmd} 573 etc. 574 < Only valid entries in the location list are used. 575 Otherwise it works the same as `:cdo`. 576 577 *:lfd* *:lfdo* 578 :lfd[o][!] {cmd} Execute {cmd} in each file in the location list for 579 the current window. 580 It works like doing this: > 581 :lfirst 582 :{cmd} 583 :lnfile 584 :{cmd} 585 etc. 586 < Otherwise it works the same as `:ldo`. 587 588 FILTERING A QUICKFIX OR LOCATION LIST: 589 *cfilter-plugin* *:Cfilter* *:Lfilter* *package-cfilter* 590 If you have too many entries in a quickfix list, you can use the cfilter 591 plugin to reduce the number of entries. Load the plugin with: >vim 592 593 packadd cfilter 594 595 Then you can use the following commands to filter a quickfix/location list: > 596 597 :Cfilter[!] /{pat}/ 598 :Lfilter[!] /{pat}/ 599 600 The |:Cfilter| command creates a new quickfix list from the entries matching 601 {pat} in the current quickfix list. {pat} is a Vim |regular-expression| 602 pattern. Both the file name and the text of the entries are matched against 603 {pat}. If the optional ! is supplied, then the entries not matching {pat} are 604 used. The pattern can be optionally enclosed using one of the following 605 characters: ', ", /. If the pattern is empty, then the last used search 606 pattern is used. 607 608 The |:Lfilter| command does the same as |:Cfilter| but operates on the current 609 location list. 610 611 The current quickfix/location list is not modified by these commands, so you 612 can go back to the unfiltered list using the |:colder|/|:lolder| command. 613 614 ============================================================================= 615 2. The error window *quickfix-window* 616 617 *:cope* *:copen* *w:quickfix_title* 618 :cope[n] [height] Open a window to show the current list of errors. 619 620 When [height] is given, the window becomes that high 621 (if there is room). When [height] is omitted the 622 window is made ten lines high. 623 624 If there already is a quickfix window, it will be made 625 the current window. It is not possible to open a 626 second quickfix window. If [height] is given the 627 existing window will be resized to it. 628 629 *quickfix-buffer* 630 The window will contain a special buffer, with 631 'buftype' equal to "quickfix". Don't change this! 632 The window will have the w:quickfix_title variable set 633 which will indicate the command that produced the 634 quickfix list. This can be used to compose a custom 635 status line if the value of 'statusline' is adjusted 636 properly. Whenever this buffer is modified by a 637 quickfix command or function, the |b:changedtick| 638 variable is incremented. You can get the number of 639 this buffer using the getqflist() and getloclist() 640 functions by passing the "qfbufnr" item. For a 641 location list, this buffer is wiped out when the 642 location list is removed. 643 644 *:lop* *:lopen* 645 :lop[en] [height] Open a window to show the location list for the 646 current window. Works only when the location list for 647 the current window is present. You can have more than 648 one location window opened at a time. Otherwise, it 649 acts the same as ":copen". 650 651 *:ccl* *:cclose* 652 :ccl[ose] Close the quickfix window. 653 654 *:lcl* *:lclose* 655 :lcl[ose] Close the window showing the location list for the 656 current window. 657 658 *:cw* *:cwindow* 659 :cw[indow] [height] Open the quickfix window when there are recognized 660 errors. If the window is already open and there are 661 no recognized errors, close the window. 662 663 When opening the window and [height] is given, the 664 window becomes that high (if there is room). When 665 [height] is omitted the window is made ten lines high. 666 667 *:lw* *:lwindow* 668 :lw[indow] [height] Same as ":cwindow", except use the window showing the 669 location list for the current window. 670 671 *:cbo* *:cbottom* 672 :cbo[ttom] Put the cursor in the last line of the quickfix window 673 and scroll to make it visible. This is useful for 674 when errors are added by an asynchronous callback. 675 Only call it once in a while if there are many 676 updates to avoid a lot of redrawing. 677 678 *:lbo* *:lbottom* 679 :lbo[ttom] Same as ":cbottom", except use the window showing the 680 location list for the current window. 681 682 Normally the quickfix window is at the bottom of the screen. If there are 683 vertical splits, it's at the bottom of the rightmost column of windows. To 684 make it always occupy the full width: > 685 :botright cwindow 686 You can move the window around with |window-moving| commands. 687 For example, to move it to the top: CTRL-W K 688 The 'winfixheight' option will be set, which means that the window will mostly 689 keep its height, ignoring 'winheight' and 'equalalways'. You can change the 690 height manually (e.g., by dragging the status line above it with the mouse). 691 692 In the quickfix window, each line is one error. The line number is equal to 693 the error number. The current entry is highlighted with the QuickFixLine 694 highlighting. You can change it to your liking, e.g.: > 695 :hi QuickFixLine ctermbg=Yellow guibg=Yellow 696 697 You can use ":.cc" to jump to the error under the cursor. 698 Hitting the <Enter> key or double-clicking the mouse on a line has the same 699 effect. The file containing the error is opened in the window above the 700 quickfix window. If there already is a window for that file, it is used 701 instead. If the buffer in the used window has changed, and the error is in 702 another file, jumping to the error will fail. You will first have to make 703 sure the window contains a buffer which can be abandoned. 704 705 When you select a file from the quickfix window, Vim first reuses a window 706 that already displays the file. Otherwise it uses a suitable window in the 707 current tab page, or opens a new one. The detailed selection rules are: 708 709 1. If a window displaying the selected file is present in the current tabpage 710 (starting with the window before the quickfix window), then that window is 711 used. 712 2. If the above step fails and if 'switchbuf' contains "usetab" and a window 713 displaying the selected file is present in any one of the tabpages 714 (starting with the first tabpage) then that window is used. 715 3. If the above step fails then a window in the current tabpage displaying a 716 buffer with 'buftype' not set (starting with the window before the quickfix 717 window) is used. 718 4. If the above step fails and if 'switchbuf' contains "uselast", then the 719 previously accessed window is used. 720 5. If the above step fails then the window before the quickfix window is used. 721 If there is no previous window, then the window after the quickfix window 722 is used. 723 6. If the above step fails, then a new horizontally split window above the 724 quickfix window is used. 725 726 *quickfix-winfixbuf* 727 When 'winfixbuf' is set for the window that would be used to display the 728 error, jumping to an error in another buffer is not possible in that window. 729 For a quickfix list Vim then looks for another suitable window, using the 730 previously accessed window if it does not have 'winfixbuf' set, and otherwise 731 splits a new window. For a location list this fails with |E1513|, because a 732 location list is tied to its window and cannot move to or split off another 733 one. Using [!] skips these checks. 734 735 *CTRL-W_<Enter>* *CTRL-W_<CR>* 736 You can use CTRL-W <Enter> to open a new window and jump to the error there. 737 738 When the quickfix window has been filled, two autocommand events are 739 triggered. First the 'filetype' option is set to "qf", which triggers the 740 FileType event (also see |qf.vim|). Then the BufReadPost event is triggered, 741 using "quickfix" for the buffer name. This can be used to perform some action 742 on the listed errors. Example: > 743 au BufReadPost quickfix setlocal modifiable 744 \ | silent exe 'g/^/s//\=line(".") .. " "/' 745 \ | setlocal nomodifiable 746 This prepends the line number to each line. Note the use of "\=" in the 747 substitute string of the ":s" command, which is used to evaluate an 748 expression. 749 The BufWinEnter event is also triggered, again using "quickfix" for the buffer 750 name. 751 752 Note: When adding to an existing quickfix list the autocommand are not 753 triggered. 754 755 Note: Making changes in the quickfix window has no effect on the list of 756 errors. 'modifiable' is off to avoid making changes. If you delete or insert 757 lines anyway, the relation between the text and the error number is messed up. 758 If you really want to do this, you could write the contents of the quickfix 759 window to a file and use ":cfile" to have it parsed and used as the new error 760 list. 761 762 *location-list-window* 763 The location list window displays the entries in a location list. When you 764 open a location list window, it is created below the current window and 765 displays the location list for the current window. The location list window 766 is similar to the quickfix window, except that you can have more than one 767 location list window open at a time. When you use a location list command in 768 this window, the displayed location list is used. 769 770 When you select a file from the location list window, Vim first uses the 771 window associated with that location list, when possible. Otherwise it 772 reuses a suitable window or opens a new one. The detailed selection rules 773 are: 774 775 1. If a non-quickfix window associated with the location list is present in 776 the current tabpage, then that window is used. 777 2. If the above step fails and if the file is already opened in another window 778 in the current tabpage, then that window is used. 779 3. If the above step fails and 'switchbuf' contains "usetab" and if the file 780 is opened in a window in any one of the tabpages, then that window is used. 781 4. If the above step fails then a window in the current tabpage showing a 782 buffer with 'buftype' not set is used. 783 5. If the above step fails, then the file is edited in a new window. 784 785 In all of the above cases, if the location list for the selected window is not 786 yet set, then it is set to the location list displayed in the location list 787 window. 788 789 *quickfix-window-ID* 790 You can use the |getqflist()| and |getloclist()| functions to obtain the 791 window ID of the quickfix window and location list window respectively (if 792 present). Examples: > 793 echo getqflist({'winid' : 1}).winid 794 echo getloclist(2, {'winid' : 1}).winid 795 < 796 *getqflist-examples* 797 The |getqflist()| and |getloclist()| functions can be used to get the various 798 attributes of a quickfix and location list respectively. Some examples for 799 using these functions are below: 800 > 801 " get the title of the current quickfix list 802 :echo getqflist({'title' : 0}).title 803 804 " get the identifier of the current quickfix list 805 :let qfid = getqflist({'id' : 0}).id 806 807 " get the identifier of the fourth quickfix list in the stack 808 :let qfid = getqflist({'nr' : 4, 'id' : 0}).id 809 810 " check whether a quickfix list with a specific identifier exists 811 :if getqflist({'id' : qfid}).id == qfid 812 813 " get the index of the current quickfix list in the stack 814 :let qfnum = getqflist({'nr' : 0}).nr 815 816 " get the items of a quickfix list specified by an identifier 817 :echo getqflist({'id' : qfid, 'items' : 0}).items 818 819 " get the number of entries in a quickfix list specified by an id 820 :echo getqflist({'id' : qfid, 'size' : 0}).size 821 822 " get the context of the third quickfix list in the stack 823 :echo getqflist({'nr' : 3, 'context' : 0}).context 824 825 " get the number of quickfix lists in the stack 826 :echo getqflist({'nr' : '$'}).nr 827 828 " get the number of times the current quickfix list is changed 829 :echo getqflist({'changedtick' : 0}).changedtick 830 831 " get the current entry in a quickfix list specified by an identifier 832 :echo getqflist({'id' : qfid, 'idx' : 0}).idx 833 834 " get all the quickfix list attributes using an identifier 835 :echo getqflist({'id' : qfid, 'all' : 0}) 836 837 " parse text from a List of lines and return a quickfix list 838 :let myList = ["a.java:10:L10", "b.java:20:L20"] 839 :echo getqflist({'lines' : myList}).items 840 841 " parse text using a custom 'efm' and return a quickfix list 842 :echo getqflist({'lines' : ['a.c#10#Line 10'], 'efm':'%f#%l#%m'}).items 843 844 " get the quickfix list window id 845 :echo getqflist({'winid' : 0}).winid 846 847 " get the quickfix list window buffer number 848 :echo getqflist({'qfbufnr' : 0}).qfbufnr 849 850 " get the context of the current location list 851 :echo getloclist(0, {'context' : 0}).context 852 853 " get the location list window id of the third window 854 :echo getloclist(3, {'winid' : 0}).winid 855 856 " get the location list window buffer number of the third window 857 :echo getloclist(3, {'qfbufnr' : 0}).qfbufnr 858 859 " get the file window id of a location list window (winnr: 4) 860 :echo getloclist(4, {'filewinid' : 0}).filewinid 861 < 862 *setqflist-examples* 863 The |setqflist()| and |setloclist()| functions can be used to set the various 864 attributes of a quickfix and location list respectively. Some examples for 865 using these functions are below: 866 > 867 " create an empty quickfix list with a title and a context 868 :let t = 'Search results' 869 :let c = {'cmd' : 'grep'} 870 :call setqflist([], ' ', {'title' : t, 'context' : c}) 871 872 " set the title of the current quickfix list 873 :call setqflist([], 'a', {'title' : 'Mytitle'}) 874 875 " change the current entry in the list specified by an identifier 876 :call setqflist([], 'a', {'id' : qfid, 'idx' : 10}) 877 878 " set the context of a quickfix list specified by an identifier 879 :call setqflist([], 'a', {'id' : qfid, 'context' : {'val' : 100}}) 880 881 " create a new quickfix list from a command output 882 :call setqflist([], ' ', {'lines' : systemlist('grep -Hn main *.c')}) 883 884 " parse text using a custom efm and add to a particular quickfix list 885 :call setqflist([], 'a', {'id' : qfid, 886 \ 'lines' : ["a.c#10#L10", "b.c#20#L20"], 'efm':'%f#%l#%m'}) 887 888 " add items to the quickfix list specified by an identifier 889 :let newItems = [{'filename' : 'a.txt', 'lnum' : 10, 'text' : "Apple"}, 890 \ {'filename' : 'b.txt', 'lnum' : 20, 'text' : "Orange"}] 891 :call setqflist([], 'a', {'id' : qfid, 'items' : newItems}) 892 893 " empty a quickfix list specified by an identifier 894 :call setqflist([], 'r', {'id' : qfid, 'items' : []}) 895 896 " free all the quickfix lists in the stack 897 :call setqflist([], 'f') 898 899 " set the title of the fourth quickfix list 900 :call setqflist([], 'a', {'nr' : 4, 'title' : 'SomeTitle'}) 901 902 " create a new quickfix list at the end of the stack 903 :call setqflist([], ' ', {'nr' : '$', 904 \ 'lines' : systemlist('grep -Hn class *.java')}) 905 906 " create a new location list from a command output 907 :call setloclist(0, [], ' ', {'lines' : systemlist('grep -Hn main *.c')}) 908 909 " replace the location list entries for the third window 910 :call setloclist(3, [], 'r', {'items' : newItems}) 911 < 912 ============================================================================= 913 3. Using more than one list of errors *quickfix-error-lists* 914 915 So far it has been assumed that there is only one list of errors. Actually 916 there can be multiple used lists that are remembered; see 'chistory' and 917 'lhistory'. 918 When starting a new list, the previous ones are automatically kept. Two 919 commands can be used to access older error lists. They set one of the 920 existing error lists as the current one. 921 922 *:colder* *:col* *E380* 923 :col[der] [count] Go to older error list. When [count] is given, do 924 this [count] times. When already at the oldest error 925 list, an error message is given. 926 927 *:lolder* *:lol* 928 :lol[der] [count] Same as `:colder`, except use the location list for 929 the current window instead of the quickfix list. 930 931 *:cnewer* *:cnew* *E381* 932 :cnew[er] [count] Go to newer error list. When [count] is given, do 933 this [count] times. When already at the newest error 934 list, an error message is given. 935 936 *:lnewer* *:lnew* 937 :lnew[er] [count] Same as `:cnewer`, except use the location list for 938 the current window instead of the quickfix list. 939 940 *:chistory* *:chi* 941 :[count]chi[story] Show the list of error lists. The current list is 942 marked with ">". The output looks like: 943 error list 1 of 3; 43 errors :make ~ 944 > error list 2 of 3; 0 errors :helpgrep tag ~ 945 error list 3 of 3; 15 errors :grep ex_help *.c ~ 946 947 When [count] is given, then the count'th quickfix 948 list is made the current list. Example: > 949 " Make the 4th quickfix list current 950 :4chistory 951 < 952 *:lhistory* *:lhi* 953 :[count]lhi[story] Show the list of location lists, otherwise like 954 `:chistory`. 955 956 When adding a new error list, it becomes the current list. 957 958 When ":colder" has been used and ":make" or ":grep" is used to add a new error 959 list, one newer list is overwritten. This is especially useful if you are 960 browsing with ":grep" |grep|. If you want to keep the more recent error 961 lists, use ":cnewer 99" first. 962 963 To get the number of lists in the quickfix and location list stack, you can 964 use the |getqflist()| and |getloclist()| functions respectively with the list 965 number set to the special value '$'. Examples: > 966 echo getqflist({'nr' : '$'}).nr 967 echo getloclist(3, {'nr' : '$'}).nr 968 To get the number of the current list in the stack: > 969 echo getqflist({'nr' : 0}).nr 970 < 971 ============================================================================= 972 4. Using :make *:make_makeprg* 973 974 *:mak* *:make* 975 :mak[e][!] [arguments] 1. All relevant |QuickFixCmdPre| autocommands are 976 executed. 977 2. If the 'autowrite' option is on, write any changed 978 buffers 979 3. An errorfile name is made from 'makeef'. If 980 'makeef' doesn't contain "##", and a file with this 981 name already exists, it is deleted. 982 4. The program given with the 'makeprg' option is 983 started (default "make") with the optional 984 [arguments] and the output is saved in the 985 errorfile (for Unix it is also echoed on the 986 screen). 987 5. The errorfile is read using 'errorformat'. 988 6. All relevant |QuickFixCmdPost| autocommands are 989 executed. See example below. 990 7. If [!] is not given the first error is jumped to. 991 8. The errorfile is deleted. 992 9. You can now move through the errors with commands 993 like |:cnext| and |:cprevious|, see above. 994 This command does not accept a comment, any " 995 characters are considered part of the arguments. 996 If the encoding of the program output differs from the 997 'encoding' option, you can use the 'makeencoding' 998 option to specify the encoding. 999 1000 *:lmak* *:lmake* 1001 :lmak[e][!] [arguments] 1002 Same as ":make", except the location list for the 1003 current window is used instead of the quickfix list. 1004 1005 In short, `:make` runs 'makeprg', reads its output using 'errorformat', 1006 optionally jumps to the first recognized error, and then removes the temporary 1007 error file used by the normal `:make` workflow. If 'shellpipe' is empty, or 1008 if the program manages its own output file, this cleanup does not apply to 1009 that program's file. Use |:cnext| and related commands to move through the 1010 resulting list. 1011 1012 The ":make" command executes the command given with the 'makeprg' option. 1013 This is done by passing the command to the shell given with the 'shell' 1014 option. This works almost like typing 1015 1016 ":!{makeprg} [arguments] {shellpipe} {errorfile}". 1017 1018 {makeprg} is the string given with the 'makeprg' option. Any command can be 1019 used, not just "make". Characters '%' and '#' are expanded as usual on a 1020 command-line. You can use "%<" to insert the current file name without 1021 extension, or "#<" to insert the alternate file name without extension, for 1022 example: > 1023 :set makeprg=make\ #<.o 1024 1025 [arguments] is anything that is typed after ":make". 1026 {shellpipe} is the 'shellpipe' option. 1027 {errorfile} is the 'makeef' option, with ## replaced to make it unique. 1028 1029 The placeholder "$*" can be used for the argument list in {makeprg} if the 1030 command needs some additional characters after its arguments. The $* is 1031 replaced then by all arguments. Example: > 1032 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*} 1033 or simpler > 1034 :let &mp = 'latex \\nonstopmode \\input\{$*}' 1035 "$*" can be given multiple times, for example: > 1036 :set makeprg=gcc\ -o\ $*\ $* 1037 1038 The 'shellpipe' option defaults to ">" for the Amiga and ">%s 2>&1" for Win32. 1039 This means that the output of the compiler is saved in a file and not shown on 1040 the screen directly. For Unix "| tee" is used. The compiler output is shown 1041 on the screen and saved in a file the same time. Depending on the shell used 1042 "|& tee" or "2>&1| tee" is the default, so stderr output will be included. 1043 1044 If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful 1045 for compilers that write to an errorfile themselves (e.g., Manx's Amiga C). 1046 1047 1048 Using QuickFixCmdPost to fix the encoding ~ 1049 1050 It may be that 'encoding' is set to an encoding that differs from the messages 1051 your build program produces. This example shows how to fix this after Vim has 1052 read the error messages: > 1053 1054 function QfMakeConv() 1055 let qflist = getqflist() 1056 for i in qflist 1057 let i.text = iconv(i.text, "cp936", "utf-8") 1058 endfor 1059 call setqflist(qflist) 1060 endfunction 1061 1062 au QuickFixCmdPost make call QfMakeConv() 1063 1064 (Example by Faque Cheng) 1065 Another option is using 'makeencoding'. 1066 1067 ============================================================================== 1068 5. Using :vimgrep and :grep *grep* *lid* 1069 1070 Vim has two ways to find matches for a pattern: internal and external. The 1071 advantage of the internal grep is that it works on all systems and uses the 1072 powerful Vim search patterns. An external grep program can be used when the 1073 Vim grep does not do what you want. 1074 1075 The internal method will be slower, because files are read into memory. For 1076 large projects, consider using |:grep| with an external search program. The 1077 advantages of the internal method are: 1078 - Line separators and encoding are automatically recognized, as if a file is 1079 being edited. 1080 - Uses Vim search patterns. Multi-line patterns can be used. 1081 - When plugins are enabled: compressed and remote files can be searched. 1082 |gzip| |netrw| 1083 1084 To be able to do this Vim loads each file as if it is being edited. When 1085 there is no match in the file the associated buffer is wiped out again. The 1086 'hidden' option is ignored here to avoid running out of memory or file 1087 descriptors when searching many files. However, when the |:hide| command 1088 modifier is used the buffers are kept loaded. This makes following searches 1089 in the same files a lot faster. 1090 1091 Note that |:copen| (or |:lopen| for |:lgrep|) may be used to open a buffer 1092 containing the search results in linked form. The |:silent| command may be 1093 used to suppress the default full screen grep output. The ":grep!" form of 1094 the |:grep| command doesn't jump to the first match automatically. These 1095 commands can be combined to create a NewGrep command: > 1096 1097 command! -nargs=+ NewGrep execute 'silent grep! <args>' | copen 42 1098 1099 1100 5.1 Using Vim's internal grep 1101 1102 *:vim* *:vimgrep* *E682* *E683* 1103 :vim[grep][!] /{pattern}/[g][j][f] {file} ... 1104 Search for {pattern} in the files {file} ... and set 1105 the error list to the matches. Files matching 1106 'wildignore' are ignored; files in 'suffixes' are 1107 searched last. 1108 1109 {pattern} is a Vim search pattern. Instead of 1110 enclosing it in / any non-ID character (see 1111 'isident') can be used, so long as it does not appear 1112 in {pattern}. 1113 'ignorecase' applies. To overrule it put |/\c| in the 1114 pattern to ignore case or |/\C| to match case. 1115 'smartcase' is not used. 1116 If {pattern} is empty (e.g. // is specified), the last 1117 used search pattern is used. |last-pattern| 1118 1119 Flags: 1120 'g' Without the 'g' flag each line is added only 1121 once. With 'g' every match is added. 1122 1123 'j' Without the 'j' flag Vim jumps to the first 1124 match. With 'j' only the quickfix list is 1125 updated. With the [!] any changes in the current 1126 buffer are abandoned. 1127 1128 'f' When the 'f' flag is specified, fuzzy string 1129 matching is used to find matching lines. The 1130 characters in {pattern} must appear in order, but 1131 need not be next to each other. In this case, 1132 {pattern} is treated as a literal string instead 1133 of a regular expression. See |fuzzy-matching| 1134 for more information about fuzzy matching 1135 strings. 1136 1137 |QuickFixCmdPre| and |QuickFixCmdPost| are triggered. 1138 A file that is opened for matching may use a buffer 1139 number, but it is reused if possible to avoid 1140 consuming buffer numbers. 1141 1142 :{count}vim[grep] ... 1143 When a number is put before the command this is used 1144 as the maximum number of matches to find. Use 1145 ":1vimgrep pattern file" to find only the first. 1146 Useful if you only want to check if there is a match 1147 and quit quickly when it's found. 1148 1149 Every second or so the searched file name is displayed 1150 to give you an idea of the progress made. 1151 Examples: > 1152 :vimgrep /an error/ *.c 1153 :vimgrep /\<FileName\>/ *.h include/* 1154 :vimgrep /myfunc/ **/*.c 1155 < For the use of "**" see |starstar-wildcard|. 1156 1157 :vim[grep][!] {pattern} {file} ... 1158 Like above, but instead of enclosing the pattern in a 1159 non-ID character use a white space separated pattern. 1160 The pattern must start with an ID character. 1161 Example: > 1162 :vimgrep Error *.c 1163 < 1164 *:lv* *:lvimgrep* 1165 :lv[imgrep][!] /{pattern}/[g][j][f] {file} ... 1166 :lv[imgrep][!] {pattern} {file} ... 1167 Same as ":vimgrep", except the location list for the 1168 current window is used instead of the quickfix list. 1169 1170 *:vimgrepa* *:vimgrepadd* 1171 :vimgrepa[dd][!] /{pattern}/[g][j][f] {file} ... 1172 :vimgrepa[dd][!] {pattern} {file} ... 1173 Just like ":vimgrep", but instead of making a new list 1174 of errors the matches are appended to the current 1175 list. 1176 1177 *:lvimgrepa* *:lvimgrepadd* 1178 :lvimgrepa[dd][!] /{pattern}/[g][j][f] {file} ... 1179 :lvimgrepa[dd][!] {pattern} {file} ... 1180 Same as ":vimgrepadd", except the location list for 1181 the current window is used instead of the quickfix 1182 list. 1183 1184 5.2 External grep 1185 1186 Vim can interface with "grep" and grep-like programs (such as the GNU 1187 id-utils) in a similar way to its compiler integration (see |:make| above). 1188 1189 [Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where 1190 "re" stands for Regular Expression.] 1191 1192 *:gr* *:grep* 1193 :gr[ep][!] [arguments] Just like ":make", but use 'grepprg' instead of 1194 'makeprg' and 'grepformat' instead of 'errorformat'. 1195 When 'grepprg' is "internal" this works like 1196 |:vimgrep|. Note that the pattern needs to be 1197 enclosed in separator characters then. 1198 If the encoding of the program output differs from the 1199 'encoding' option, you can use the 'makeencoding' 1200 option to specify the encoding. 1201 1202 *:lgr* *:lgrep* 1203 :lgr[ep][!] [arguments] Same as ":grep", except the location list for the 1204 current window is used instead of the quickfix list. 1205 1206 *:grepa* *:grepadd* 1207 :grepa[dd][!] [arguments] 1208 Just like ":grep", but instead of making a new list of 1209 errors the matches are appended to the current list. 1210 Example: > 1211 :call setqflist([]) 1212 :bufdo grepadd! something % 1213 < The first command makes a new error list which is 1214 empty. The second command executes "grepadd" for each 1215 listed buffer. Note the use of ! to avoid that 1216 ":grepadd" jumps to the first error, which is not 1217 allowed with |:bufdo|. 1218 An example that uses the argument list and avoids 1219 errors for files without matches: > 1220 :silent argdo try 1221 \ | grepadd! something % 1222 \ | catch /E480:/ 1223 \ | endtry" 1224 < 1225 If the encoding of the program output differs from the 1226 'encoding' option, you can use the 'makeencoding' 1227 option to specify the encoding. 1228 1229 *:lgrepa* *:lgrepadd* 1230 :lgrepa[dd][!] [arguments] 1231 Same as ":grepadd", except the location list for the 1232 current window is used instead of the quickfix list. 1233 1234 5.3 Setting up external grep 1235 1236 If you have a standard "grep" program installed, the :grep command may work 1237 well with the defaults. The syntax is very similar to the standard command: > 1238 1239 :grep foo *.c 1240 1241 Will search all files with the .c extension for the substring "foo". The 1242 arguments to :grep are passed straight to the "grep" program, so you can use 1243 whatever options your "grep" supports. 1244 1245 By default, :grep invokes grep with the -n option (show file and line 1246 numbers). You can change this with the 'grepprg' option. You will need to 1247 set 'grepprg' if: 1248 1249 a) You are using a program that isn't called "grep" 1250 b) You have to call grep with a full path 1251 c) You want to pass other options automatically (e.g. case insensitive 1252 search.) 1253 1254 Once "grep" has executed, Vim parses the results using the 'grepformat' 1255 option. This option works in the same way as the 'errorformat' option - see 1256 that for details. You may need to change 'grepformat' from the default if 1257 your grep outputs in a non-standard format, or you are using some other 1258 program with a special format. 1259 1260 Once the results are parsed, Vim loads the first file containing a match and 1261 jumps to the appropriate line, in the same way that it jumps to a compiler 1262 error in |quickfix| mode. You can then use the |:cnext|, |:clist|, etc. 1263 commands to see the other matches. 1264 1265 1266 5.4 Using :grep with id-utils 1267 1268 You can set up :grep to work with the GNU id-utils like this: > 1269 1270 :set grepprg=lid\ -Rgrep\ -s 1271 :set grepformat=%f:%l:%m 1272 1273 then > 1274 :grep (regexp) 1275 1276 works just as you'd expect. 1277 (provided you remembered to mkid first :) 1278 1279 1280 5.5 Browsing source code with :vimgrep or :grep 1281 1282 Using the stack of error lists that Vim keeps, you can browse your files to 1283 look for functions and the functions they call. For example, suppose that you 1284 have to add an argument to the read_file() function. You enter this command: > 1285 1286 :vimgrep /\<read_file\>/ *.c 1287 1288 You use ":cn" to go along the list of matches and add the argument. At one 1289 place you have to get the new argument from a higher level function msg(), and 1290 need to change that one too. Thus you use: > 1291 1292 :vimgrep /\<msg\>/ *.c 1293 1294 While changing the msg() functions, you find another function that needs to 1295 get the argument from a higher level. You can again use ":vimgrep" to find 1296 these functions. Once you are finished with one function, you can use > 1297 1298 :colder 1299 1300 to go back to the previous one. 1301 1302 This works like browsing a tree: ":vimgrep" goes one level deeper, creating a 1303 list of branches. ":colder" goes back to the previous level. You can mix 1304 this use of ":vimgrep" and "colder" to browse all the locations in a tree-like 1305 way. If you do this consistently, you will find all locations without the 1306 need to write down a "todo" list. 1307 1308 ============================================================================= 1309 6. Selecting a compiler *compiler-select* 1310 1311 *:comp* *:compiler* *E666* 1312 :comp[iler][!] {name} Set options to work with compiler {name}. 1313 Without the "!" options are set for the 1314 current buffer. With "!" global options are 1315 set. 1316 If you use ":compiler foo" in "file.foo" and 1317 then ":compiler! bar" in another buffer, Vim 1318 will keep on using "foo" in "file.foo". 1319 {not available when compiled without the 1320 |+eval| feature} 1321 1322 1323 The Vim plugins in the "compiler" directory will set options to use the 1324 selected compiler. For `:compiler` local options are set, for `:compiler!` 1325 global options. 1326 1327 In normal use, select a compiler with `:compiler {name}` and then run |:make|. 1328 The compiler plugin usually sets 'makeprg' and 'errorformat' so Vim can run 1329 the compiler and read its messages. The descriptions below document options 1330 for particular compiler plugins. 1331 1332 The values set by a compiler plugin can be changed afterwards with |:set| or 1333 |:setlocal|. `:compiler {name}` sets options for the current buffer, while 1334 `:compiler! {name}` sets global options; a buffer-local value takes precedence 1335 over a global value. 1336 1337 *current_compiler* 1338 To support older Vim versions, the plugins always use "current_compiler" and 1339 not "b:current_compiler". What the command actually does is the following: 1340 1341 - Delete the "current_compiler" and "b:current_compiler" variables. 1342 - Define the "CompilerSet" user command. With "!" it does ":set", without "!" 1343 it does ":setlocal". 1344 - Execute ":runtime! compiler/{name}.vim". The plugins are expected to set 1345 options with "CompilerSet" and set the "current_compiler" variable to the 1346 name of the compiler. 1347 - Delete the "CompilerSet" user command. 1348 - Set "b:current_compiler" to the value of "current_compiler". 1349 - Without "!" the old value of "current_compiler" is restored. 1350 1351 1352 For writing a compiler plugin, see |write-compiler-plugin|. 1353 1354 Use the |compiler-make| plugin to undo the effect of a compiler plugin. 1355 1356 BIOME *compiler-biome* *quickfix-biome* 1357 1358 Biome check lints JavaScript, TypeScript, JSX, TSX, JSON, JSONC, HTML, Vue, 1359 Svelte, Astro, CSS, GraphQL and GritQL files. 1360 1361 Commonly used compiler options can be added to 'makeprg' by setting the 1362 b/g:biome_makeprg_params variable. For example (global default is ""): > 1363 1364 let b:biome_makeprg_params = "--diagnostic-level=error --staged" 1365 1366 1367 CPPCHECK *quickfix-cppcheck* *compiler-cppcheck* 1368 1369 Use g/b:`c_cppcheck_params` to set cppcheck parameters. The global 1370 settings by default include 1371 1372 - `--verbose`: Enables verbose output. 1373 - `--force`: Forces checking of all configurations. 1374 - `--inline-suppr`: Allows inline suppressions. 1375 - `--enable=...`: Enables specific checks like warnings, style, performance, 1376 portability, information, and missing includes. 1377 - `-j`: Utilizes multiple processors if available, determined by the 1378 `getconf` command if available (requires omitting the unusedFunction check) 1379 1380 For C++ files (`filetype == 'cpp'`), the `--language=c++` option is added to 1381 ensure Cppcheck treats the file as C++. 1382 1383 If compile_commands.json is present in the current directory, it is added as a 1384 `--project` parameter to the command line. Otherwise, by default the 1385 directories in &path are passed as include directories. These can be set by 1386 g/b:`c_cppcheck_includes` as a list of `-I` flags. Tim Pope's vim-apathy 1387 plug-in [0] can expand &path. To also append the folders in a git repo use > 1388 1389 let &l:path = join(systemlist('git ls-tree -d --name-only -r HEAD'), ',') 1390 1391 [0] https://github.com/tpope/vim-apathy 1392 1393 DOTNET *compiler-dotnet* 1394 1395 The .NET CLI compiler outputs both errors and warnings by default. The output 1396 may be limited to include only errors, by setting the g:dotnet_errors_only 1397 variable to |v:true|. 1398 1399 The associated project name is included in each error and warning. To 1400 suppress the project name, set the g:dotnet_show_project_file variable to 1401 |v:false|. 1402 1403 Example: limit output to only display errors, and suppress the project name: > 1404 let dotnet_errors_only = v:true 1405 let dotnet_show_project_file = v:false 1406 compiler dotnet 1407 < 1408 GCC *quickfix-gcc* *compiler-gcc* 1409 1410 There's one variable you can set for the GCC compiler: 1411 1412 g:compiler_gcc_ignore_unmatched_lines 1413 Ignore lines that don't match any patterns 1414 defined for GCC. Useful if output from 1415 commands run from make are generating false 1416 positives. 1417 1418 JAVAC *compiler-javac* 1419 1420 Commonly used compiler options can be added to 'makeprg' by setting the 1421 b/g:javac_makeprg_params variable. For example: > 1422 1423 let g:javac_makeprg_params = "-Xlint:all -encoding utf-8" 1424 1425 MAVEN *compiler-maven* 1426 1427 Commonly used compiler options can be added to 'makeprg' by setting the 1428 b/g:maven_makeprg_params variable. For example: > 1429 1430 let g:maven_makeprg_params = "-DskipTests -U -X" 1431 1432 SPOTBUGS *compiler-spotbugs* 1433 1434 SpotBugs is a static analysis tool that can be used to find bugs in Java. 1435 It scans the Java bytecode of all classes in the currently open buffer. 1436 (Therefore, `:compiler! spotbugs` is not supported.) 1437 1438 Commonly used compiler options can be added to 'makeprg' by setting the 1439 "b:" or "g:spotbugs_makeprg_params" variable. For example: >vim 1440 1441 let b:spotbugs_makeprg_params = "-longBugCodes -effort:max -low" 1442 1443 The global default is "-workHard -experimental". 1444 1445 By default, the class files are searched in the directory where the source 1446 files are placed. However, typical Java projects use distinct directories 1447 for source files and class files. To make both known to SpotBugs, assign 1448 their paths (distinct and relative to their common root directory) to the 1449 following properties (using the example of a common Maven project): >vim 1450 1451 let g:spotbugs_properties = { 1452 \ 'sourceDirPath': ['src/main/java'], 1453 \ 'classDirPath': ['target/classes'], 1454 \ 'testSourceDirPath': ['src/test/java'], 1455 \ 'testClassDirPath': ['target/test-classes'], 1456 \ } 1457 1458 Note that source and class path entries are expected to come in pairs: define 1459 both "sourceDirPath" and "classDirPath" when you are considering at least one, 1460 and apply the same logic to "testSourceDirPath" and "testClassDirPath". 1461 Note that values for the path keys describe only for SpotBugs where to look 1462 for files; refer to the documentation for particular compiler plugins for more 1463 information. 1464 1465 The default pre- and post-compiler actions are provided for Ant, Maven, and 1466 Javac compiler plugins and can be selected by assigning the name of a compiler 1467 plugin (`ant`, `maven`, or `javac`) to the "compiler" key: >vim 1468 1469 let g:spotbugs_properties = { 1470 \ 'compiler': 'maven', 1471 \ } 1472 1473 This single setting is essentially equivalent to all the settings below, with 1474 the exception made for the "PreCompilerAction" and "PreCompilerTestAction" 1475 values: their listed |Funcref|s will obtain no-op implementations whereas the 1476 implicit Funcrefs of the "compiler" key will obtain the requested defaults if 1477 available. >vim 1478 1479 let g:spotbugs_properties = { 1480 \ 'PreCompilerAction': 1481 \ function('spotbugs#DefaultPreCompilerAction'), 1482 \ 'PreCompilerTestAction': 1483 \ function('spotbugs#DefaultPreCompilerTestAction'), 1484 \ 'PostCompilerAction': 1485 \ function('spotbugs#DefaultPostCompilerAction'), 1486 \ 'sourceDirPath': ['src/main/java'], 1487 \ 'classDirPath': ['target/classes'], 1488 \ 'testSourceDirPath': ['src/test/java'], 1489 \ 'testClassDirPath': ['target/test-classes'], 1490 \ } 1491 1492 With default actions, the compiler of choice will attempt to rebuild the class 1493 files for the buffer (and possibly for the whole project) as soon as a Java 1494 syntax file is loaded; then, `spotbugs` will attempt to analyze the quality of 1495 the compilation unit of the buffer. 1496 1497 Vim commands proficient in 'makeprg' [0] can be composed with default actions. 1498 Begin by considering which of the supported keys, "DefaultPreCompilerCommand", 1499 "DefaultPreCompilerTestCommand", or "DefaultPostCompilerCommand", you need to 1500 write an implementation for, observing that each of these keys corresponds to 1501 a particular "*Action" key. Follow it by defining a new function that always 1502 declares an only parameter of type string and puts to use a command equivalent 1503 of |:make|, and assigning its |Funcref| to the selected key. For example: 1504 >vim 1505 function! GenericPostCompilerCommand(arguments) abort 1506 execute 'make ' .. a:arguments 1507 endfunction 1508 1509 let g:spotbugs_properties = { 1510 \ 'DefaultPostCompilerCommand': 1511 \ function('GenericPostCompilerCommand'), 1512 \ } 1513 1514 When "PostCompilerAction" is available, "PostCompilerActionExecutor" is also 1515 supported. Its value must be a Funcref pointing to a function that always 1516 declares a single parameter of type string and decides whether |:execute| can 1517 be dispatched on its argument, containing a pending post-compiler action, 1518 after ascertaining the current status of |:cc| (or |:ll|): >vim 1519 1520 function! GenericPostCompilerActionExecutor(action) abort 1521 try 1522 cc 1523 catch /\<E42:/ 1524 execute a:action 1525 endtry 1526 endfunction 1527 1528 Complementary, some or all of the available "Pre*Action"s (or "*Pre*Command"s) 1529 may run `:doautocmd java_spotbugs_post User` in their implementations before 1530 |:make| (or its equivalent) to define a once-only |ShellCmdPost| `:autocmd` 1531 that will arrange for "PostCompilerActionExecutor" to be invoked; and then run 1532 `:doautocmd java_spotbugs_post ShellCmdPost` to consume this event: >vim 1533 1534 function! GenericPreCompilerCommand(arguments) abort 1535 if !exists('g:spotbugs_compilation_done') 1536 doautocmd java_spotbugs_post User 1537 execute 'make ' .. a:arguments 1538 " only run doautocmd when :make was synchronous 1539 " see note below 1540 doautocmd java_spotbugs_post ShellCmdPost " XXX: (a) 1541 let g:spotbugs_compilation_done = 1 1542 else 1543 cc 1544 endif 1545 endfunction 1546 1547 function! GenericPreCompilerTestCommand(arguments) abort 1548 if !exists('g:spotbugs_test_compilation_done') 1549 doautocmd java_spotbugs_post User 1550 execute 'make ' .. a:arguments 1551 " only run doautocmd when :make was synchronous 1552 " see note below 1553 doautocmd java_spotbugs_post ShellCmdPost " XXX: (b) 1554 let g:spotbugs_test_compilation_done = 1 1555 else 1556 cc 1557 endif 1558 endfunction 1559 1560 let g:spotbugs_properties = { 1561 \ 'compiler': 'maven', 1562 \ 'DefaultPreCompilerCommand': 1563 \ function('GenericPreCompilerCommand'), 1564 \ 'DefaultPreCompilerTestCommand': 1565 \ function('GenericPreCompilerTestCommand'), 1566 \ 'PostCompilerActionExecutor': 1567 \ function('GenericPostCompilerActionExecutor'), 1568 \ } 1569 1570 If a command equivalent of `:make` is capable of asynchronous execution and 1571 consuming `ShellCmdPost` events, `:doautocmd java_spotbugs_post ShellCmdPost` 1572 must be removed from such "*Action" (or "*Command") implementations (i.e. the 1573 lines `(a)` and `(b)` in the listed examples) to retain a sequential order for 1574 non-blocking execution, and any notification (see below) must be suppressed. 1575 A `ShellCmdPost` `:autocmd` can be associated with any |:augroup| by assigning 1576 its name to the "augroupForPostCompilerAction" key. 1577 1578 When default actions are not suited to a desired workflow, proceed by writing 1579 arbitrary functions yourself and matching their Funcrefs to the supported 1580 keys: "PreCompilerAction", "PreCompilerTestAction", and "PostCompilerAction". 1581 1582 The next example re-implements the default pre-compiler actions for a Maven 1583 project and requests other default Maven settings with the "compiler" entry: 1584 >vim 1585 function! MavenPreCompilerAction() abort 1586 call spotbugs#DeleteClassFiles() 1587 compiler maven 1588 make compile 1589 cc 1590 endfunction 1591 1592 function! MavenPreCompilerTestAction() abort 1593 call spotbugs#DeleteClassFiles() 1594 compiler maven 1595 make test-compile 1596 cc 1597 endfunction 1598 1599 let g:spotbugs_properties = { 1600 \ 'compiler': 'maven', 1601 \ 'PreCompilerAction': 1602 \ function('MavenPreCompilerAction'), 1603 \ 'PreCompilerTestAction': 1604 \ function('MavenPreCompilerTestAction'), 1605 \ } 1606 1607 Note that all entered custom settings will take precedence over the matching 1608 default settings in "g:spotbugs_properties". 1609 Note that it is necessary to notify the plugin of the result of a pre-compiler 1610 action before further work can be undertaken. Using |:cc| after |:make| (or 1611 |:ll| after |:lmake|) as the last command of an action is the supported means 1612 of such communication. 1613 1614 Two commands, "SpotBugsRemoveBufferAutocmd" and "SpotBugsDefineBufferAutocmd", 1615 are provided to toggle actions for buffer-local autocommands. For example, to 1616 also run actions on any |BufWritePost| and |SigUSR1| event, add these lines to 1617 `~/.vim/after/ftplugin/java.vim`: >vim 1618 1619 if exists(':SpotBugsDefineBufferAutocmd') == 2 1620 SpotBugsDefineBufferAutocmd BufWritePost SigUSR1 1621 endif 1622 1623 Otherwise, you can turn to `:doautocmd java_spotbugs User` at any time. 1624 1625 The "g:spotbugs_properties" variable is consulted by the Java filetype plugin 1626 (|ft-java-plugin|) to arrange for the described automation, and, therefore, it 1627 must be defined before |FileType| events can take place for the buffers loaded 1628 with Java source files. It could, for example, be set in a project-local 1629 |vimrc| loaded by [1]. 1630 1631 Both "g:spotbugs_properties" and "b:spotbugs_properties" are recognized and 1632 must be modifiable (|:unlockvar|). The "*Command" entries are always treated 1633 as global functions to be shared among all Java buffers. 1634 1635 The SpotBugs Java library and, by extension, its distributed shell scripts do 1636 not support in the `-textui` mode listed pathnames with directory filenames 1637 that contain blank characters [2]. To work around this limitation, consider 1638 making a symbolic link to such a directory from a directory that does not have 1639 blank characters in its name and passing this information to SpotBugs: >vim 1640 1641 let g:spotbugs_alternative_path = { 1642 \ 'fromPath': 'path/to/dir_without_blanks', 1643 \ 'toPath': 'path/to/dir with blanks', 1644 \ } 1645 1646 [0] https://github.com/Konfekt/vim-compilers 1647 [1] https://github.com/MarcWeber/vim-addon-local-vimrc 1648 [2] https://github.com/spotbugs/spotbugs/issues/909 1649 1650 GNU MAKE *compiler-make* 1651 1652 Since the default make program is "make", the compiler plugin for make, 1653 :compiler make, will reset the 'makeprg' and 'errorformat' option to 1654 the default values and unlet any variables that may have been set by a 1655 previous compiler plugin. 1656 1657 MANX AZTEC C *quickfix-manx* *compiler-manx* 1658 1659 To use Vim with Manx's Aztec C compiler on the Amiga you should do the 1660 following: 1661 - Set the CCEDIT environment variable with the command: > 1662 mset "CCEDIT=vim -q" 1663 - Compile with the -qf option. If the compiler finds any errors, Vim is 1664 started and the cursor is positioned on the first error. The error message 1665 will be displayed on the last line. You can go to other errors with the 1666 commands mentioned above. You can fix the errors and write the file(s). 1667 - If you exit Vim normally the compiler will re-compile the same file. If you 1668 exit with the :cq command, the compiler will terminate. Do this if you 1669 cannot fix the error, or if another file needs to be compiled first. 1670 1671 There are some restrictions to the Quickfix mode on the Amiga. The 1672 compiler only writes the first 25 errors to the errorfile (Manx's 1673 documentation does not say how to get more). If you want to find the others, 1674 you will have to fix a few errors and exit the editor. After recompiling, 1675 up to 25 remaining errors will be found. 1676 1677 If Vim was started from the compiler, the :sh and some :! commands will not 1678 work, because Vim is then running in the same process as the compiler and 1679 stdin (standard input) will not be interactive. 1680 1681 GROFF *quickfix-groff* *compiler-groff* 1682 1683 The GROFF compiler plugin uses the mom macro set (documented in the groff_mom 1684 manpage) as input and expects that the output file type extension is passed to 1685 make, say :make html or :make pdf. 1686 1687 Additional arguments can be passed to groff by setting them in 1688 `b:groff_compiler_args` or `g:groff_compiler_args`. The `language` argument 1689 passed to groff is set using 'spelllang'; it can be overridden by setting 1690 `b:groff_compiler_lang`. The default encoding is `UTF-8` and can be changed 1691 by setting `b:groff_compiler_encoding` or `g:groff_compiler_encoding`. 1692 1693 PANDOC *quickfix-pandoc* *compiler-pandoc* 1694 1695 The Pandoc compiler plugin expects that an output file type extension is 1696 passed to make, say :make html or :make pdf. 1697 1698 Additional arguments can be passed to pandoc: 1699 1700 - either by appending them to make, say `:make html --self-contained` . 1701 - or setting them in `b:pandoc_compiler_args` or `g:pandoc_compiler_args`. 1702 1703 The `--from` argument is an educated guess using the buffer file type; 1704 it can be overridden by setting `b:pandoc_compiler_from`. 1705 The `--metadata lang` argument is set using 'spelllang'; 1706 If `--from=markdown` is assumed and no title set in a title header or 1707 YAML block, then the filename (without extension) is used as the title. 1708 1709 PERL *quickfix-perl* *compiler-perl* 1710 1711 The Perl compiler plugin doesn't actually compile, but invokes Perl's internal 1712 syntax checking feature and parses the output for possible errors so you can 1713 correct them in quick-fix mode. 1714 1715 Warnings are forced regardless of "no warnings" or "$^W = 0" within the file 1716 being checked. To disable this set g:perl_compiler_force_warnings to a zero 1717 value. For example: > 1718 let g:perl_compiler_force_warnings = 0 1719 1720 MYPY TYPE CHECKER *compiler-mypy* 1721 1722 Commonly used compiler options can be added to 'makeprg' by setting the 1723 b/g:mypy_makeprg_params variable. For example: > 1724 1725 let b:mypy_makeprg_params = "--warn-unused-ignores" 1726 1727 The global default is "--strict --ignore-missing-imports". 1728 1729 PYRIGHT TYPE CHECKER *compiler-pyright* 1730 1731 Commonly used compiler options can be added to 'makeprg' by setting the 1732 b/g:pyright_makeprg_params variable. 1733 1734 The global default is "pyright". 1735 1736 TY TYPE CHECKER *compiler-ty* 1737 1738 Commonly used compiler options and executable can be set by the 1739 b/g:ty_makeprg variable. For example: > 1740 1741 let b:ty_makeprg = "uv run ty" 1742 1743 The global default is "ty --no-progress --color=never". 1744 1745 RUFF LINTER *compiler-ruff* 1746 1747 Commonly used compiler options can be added to 'makeprg' by setting the 1748 b/g:ruff_makeprg_params variable. For example: > 1749 1750 let b:ruff_makeprg_params = "--max-line-length "..&textwidth 1751 1752 The global default is "--preview". 1753 1754 PYLINT LINTER *compiler-pylint* 1755 1756 Commonly used compiler options can be added to 'makeprg' by setting the 1757 b/g:pylint_makeprg_params variable. For example: > 1758 1759 let b:pylint_makeprg_params = "--max-line-length "..&textwidth 1760 1761 The global default is "--jobs=0" to use (almost) all cores. 1762 1763 PYUNIT COMPILER *compiler-pyunit* 1764 1765 This is not actually a compiler, but a unit testing framework for the 1766 Python language. It is included into standard Python distribution 1767 starting from version 2.0. For older versions, you can get it from 1768 http://pyunit.sourceforge.net. 1769 1770 When you run your tests with the help of the framework, possible errors 1771 are parsed by Vim and presented for you in quick-fix mode. 1772 1773 Unfortunately, there is no standard way to run the tests. 1774 The alltests.py script seems to be used quite often, that's all. 1775 Useful values for the 'makeprg' options therefore are: 1776 setlocal makeprg=./alltests.py " Run a testsuite 1777 setlocal makeprg=python\ %:S " Run a single testcase 1778 1779 PYTEST COMPILER *compiler-pytest* 1780 1781 Commonly used compiler options can be added to 'makeprg' by setting the 1782 b/g:pytest_makeprg_params variable. For example: > 1783 1784 let b:pytest_makeprg_params = "--verbose --no-summary --disable-warnings" 1785 1786 The global default is "--tb=short --quiet"; Python warnings are suppressed. 1787 1788 TEX COMPILER *compiler-tex* 1789 1790 Included in the distribution compiler for TeX ($VIMRUNTIME/compiler/tex.vim) 1791 uses make command if possible. If the compiler finds a file named "Makefile" 1792 or "makefile" in the current directory, it supposes that you want to process 1793 your *TeX files with make, and the makefile does the right work. In this case 1794 compiler sets 'errorformat' for *TeX output and leaves 'makeprg' untouched. 1795 If neither "Makefile" nor "makefile" is found, the compiler will not use make. 1796 You can force the compiler to ignore makefiles by defining 1797 b:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked for 1798 existence only). 1799 1800 If the compiler chose not to use make, it needs to choose a right program for 1801 processing your input. If b:tex_flavor or g:tex_flavor (in this precedence) 1802 variable exists, it defines TeX flavor for :make (actually, this is the name 1803 of executed command), and if both variables do not exist, it defaults to 1804 "latex". For example, while editing chapter2.tex \input-ed from mypaper.tex 1805 written in AMS-TeX: > 1806 1807 :let b:tex_flavor = 'amstex' 1808 :compiler tex 1809 < [editing...] > 1810 :make mypaper 1811 1812 Note that you must specify a name of the file to process as an argument (to 1813 process the right file when editing \input-ed or \include-ed file; portable 1814 solution for substituting % for no arguments is welcome). This is not in the 1815 semantics of make, where you specify a target, not source, but you may specify 1816 filename without extension ".tex" and mean this as "make filename.dvi or 1817 filename.pdf or filename.some_result_extension according to compiler". 1818 1819 Note: tex command line syntax is set to usable both for MikTeX (suggestion 1820 by Srinath Avadhanula) and teTeX (checked by Artem Chuprina). Suggestion 1821 from |errorformat-LaTeX| is too complex to keep it working for different 1822 shells and OSes and also does not allow to use other available TeX options, 1823 if any. If your TeX doesn't support "-interaction=nonstopmode", please 1824 report it with different means to express \nonstopmode from the command line. 1825 1826 TOMBI *quickfix-toml* *compiler-tombi* 1827 1828 The tombi compiler plugin does not compile. 1829 1830 It runs "tombi lint" and parses diagnostics into the quickfix list. 1831 1832 Color codes are stripped from the linter output to keep |errorformat| 1833 parsing reliable. This may require a working "sed" for old versions of the 1834 tombi linter. 1835 1836 TSC COMPILER *compiler-tsc* 1837 1838 The executable and compiler options can be added to 'makeprg' by setting the 1839 b/g:tsc_makeprg variable. For example: > 1840 1841 let b:tsc_makeprg = "npx tsc --noEmit" 1842 1843 TYPST COMPILER *compiler-typst* 1844 1845 Vim includes a compiler plugin for Typst files. This compiler is enabled 1846 automatically in Typst buffers by the Typst filetype plugin |ft-typst-plugin|. 1847 Run |:make| to compile the current Typst file. 1848 1849 *g:typst_cmd* 1850 By default Vim will use "typst" as the command to run the Typst compiler. 1851 This can be changed by setting the |g:typst_cmd| variable: > 1852 let g:typst_cmd = "/path/to/other/command" 1853 1854 ============================================================================= 1855 7. The error format *error-file-format* 1856 1857 *errorformat* *E372* *E373* *E374* 1858 *E375* *E376* *E377* *E378* 1859 The 'errorformat' option specifies patterns that Vim uses to read compiler 1860 output. A pattern can extract the file name, line number, column and message 1861 from each line. The first format that matches with an error message is used. 1862 You can add several formats for different messages your compiler produces, or 1863 even entries for multiple compilers. See |efm-entries|. 1864 1865 Each entry in 'errorformat' is a scanf-like string that describes the format. 1866 First, you need to know how scanf works. Look in the documentation of your 1867 C compiler. Below you find the % items that Vim understands. Others are 1868 invalid. 1869 1870 Quick start: Vim already includes formats for many common compilers. Check 1871 |errorformats| for an example before writing your own. If no example matches, 1872 start with the basic items below and adapt one of the examples as needed. 1873 1874 Special characters in 'errorformat' are comma and backslash. See 1875 |efm-entries| for how to deal with them. Note that a literal "%" is matched 1876 by "%%", thus it is not escaped with a backslash. 1877 Keep in mind that in the `:make` and `:grep` output all NUL characters are 1878 replaced with SOH (0x01). 1879 1880 Note: By default the difference between upper and lowercase is ignored. If 1881 you want to match case, add "\C" to the pattern |/\C|. 1882 1883 Vim will read lines of any length, but only the first 4095 bytes are used, the 1884 rest is ignored. Items can only be 1023 bytes long. 1885 1886 1887 Basic items 1888 1889 %f file name (finds a string) 1890 %b buffer number (finds a number) 1891 %o module name (finds a string) 1892 %l line number (finds a number) 1893 %e end line number (finds a number) 1894 %c column number (finds a number representing character 1895 column of the error, byte index, a <tab> is 1 1896 character column) 1897 %v virtual column number (finds a number representing the 1898 screen column of the error, where a <tab> is always 8 1899 screen columns regardless of 'tabstop') 1900 %k end column number (finds a number representing 1901 the character column of the error, byte index, or a 1902 number representing screen end column of the error if 1903 it's used with %v) 1904 %t error type (finds a single character): 1905 e - error message 1906 w - warning message 1907 i - info message 1908 n - note message 1909 The uppercase letters E, W, I and N are also 1910 recognized and have the same meaning. 1911 %n error number (finds a number) 1912 %m error message (finds a string) 1913 %r matches the "rest" of a single-line file message %O/P/Q 1914 %p pointer line (finds a sequence of '-', '.', ' ' or 1915 tabs and uses the length for the column number) 1916 %*{conv} any scanf non-assignable conversion 1917 %% the single '%' character 1918 %s search text (finds a string) 1919 1920 The "%f" conversion may depend on the current 'isfname' setting. "~/" is 1921 expanded to the home directory and environment variables are expanded. 1922 1923 The "%f" and "%m" conversions have to detect the end of the string. This 1924 normally happens by matching following characters and items. When nothing is 1925 following the rest of the line is matched. If "%f" is followed by a '%' or a 1926 backslash, it will look for a sequence of 'isfname' characters. 1927 1928 On MS-Windows a leading "C:" will be included in "%f", even when using "%f:". 1929 This means that a file name which is a single alphabetical letter will not be 1930 detected. 1931 1932 The "%b" conversion is used to parse a buffer number. This is useful for 1933 referring to lines in a scratch buffer or a buffer with no name. If a buffer 1934 with the matching number doesn't exist, then that line is used as a non-error 1935 line. 1936 1937 The "%p" conversion is normally followed by a "^". It's used for compilers 1938 that output a line like: > 1939 ^ 1940 or > 1941 ---------^ 1942 to indicate the column of the error. This is to be used in a multi-line error 1943 message. See |errorformat-javac| for a useful example. 1944 1945 The "%s" conversion specifies the text to search for, to locate the error 1946 line. The text is used as a literal string. The anchors "^" and "$" are 1947 added to the text to locate the error line exactly matching the search text 1948 and the text is prefixed with the "\V" atom to make it "very nomagic". The 1949 "%s" conversion can be used to locate lines without a line number in the error 1950 output. Like the output of the "grep" shell command. 1951 When the pattern is present the line number will not be used. 1952 1953 The "%o" conversion specifies the module name in quickfix entry. If present 1954 it will be used in quickfix error window instead of the filename. The module 1955 name is used only for displaying purposes, the file name is used when jumping 1956 to the file. 1957 1958 Changing directory 1959 1960 The following uppercase conversion characters specify the type of special 1961 format strings. At most one of them may be given as a prefix at the beginning 1962 of a single comma-separated format pattern. 1963 Some compilers produce messages that consist of directory names that have to 1964 be prepended to each file name read by %f (example: GNU make). The following 1965 codes can be used to scan these directory names; they will be stored in an 1966 internal directory stack. *E379* 1967 %D "enter directory" format string; expects a following 1968 %f that finds the directory name 1969 %X "leave directory" format string; expects following %f 1970 1971 When defining an "enter directory" or "leave directory" format, the "%D" or 1972 "%X" has to be given at the start of that substring. Vim tracks the directory 1973 changes and prepends the current directory to each erroneous file found with a 1974 relative path. See |quickfix-directory-stack| for details, tips and 1975 limitations. 1976 1977 1978 Multi-line messages *errorformat-multi-line* 1979 1980 It is possible to read the output of programs that produce multi-line 1981 messages, i.e. error strings that consume more than one line. Possible 1982 prefixes are: 1983 %E start of a multi-line error message 1984 %W start of a multi-line warning message 1985 %I start of a multi-line informational message 1986 %N start of a multi-line note message 1987 %A start of a multi-line message (unspecified type) 1988 %> for next line start with current pattern again |efm-%>| 1989 %C continuation of a multi-line message 1990 %Z end of a multi-line message 1991 These can be used with '+' and '-', see |efm-ignore| below. 1992 1993 Using "\n" in the pattern won't work to match multi-line messages. 1994 1995 Example: Your compiler happens to write out errors in the following format 1996 (leading line numbers not being part of the actual output): 1997 1998 1 Error 275 ~ 1999 2 line 42 ~ 2000 3 column 3 ~ 2001 4 ' ' expected after '--' ~ 2002 2003 The appropriate error format string has to look like this: > 2004 :set efm=%EError\ %n,%Cline\ %l,%Ccolumn\ %c,%Z%m 2005 2006 And the |:clist| error message generated for this error is: 2007 2008 1:42 col 3 error 275: ' ' expected after '--' 2009 2010 Another example: Think of a Python interpreter that produces the following 2011 error message (line numbers are not part of the actual output): 2012 2013 1 ============================================================== 2014 2 FAIL: testGetTypeIdCachesResult (dbfacadeTest.DjsDBFacadeTest) 2015 3 -------------------------------------------------------------- 2016 4 Traceback (most recent call last): 2017 5 File "unittests/dbfacadeTest.py", line 89, in testFoo 2018 6 self.assertEquals(34, dtid) 2019 7 File "/usr/lib/python2.2/unittest.py", line 286, in 2020 8 failUnlessEqual 2021 9 raise self.failureException, \ 2022 10 AssertionError: 34 != 33 2023 11 2024 12 -------------------------------------------------------------- 2025 13 Ran 27 tests in 0.063s 2026 2027 Say you want |:clist| write the relevant information of this message only, 2028 namely: 2029 5 unittests/dbfacadeTest.py:89: AssertionError: 34 != 33 2030 2031 Then the error format string could be defined as follows: > 2032 :set efm=%C\ %.%#,%A\ \ File\ \"%f\"\\,\ line\ %l%.%#,%Z%[%^\ ]%\\@=%m 2033 2034 Note that the %C string is given before the %A here: since the expression 2035 ' %.%#' (which stands for the regular expression ' .*') matches every line 2036 starting with a space, followed by any characters to the end of the line, 2037 it also hides line 7 which would trigger a separate error message otherwise. 2038 Error format strings are always parsed pattern by pattern until the first 2039 match occurs. 2040 *efm-%>* 2041 The %> item can be used to avoid trying patterns that appear earlier in 2042 'errorformat'. This is useful for patterns that match just about anything. 2043 For example, if the error looks like this: 2044 2045 Error in line 123 of foo.c: ~ 2046 unknown variable "i" ~ 2047 2048 This can be found with: > 2049 :set efm=xxx,%E%>Error in line %l of %f:,%Z%m 2050 Where "xxx" has a pattern that would also match the second line. 2051 2052 Important: There is no memory of what part of the errorformat matched before; 2053 every line in the error file gets a complete new run through the error format 2054 lines. For example, if one has: > 2055 setlocal efm=aa,bb,cc,dd,ee 2056 Where aa, bb, etc. are error format strings. Each line of the error file will 2057 be matched to the pattern aa, then bb, then cc, etc. Just because cc matched 2058 the previous error line does _not_ mean that dd will be tried first on the 2059 current line, even if cc and dd are multi-line errorformat strings. 2060 2061 2062 2063 Separate file name *errorformat-separate-filename* 2064 2065 These prefixes are useful if the file name is given once and multiple messages 2066 follow that refer to this file name. 2067 %O single-line file message: overread the matched part 2068 %P single-line file message: push file %f onto the stack 2069 %Q single-line file message: pop the last file from stack 2070 2071 Example: Given a compiler that produces the following error logfile (without 2072 leading line numbers): 2073 2074 1 [a1.tt] 2075 2 (1,17) error: ';' missing 2076 3 (21,2) warning: variable 'z' not defined 2077 4 (67,3) error: end of file found before string ended 2078 5 2079 6 [a2.tt] 2080 7 2081 8 [a3.tt] 2082 9 NEW compiler v1.1 2083 10 (2,2) warning: variable 'x' not defined 2084 11 (67,3) warning: 's' already defined 2085 2086 This logfile lists several messages for each file enclosed in [...] which are 2087 properly parsed by an error format like this: > 2088 :set efm=%+P[%f],(%l\\,%c)%*[\ ]%t%*[^:]:\ %m,%-Q 2089 2090 A call of |:clist| writes them accordingly with their correct filenames: 2091 2092 2 a1.tt:1 col 17 error: ';' missing 2093 3 a1.tt:21 col 2 warning: variable 'z' not defined 2094 4 a1.tt:67 col 3 error: end of file found before string ended 2095 8 a3.tt:2 col 2 warning: variable 'x' not defined 2096 9 a3.tt:67 col 3 warning: 's' already defined 2097 2098 Unlike the other prefixes that all match against whole lines, %P, %Q and %O 2099 can be used to match several patterns in the same line. Thus it is possible 2100 to parse even nested files like in the following line: 2101 {"file1" {"file2" error1} error2 {"file3" error3 {"file4" error4 error5}}} 2102 The %O then parses over strings that do not contain any push/pop file name 2103 information. See |errorformat-LaTeX| for an extended example. 2104 2105 2106 Ignoring and using whole messages *efm-ignore* 2107 2108 The codes '+' or '-' can be combined with the uppercase codes above; in that 2109 case they have to precede the letter, e.g. '%+A' or '%-G': 2110 %- do not include the matching multi-line in any output 2111 %+ include the whole matching line in the %m error string 2112 2113 One prefix is only useful in combination with '+' or '-', namely %G. It 2114 parses over lines containing general information like compiler version strings 2115 or other headers that can be skipped. 2116 %-G ignore this message 2117 %+G general message 2118 2119 2120 Pattern matching 2121 2122 The scanf()-like "%*[]" notation is supported for backward-compatibility 2123 with previous versions of Vim. However, it is also possible to specify 2124 (nearly) any Vim supported regular expression in format strings. 2125 Since meta characters of the regular expression language can be part of 2126 ordinary matching strings or file names (and therefore internally have to 2127 be escaped), meta symbols have to be written with leading '%': 2128 %\ The single '\' character. Note that this has to be 2129 escaped ("%\\") in ":set errorformat=" definitions. 2130 %. The single '.' character. 2131 %# The single '*'(!) character. 2132 %^ The single '^' character. Note that this is not 2133 useful, the pattern already matches start of line. 2134 %$ The single '$' character. Note that this is not 2135 useful, the pattern already matches end of line. 2136 %[ The single '[' character for a [] character range. 2137 %~ The single '~' character. 2138 When using character classes in expressions (see |/\i| for an overview), 2139 terms containing the "\+" quantifier can be written in the scanf() "%*" 2140 notation. Example: "%\\d%\\+" ("\d\+", "any number") is equivalent to 2141 "%*\\d". 2142 Important note: The \(...\) grouping of sub-matches can not be used in format 2143 specifications because it is reserved for internal conversions. 2144 2145 2146 Multiple entries in 'errorformat' *efm-entries* 2147 2148 To be able to detect output from several compilers, several format patterns 2149 may be put in 'errorformat', separated by commas (note: blanks after the comma 2150 are ignored). The first pattern that has a complete match is used. If no 2151 match is found, matching parts from the last one will be used, although the 2152 file name is removed and the error message is set to the whole message. If 2153 there is a pattern that may match output from several compilers (but not in a 2154 right way), put it after one that is more restrictive. 2155 2156 To include a comma in a pattern precede it with a backslash (you have to type 2157 two in a ":set" command). To include a backslash itself give two backslashes 2158 (you have to type four in a ":set" command). You also need to put a backslash 2159 before a space for ":set". 2160 2161 2162 Valid matches *quickfix-valid* 2163 2164 If a line does not completely match one of the entries in 'errorformat', the 2165 whole line is put in the error message and the entry is marked "not valid" 2166 These lines are skipped with the ":cn" and ":cp" commands (unless there is 2167 no valid line at all). You can use ":cl!" to display all the error messages. 2168 2169 If the error format does not contain a file name Vim cannot switch to the 2170 correct file. You will have to do this by hand. 2171 2172 2173 Examples 2174 2175 The format of the file from the Amiga Aztec compiler is: 2176 2177 filename>linenumber:columnnumber:errortype:errornumber:errormessage 2178 2179 filename name of the file in which the error was detected 2180 linenumber line number where the error was detected 2181 columnnumber column number where the error was detected 2182 errortype type of the error, normally a single 'E' or 'W' 2183 errornumber number of the error (for lookup in the manual) 2184 errormessage description of the error 2185 2186 This can be matched with this 'errorformat' entry: 2187 %f>%l:%c:%t:%n:%m 2188 2189 Some examples for C compilers that produce single-line error outputs: 2190 %f:%l:\ %t%*[^0123456789]%n:\ %m for Manx/Aztec C error messages 2191 (scanf() doesn't understand [0-9]) 2192 %f\ %l\ %t%*[^0-9]%n:\ %m for SAS C 2193 \"%f\"\\,%*[^0-9]%l:\ %m for generic C compilers 2194 %f:%l:\ %m for GCC 2195 %f:%l:\ %m,%Dgmake[%*\\d]:\ Entering\ directory\ `%f', 2196 %Dgmake[%*\\d]:\ Leaving\ directory\ `%f' 2197 for GCC with gmake (concat the lines!) 2198 %f(%l)\ :\ %*[^:]:\ %m old SCO C compiler (pre-OS5) 2199 %f(%l)\ :\ %t%*[^0-9]%n:\ %m idem, with error type and number 2200 %f:%l:\ %m,In\ file\ included\ from\ %f:%l:,\^I\^Ifrom\ %f:%l%m 2201 for GCC, with some extras 2202 2203 Extended examples for the handling of multi-line messages are given below, 2204 see |errorformat-Jikes| and |errorformat-LaTeX|. 2205 2206 Note the backslash in front of a space and double quote. It is required for 2207 the :set command. There are two backslashes in front of a comma, one for the 2208 :set command and one to avoid recognizing the comma as a separator of error 2209 formats. 2210 2211 2212 Filtering messages 2213 2214 If you have a compiler that produces error messages that do not fit in the 2215 format string, you could write a program that translates the error messages 2216 into this format. You can use this program with the ":make" command by 2217 changing the 'makeprg' option. For example: > 2218 :set mp=make\ \\\|&\ error_filter 2219 The backslashes before the pipe character are required to avoid it to be 2220 recognized as a command separator. The backslash before each space is 2221 required for the set command. 2222 2223 ============================================================================= 2224 8. The directory stack *quickfix-directory-stack* 2225 2226 Quickfix maintains a stack for saving all used directories parsed from the 2227 make output. For GNU-make this is rather simple, as it always prints the 2228 absolute path of all directories it enters and leaves. Regardless if this is 2229 done via a 'cd' command in the makefile or with the parameter "-C dir" (change 2230 to directory before reading the makefile). It may be useful to use the switch 2231 "-w" to force GNU-make to print out the working directory before and after 2232 processing. 2233 2234 This matters only when compiler output contains relative file names from 2235 multiple directories. If the output does not clearly report directory 2236 changes, Vim has to guess and can select the wrong file. Printing absolute 2237 directory names and both entering and leaving directory messages avoids this 2238 problem. 2239 2240 Maintaining the correct directory is more complicated if you don't use 2241 GNU-make. AIX-make for example doesn't print any information about its 2242 working directory. Then you need to enhance the makefile. In the makefile of 2243 LessTif there is a command which echoes "Making {target} in {dir}". The 2244 special problem here is that it doesn't print information on leaving the 2245 directory and that it doesn't print the absolute path. 2246 2247 To solve the problem with relative paths and missing "leave directory" 2248 messages Vim uses the following algorithm: 2249 2250 1) Check if the given directory is a subdirectory of the current directory. 2251 If this is true, store it as the current directory. 2252 2) If it is not a subdir of the current directory, try if this is a 2253 subdirectory of one of the upper directories. 2254 3) If the directory still isn't found, it is assumed to be a subdirectory 2255 of Vim's current directory. 2256 2257 Additionally it is checked for every file, if it really exists in the 2258 identified directory. If not, it is searched in all other directories of the 2259 directory stack (NOT the directory subtree!). If it is still not found, it is 2260 assumed that it is in Vim's current directory. 2261 2262 There are limitations in this algorithm. These examples assume that make just 2263 prints information about entering a directory in the form "Making all in dir". 2264 2265 1) Assume you have following directories and files: 2266 ./dir1 2267 ./dir1/file1.c 2268 ./file1.c 2269 2270 If make processes the directory "./dir1" before the current directory and 2271 there is an error in the file "./file1.c", you will end up with the file 2272 "./dir1/file.c" loaded by Vim. 2273 2274 This can only be solved with a "leave directory" message. 2275 2276 2) Assume you have following directories and files: 2277 ./dir1 2278 ./dir1/dir2 2279 ./dir2 2280 2281 You get the following: 2282 2283 Make output Directory interpreted by Vim 2284 ------------------------ ---------------------------- 2285 Making all in dir1 ./dir1 2286 Making all in dir2 ./dir1/dir2 2287 Making all in dir2 ./dir1/dir2 2288 2289 This can be solved by printing absolute directories in the "enter 2290 directory" message or by printing "leave directory" messages. 2291 2292 To avoid this problem, ensure to print absolute directory names and "leave 2293 directory" messages. 2294 2295 Examples for Makefiles: 2296 2297 Unix: 2298 libs: 2299 for dn in $(LIBDIRS); do \ 2300 (cd $$dn; echo "Entering dir '$$(pwd)'"; make); \ 2301 echo "Leaving dir"; \ 2302 done 2303 2304 Add 2305 %DEntering\ dir\ '%f',%XLeaving\ dir 2306 to your 'errorformat' to handle the above output. 2307 2308 Note that Vim doesn't check if the directory name in a "leave directory" 2309 messages is the current directory. This is why you could just use the message 2310 "Leaving dir". 2311 2312 ============================================================================= 2313 9. Specific error file formats *errorformats* 2314 2315 *errorformat-Jikes* 2316 Jikes(TM), a source-to-bytecode Java compiler published by IBM Research, 2317 produces simple multi-line error messages. 2318 2319 An 'errorformat' string matching the produced messages is shown below. 2320 The following lines can be placed in the user's |vimrc| to overwrite Vim's 2321 recognized default formats, or see |:set+=| how to install this format 2322 additionally to the default. > 2323 2324 :set efm=%A%f:%l:%c:%*\\d:%*\\d:, 2325 \%C%*\\s%trror:%m, 2326 \%+C%*[^:]%trror:%m, 2327 \%C%*\\s%tarning:%m, 2328 \%C%m 2329 < 2330 Jikes(TM) produces a single-line error message when invoked with the option 2331 "+E", and can be matched with the following: > 2332 2333 :setl efm=%f:%l:%v:%*\\d:%*\\d:%*\\s%m 2334 < 2335 *errorformat-javac* 2336 This 'errorformat' has been reported to work well for javac, which outputs a 2337 line with "^" to indicate the column of the error: > 2338 :setl efm=%A%f:%l:\ %m,%-Z%p^,%-C%.%# 2339 or: > 2340 :setl efm=%A%f:%l:\ %m,%+Z%p^,%+C%.%#,%-G%.%# 2341 < 2342 Here is an alternative from Michael F. Lamb for Unix that filters the errors 2343 first: > 2344 :setl errorformat=%Z%f:%l:\ %m,%A%p^,%-G%*[^sl]%.%# 2345 :setl makeprg=javac\ %:S\ 2>&1\ \\\|\ vim-javac-filter 2346 2347 You need to put the following in "vim-javac-filter" somewhere in your path 2348 (e.g., in ~/bin) and make it executable: > 2349 #!/bin/sed -f 2350 /\^$/s/\t/\ /g;/:[0-9]\+:/{h;d};/^[ \t]*\^/G; 2351 2352 In English, that sed script: 2353 - Changes single tabs to single spaces and 2354 - Moves the line with the filename, line number, error message to just after 2355 the pointer line. That way, the unused error text between doesn't break 2356 vim's notion of a "multi-line message" and also doesn't force us to include 2357 it as a "continuation of a multi-line message." 2358 2359 *errorformat-ant* 2360 For ant (http://jakarta.apache.org/) the above errorformat has to be modified 2361 to honour the leading [javac] in front of each javac output line: > 2362 :set efm=%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%# 2363 2364 The 'errorformat' can also be configured to handle ant together with either 2365 javac or jikes. If you're using jikes, you should tell ant to use jikes' +E 2366 command line switch which forces jikes to generate one-line error messages. 2367 This is what the second line (of a build.xml file) below does: > 2368 <property name = "build.compiler" value = "jikes"/> 2369 <property name = "build.compiler.emacs" value = "true"/> 2370 2371 The 'errorformat' which handles ant with both javac and jikes is: > 2372 :set efm=\ %#[javac]\ %#%f:%l:%c:%*\\d:%*\\d:\ %t%[%^:]%#:%m, 2373 \%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%# 2374 < 2375 *errorformat-jade* 2376 parsing jade (see http://www.jclark.com/) errors is simple: > 2377 :set efm=jade:%f:%l:%c:%t:%m 2378 < 2379 *errorformat-LaTeX* 2380 The following is an example how an 'errorformat' string can be specified 2381 for the (La)TeX typesetting system which displays error messages over 2382 multiple lines. The output of ":clist" and ":cc" etc. commands displays 2383 multi-lines in a single line, leading white space is removed. 2384 It should be easy to adopt the above LaTeX errorformat to any compiler output 2385 consisting of multi-line errors. 2386 2387 The commands can be placed in a |vimrc| file or some other Vim script file, 2388 e.g. a script containing LaTeX related stuff which is loaded only when editing 2389 LaTeX sources. 2390 Make sure to copy all lines of the example (in the given order), afterwards 2391 remove the comment lines. For the '\' notation at the start of some lines see 2392 |line-continuation|. 2393 2394 First prepare 'makeprg' such that LaTeX will report multiple 2395 errors; do not stop when the first error has occurred: > 2396 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*} 2397 < 2398 Start of multi-line error messages: > 2399 :set efm=%E!\ LaTeX\ %trror:\ %m, 2400 \%E!\ %m, 2401 < Start of multi-line warning messages; the first two also 2402 include the line number. Meaning of some regular expressions: 2403 - "%.%#" (".*") matches a (possibly empty) string 2404 - "%*\\d" ("\d\+") matches a number > 2405 \%+WLaTeX\ %.%#Warning:\ %.%#line\ %l%.%#, 2406 \%+W%.%#\ at\ lines\ %l--%*\\d, 2407 \%WLaTeX\ %.%#Warning:\ %m, 2408 < Possible continuations of error/warning messages; the first 2409 one also includes the line number: > 2410 \%Cl.%l\ %m, 2411 \%+C\ \ %m., 2412 \%+C%.%#-%.%#, 2413 \%+C%.%#[]%.%#, 2414 \%+C[]%.%#, 2415 \%+C%.%#%[{}\\]%.%#, 2416 \%+C<%.%#>%.%#, 2417 \%C\ \ %m, 2418 < Lines that match the following patterns do not contain any 2419 important information; do not include them in messages: > 2420 \%-GSee\ the\ LaTeX%m, 2421 \%-GType\ \ H\ <return>%m, 2422 \%-G\ ...%.%#, 2423 \%-G%.%#\ (C)\ %.%#, 2424 \%-G(see\ the\ transcript%.%#), 2425 < Generally exclude any empty or whitespace-only line from 2426 being displayed: > 2427 \%-G\\s%#, 2428 < The LaTeX output log does not specify the names of erroneous 2429 source files per line; rather they are given globally, 2430 enclosed in parentheses. 2431 The following patterns try to match these names and store 2432 them in an internal stack. The patterns possibly scan over 2433 the same input line (one after another), the trailing "%r" 2434 conversion indicates the "rest" of the line that will be 2435 parsed in the next go until the end of line is reached. 2436 2437 Overread a file name enclosed in '('...')'; do not push it 2438 on a stack since the file apparently does not contain any 2439 error: > 2440 \%+O(%f)%r, 2441 < Push a file name onto the stack. The name is given after '(': > 2442 \%+P(%f%r, 2443 \%+P\ %\\=(%f%r, 2444 \%+P%*[^()](%f%r, 2445 \%+P[%\\d%[^()]%#(%f%r, 2446 < Pop the last stored file name when a ')' is scanned: > 2447 \%+Q)%r, 2448 \%+Q%*[^()])%r, 2449 \%+Q[%\\d%*[^()])%r 2450 2451 Note that in some cases file names in the LaTeX output log cannot be parsed 2452 properly. The parser might have been messed up by unbalanced parentheses 2453 then. The above example tries to catch the most relevant cases only. 2454 You can customize the given setting to suit your own purposes, for example, 2455 all the annoying "Overfull ..." warnings could be excluded from being 2456 recognized as an error. 2457 Alternatively to filtering the LaTeX compiler output, it is also possible 2458 to directly read the *.log file that is produced by the [La]TeX compiler. 2459 This contains even more useful information about possible error causes. 2460 However, to properly parse such a complex file, an external filter should 2461 be used. See the description further above how to make such a filter known 2462 by Vim. 2463 2464 *errorformat-Perl* 2465 In $VIMRUNTIME/tools you can find the efm_perl.pl script, which filters Perl 2466 error messages into a format that quickfix mode will understand. See the 2467 start of the file about how to use it. (This script is deprecated, see 2468 |compiler-perl|.) 2469 2470 ============================================================================= 2471 10. Customizing the quickfix window *quickfix-window-function* 2472 2473 The default format for the lines displayed in the quickfix window and location 2474 list window is: 2475 2476 <filename>|<lnum> col <col>|<text> 2477 2478 The values displayed in each line correspond to the "bufnr", "lnum", "col" and 2479 "text" fields returned by the |getqflist()| function. 2480 2481 For some quickfix/location lists, the displayed text needs to be customized. 2482 For example, if only the filename is present for a quickfix entry, then the 2483 two "|" field separator characters after the filename are not needed. Another 2484 use case is to customize the path displayed for a filename. By default, the 2485 complete path (which may be too long) is displayed for files which are not 2486 under the current directory tree. The file path may need to be simplified to 2487 a common parent directory. 2488 2489 The displayed text can be customized by setting the 'quickfixtextfunc' option 2490 to a Vim function. This function will be called with a dict argument and 2491 should return a List of strings to be displayed in the quickfix or location 2492 list window. The dict argument will have the following fields: 2493 2494 quickfix set to 1 when called for a quickfix list and 0 when called for 2495 a location list. 2496 winid for a location list, set to the id of the window with the 2497 location list. For a quickfix list, set to 0. Can be used in 2498 getloclist() to get the location list entry. 2499 id quickfix or location list identifier 2500 start_idx index of the first entry for which text should be returned 2501 end_idx index of the last entry for which text should be returned 2502 2503 The function should return a single line of text to display in the quickfix 2504 window for each entry from start_idx to end_idx. The function can obtain 2505 information about the entries using the |getqflist()| function and specifying 2506 the quickfix list identifier "id". For a location list, getloclist() function 2507 can be used with the "winid" argument. If an empty list is returned, then the 2508 default format is used to display all the entries. If an item in the returned 2509 list is an empty string, then the default format is used to display the 2510 corresponding entry. 2511 2512 If a quickfix or location list specific customization is needed, then the 2513 'quickfixtextfunc' attribute of the list can be set using the |setqflist()| or 2514 |setloclist()| function. This overrides the global 'quickfixtextfunc' option. 2515 2516 The example below displays the list of old files (|v:oldfiles|) in a quickfix 2517 window. As there is no line, column number and error text information 2518 associated with each entry, the 'quickfixtextfunc' function returns only the 2519 filename. 2520 Example: > 2521 " create a quickfix list from v:oldfiles 2522 call setqflist([], ' ', {'lines' : v:oldfiles, 'efm' : '%f', 2523 \ 'quickfixtextfunc' : 'QfOldFiles'}) 2524 func QfOldFiles(info) 2525 " get information about a range of quickfix entries 2526 let items = getqflist({'id' : a:info.id, 'items' : 1}).items 2527 let l = [] 2528 for idx in range(a:info.start_idx - 1, a:info.end_idx - 1) 2529 " use the simplified file name 2530 call add(l, fnamemodify(bufname(items[idx].bufnr), ':p:.')) 2531 endfor 2532 return l 2533 endfunc 2534 < 2535 2536 vim:tw=78:ts=8:noet:ft=help:norl: