blob: 5a8370057c14d905566d8b6cd217137770a9a243 [file] [log] [blame]
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001*quickfix.txt* For Vim version 7.0aa. Last change: 2006 Mar 07
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7This subject is introduced in section |30.1| of the user manual.
8
91. Using QuickFix commands |quickfix|
102. The error window |quickfix-window|
113. Using more than one list of errors |quickfix-error-lists|
124. Using :make |:make_makeprg|
135. Using :grep |grep|
146. Selecting a compiler |compiler-select|
157. The error format |error-file-format|
168. The directory stack |quickfix-directory-stack|
179. Specific error file formats |errorformats|
18
19{Vi does not have any of these commands}
20
21The quickfix commands are not available when the |+quickfix| feature was
22disabled at compile time.
23
24=============================================================================
251. Using QuickFix commands *quickfix* *Quickfix* *E42*
26
27Vim has a special mode to speedup the edit-compile-edit cycle. This is
28inspired by the quickfix option of the Manx's Aztec C compiler on the Amiga.
29The idea is to save the error messages from the compiler in a file and use Vim
30to jump to the errors one by one. You can examine each problem and fix it,
31without having to remember all the error messages.
32
Bram Moolenaar05159a02005-02-26 23:04:13 +000033In Vim the quickfix commands are used more generally to find a list of
34positions in files. For example, |:vimgrep| finds pattern matches. You can
Bram Moolenaar2641f772005-03-25 21:58:17 +000035use the positions in a script with the |getqflist()| function. Thus you can
Bram Moolenaar05159a02005-02-26 23:04:13 +000036do a lot more than the edit/compile/fix cycle!
37
Bram Moolenaar071d4272004-06-13 20:20:40 +000038If you are using Manx's Aztec C compiler on the Amiga look here for how to use
39it with Vim: |quickfix-manx|. If you are using another compiler you should
40save the error messages in a file and start Vim with "vim -q filename". An
41easy way to do this is with the |:make| command (see below). The
42'errorformat' option should be set to match the error messages from your
43compiler (see |errorformat| below).
44
Bram Moolenaard12f5c12006-01-25 22:10:52 +000045 *location-list* *E776*
Bram Moolenaar280f1262006-01-30 00:14:18 +000046A location list is similar to a quickfix list and contains a list of positions
47in files. A location list is associated with a window and each window can
48have a separate location list. A location list can be associated with only
49one window. The location list is independent of the quickfix list.
Bram Moolenaard12f5c12006-01-25 22:10:52 +000050
Bram Moolenaar280f1262006-01-30 00:14:18 +000051When a window with a location list is split, the new window gets a copy of the
52location list. When there are no references to a location list, the location
53list is destroyed.
54
55The following quickfix commands can be used. The location list commands are
56similar to the quickfix commands, replacing the 'c' prefix in the quickfix
57command with 'l'.
Bram Moolenaar071d4272004-06-13 20:20:40 +000058
59 *:cc*
60:cc[!] [nr] Display error [nr]. If [nr] is omitted, the same
61 error is displayed again. Without [!] this doesn't
62 work when jumping to another buffer, the current buffer
63 has been changed, there is the only window for the
64 buffer and both 'hidden' and 'autowrite' are off.
65 When jumping to another buffer with [!] any changes to
66 the current buffer are lost, unless 'hidden' is set or
67 there is another window for this buffer.
68 The 'switchbuf' settings are respected when jumping
69 to a buffer.
70
Bram Moolenaard12f5c12006-01-25 22:10:52 +000071 *:ll*
72:ll[!] [nr] Same as ":cc", except the location list for the
73 current window is used instead of the quickfix list.
74
Bram Moolenaar071d4272004-06-13 20:20:40 +000075 *:cn* *:cnext* *E553*
76:[count]cn[ext][!] Display the [count] next error in the list that
77 includes a file name. If there are no file names at
78 all, go to the [count] next error. See |:cc| for
79 [!] and 'switchbuf'.
80
Bram Moolenaar17c7c012006-01-26 22:25:15 +000081 *:lne* *:lnext*
82:[count]lne[xt][!] Same as ":cnext", except the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +000083 current window is used instead of the quickfix list.
84
Bram Moolenaar071d4272004-06-13 20:20:40 +000085:[count]cN[ext][!] *:cp* *:cprevious* *:cN* *:cNext*
86:[count]cp[revious][!] Display the [count] previous error in the list that
87 includes a file name. If there are no file names at
88 all, go to the [count] previous error. See |:cc| for
89 [!] and 'switchbuf'.
90
Bram Moolenaar17c7c012006-01-26 22:25:15 +000091
92:[count]lN[ext][!] *:lp* *:lprevious* *:lN* *:lNext*
Bram Moolenaard12f5c12006-01-25 22:10:52 +000093:[count]lp[revious][!] Same as ":cNext" and ":cprevious", except the location
94 list for the current window is used instead of the
95 quickfix list.
96
Bram Moolenaar071d4272004-06-13 20:20:40 +000097 *:cnf* *:cnfile*
98:[count]cnf[ile][!] Display the first error in the [count] next file in
99 the list that includes a file name. If there are no
100 file names at all or if there is no next file, go to
101 the [count] next error. See |:cc| for [!] and
102 'switchbuf'.
103
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000104 *:lnf* *:lnfile*
105:[count]lnf[ile][!] Same as ":cnfile", except the location list for the
106 current window is used instead of the quickfix list.
107
Bram Moolenaar071d4272004-06-13 20:20:40 +0000108:[count]cNf[ile][!] *:cpf* *:cpfile* *:cNf* *:cNfile*
109:[count]cpf[ile][!] Display the last error in the [count] previous file in
110 the list that includes a file name. If there are no
111 file names at all or if there is no next file, go to
112 the [count] previous error. See |:cc| for [!] and
113 'switchbuf'.
114
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000115
116:[count]lNf[ile][!] *:lpf* *:lpfile* *:lNf* *:lNfile*
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000117:[count]lpf[ile][!] Same as ":cNfile" and ":cpfile", except the location
118 list for the current window is used instead of the
119 quickfix list.
120
Bram Moolenaar071d4272004-06-13 20:20:40 +0000121 *:crewind* *:cr*
122:cr[ewind][!] [nr] Display error [nr]. If [nr] is omitted, the FIRST
123 error is displayed. See |:cc|.
124
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000125 *:lrewind* *:lr*
126:lr[ewind][!] [nr] Same as ":crewind", except the location list for the
127 current window is used instead of the quickfix list.
128
Bram Moolenaar071d4272004-06-13 20:20:40 +0000129 *:cfirst* *:cfir*
130:cfir[st][!] [nr] Same as ":crewind".
131
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000132 *:lfirst* *:lfir*
133:lfir[st][!] [nr] Same as ":lrewind".
134
Bram Moolenaar071d4272004-06-13 20:20:40 +0000135 *:clast* *:cla*
136:cla[st][!] [nr] Display error [nr]. If [nr] is omitted, the LAST
137 error is displayed. See |:cc|.
138
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000139 *:llast* *:lla*
140:lla[st][!] [nr] Same as ":clast", except the location list for the
141 current window is used instead of the quickfix list.
142
Bram Moolenaar071d4272004-06-13 20:20:40 +0000143 *:cq* *:cquit*
144:cq[uit] Quit Vim with an error code, so that the compiler
145 will not compile the same file again.
146
147 *:cf* *:cfile*
148:cf[ile][!] [errorfile] Read the error file and jump to the first error.
149 This is done automatically when Vim is started with
150 the -q option. You can use this command when you
151 keep Vim running while compiling. If you give the
152 name of the errorfile, the 'errorfile' option will
153 be set to [errorfile]. See |:cc| for [!].
154
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000155 *:lf* *:lfile*
156:lf[ile][!] [errorfile] Same as ":cfile", except the location list for the
157 current window is used instead of the quickfix list.
158 You can not use the -q command-line option to set
159 the location list.
160
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000161
162:cg[etfile][!] [errorfile] *:cg* *:cgetfile*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000163 Read the error file. Just like ":cfile" but don't
164 jump to the first error.
165
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000166
167:lg[etfile][!] [errorfile] *:lg* *:lgetfile*
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000168 Same as ":cgetfile", except the location list for the
169 current window is used instead of the quickfix list.
170
Bram Moolenaar4770d092006-01-12 23:22:24 +0000171 *:caddf* *:caddfile*
172:caddf[ile] [errorfile] Read the error file and add the errors from the
Bram Moolenaar87e25fd2005-07-27 21:13:01 +0000173 errorfile to the current quickfix list. If a quickfix
174 list is not present, then a new list is created.
175
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000176 *:laddf* *:laddfile*
177:laddf[ile] [errorfile] Same as ":caddfile", except the location list for the
178 current window is used instead of the quickfix list.
179
Bram Moolenaar86b68352004-12-27 21:59:20 +0000180 *:cb* *:cbuffer* *E681*
181:cb[uffer] [bufnr] Read the error list from the current buffer.
182 When [bufnr] is given it must be the number of a
183 loaded buffer. That buffer will then be used instead
184 of the current buffer.
185 A range can be specified for the lines to be used.
186 Otherwise all lines in the buffer are used.
187
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000188 *:lb* *:lbuffer*
189:lb[uffer] [bufnr] Same as ":cbuffer", except the location list for the
190 current window is used instead of the quickfix list.
191
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000192 *:caddb* *:caddbuffer*
193:caddb[uffer] [bufnr] Read the error list from the current buffer and add
194 the errors to the current quickfix list. If a
195 quickfix list is not present, then a new list is
196 created. Otherwise, same as ":cbuffer".
197
198 *:laddb* *:laddbuffer*
199:laddb[uffer] [bufnr] Same as ":caddbuffer", except the location list for
200 the current window is used instead of the quickfix
201 list.
202
Bram Moolenaara40ceaf2006-01-13 22:35:40 +0000203 *:cex* *:cexpr* *E777*
Bram Moolenaar4770d092006-01-12 23:22:24 +0000204:cex[pr][!] {expr} Create a quickfix list using the result of {expr} and
205 jump to the first error. If {expr} is a String, then
206 each new-line terminated line in the String is
207 processed using 'errorformat' and the result is added
208 to the quickfix list. If {expr} is a List, then each
209 String item in the list is processed and added to the
210 quickfix list. Non String items in the List are
211 ignored. See |:cc|
Bram Moolenaar87e25fd2005-07-27 21:13:01 +0000212 for [!].
213 Examples: >
214 :cexpr system('grep -n xyz *')
215 :cexpr getline(1, '$')
216<
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000217 *:lex* *:lexpr*
218:lex[pr][!] {expr} Same as ":cexpr", except the location list for the
219 current window is used instead of the quickfix list.
220
Bram Moolenaar4770d092006-01-12 23:22:24 +0000221 *:cad* *:caddexpr*
222:cad[dexpr][!] {expr} Evaluate {expr} and add the resulting lines to the
223 current quickfix list. If a quickfix list is not
224 present, then a new list is created. The current
225 cursor position will not be changed. See |:cexpr| for
226 more information.
227 Example: >
228 :g/mypattern/caddexpr expand("%") . ":" . line(".") . ":" . getline(".")
229<
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000230 *:lad* *:laddexpr*
231:lad[dexpr][!] {expr} Same as ":caddexpr", except the location list for the
232 current window is used instead of the quickfix list.
233
Bram Moolenaar071d4272004-06-13 20:20:40 +0000234 *:cl* *:clist*
235:cl[ist] [from] [, [to]]
236 List all errors that are valid |quickfix-valid|.
237 If numbers [from] and/or [to] are given, the respective
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000238 range of errors is listed. A negative number counts
Bram Moolenaar071d4272004-06-13 20:20:40 +0000239 from the last error backwards, -1 being the last error.
240 The 'switchbuf' settings are respected when jumping
241 to a buffer.
242
243:cl[ist]! [from] [, [to]]
244 List all errors.
245
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000246 *:lli* *:llist*
247:lli[st] [from] [, [to]]
248 Same as ":clist", except the location list for the
249 current window is used instead of the quickfix list.
250
251:lli[st]! [from] [, [to]]
252 List all the entries in the location list for the
253 current window.
254
Bram Moolenaar071d4272004-06-13 20:20:40 +0000255If you insert or delete lines, mostly the correct error location is still
256found because hidden marks are used. Sometimes, when the mark has been
257deleted for some reason, the message "line changed" is shown to warn you that
258the error location may not be correct. If you quit Vim and start again the
259marks are lost and the error locations may not be correct anymore.
260
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000261If vim is built with |+autocmd| support, two autocommands are available for
262running commands before and after a quickfix command (':make', ':grep' and so
263on) is executed. See |QuickFixCmdPre| and |QuickFixCmdPost| for details.
264
Bram Moolenaar071d4272004-06-13 20:20:40 +0000265=============================================================================
2662. The error window *quickfix-window*
267
268 *:cope* *:copen*
269:cope[n] [height] Open a window to show the current list of errors.
270 When [height] is given, the window becomes that high
271 (if there is room). Otherwise the window is made ten
272 lines high.
273 The window will contain a special buffer, with
274 'buftype' equal to "quickfix". Don't change this!
275 If there already is a quickfix window, it will be made
276 the current window. It is not possible to open a
277 second quickfix window.
278
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000279 *:lop* *:lopen*
280:lop[en] [height] Open a window to show the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000281 current window. Works only when the location list for
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000282 the current window is present. You can have more than
283 one location window opened at a time. Otherwise, it
Bram Moolenaar280f1262006-01-30 00:14:18 +0000284 acts the same as ":copen".
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000285
Bram Moolenaar071d4272004-06-13 20:20:40 +0000286 *:ccl* *:cclose*
287:ccl[ose] Close the quickfix window.
288
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000289 *:lcl* *:lclose*
290:lcl[ose] Close the window showing the location list for the
291 current window.
292
Bram Moolenaar071d4272004-06-13 20:20:40 +0000293 *:cw* *:cwindow*
294:cw[indow] [height] Open the quickfix window when there are recognized
295 errors. If the window is already open and there are
296 no recognized errors, close the window.
297
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000298 *:lw* *:lwindow*
299:lw[indow] [height] Same as ":cwindow", except use the window showing the
300 location list for the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000301
302Normally the quickfix window is at the bottom of the screen. If there are
303vertical splits, it's at the bottom of the rightmost column of windows. To
304make it always occupy the full width: >
305 :botright cwindow
306You can move the window around with |window-moving| commands.
307For example, to move it to the top: CTRL-W K
308The 'winfixheight' option will be set, which means that the window will mostly
309keep its height, ignoring 'winheight' and 'equalalways'. You can change the
310height manually (e.g., by dragging the status line above it with the mouse).
311
312In the quickfix window, each line is one error. The line number is equal to
313the error number. You can use ":.cc" to jump to the error under the cursor.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000314Hitting the <Enter> key or double-clicking the mouse on a line has the same
Bram Moolenaar071d4272004-06-13 20:20:40 +0000315effect. The file containing the error is opened in the window above the
316quickfix window. If there already is a window for that file, it is used
317instead. If the buffer in the used window has changed, and the error is in
318another file, jumping to the error will fail. You will first have to make
319sure the window contains a buffer which can be abandoned.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000320 *CTRL-W_<Enter>* *CTRL-W_<CR>*
321You can use CTRL-W <Enter> to open a new window and jump to the error there.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000322
323When the quickfix window has been filled, two autocommand events are
324triggered. First the 'filetype' option is set to "qf", which triggers the
Bram Moolenaar1ef15e32006-02-01 21:56:25 +0000325FileType event. Then the BufReadPost event is triggered, using "quickfix" for
326the buffer name. This can be used to perform some action on the listed
327errors. Example: >
Bram Moolenaar280f1262006-01-30 00:14:18 +0000328 au BufReadPost quickfix setlocal modifiable
329 \ | silent exe 'g/^/s//\=line(".")." "/'
330 \ | setlocal nomodifiable
Bram Moolenaar071d4272004-06-13 20:20:40 +0000331This prepends the line number to each line. Note the use of "\=" in the
332substitute string of the ":s" command, which is used to evaluate an
333expression.
Bram Moolenaar1ef15e32006-02-01 21:56:25 +0000334The BufWinEnter event is also triggered, again using "quickfix" for the buffer
335name.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000336
337Note: Making changes in the quickfix window has no effect on the list of
338errors. 'modifiable' is off to avoid making changes. If you delete or insert
339lines anyway, the relation between the text and the error number is messed up.
340If you really want to do this, you could write the contents of the quickfix
341window to a file and use ":cfile" to have it parsed and used as the new error
342list.
343
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000344 *location-list-window*
Bram Moolenaar280f1262006-01-30 00:14:18 +0000345The location list window displays the entries in a location list. When you
346open a location list window, it is created below the current window and
347displays the location list for the current window. The location list window
348is similar to the quickfix window, except that you can have more than one
Bram Moolenaar1ef15e32006-02-01 21:56:25 +0000349location list window open at a time. When you use a location list command in
350this window, the displayed location list is used.
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000351
Bram Moolenaar280f1262006-01-30 00:14:18 +0000352When you select a file from the location list window, the following steps are
353used to find a window to edit the file:
354
3551. If a window with the location list displayed in the location list window is
356 present, then the file is opened in that window.
3572. If the above step fails and if the file is already opened in another
358 window, then that window is used.
3593. If the above step fails then an existing window showing a buffer with
360 'buftype' not set is used.
3614. If the above step fails, then the file is edited in a new window.
362
363In all of the above cases, if the location list for the selected window is not
364yet set, then it is set to the location list displayed in the location list
365window.
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000366
Bram Moolenaar071d4272004-06-13 20:20:40 +0000367=============================================================================
3683. Using more than one list of errors *quickfix-error-lists*
369
370So far has been assumed that there is only one list of errors. Actually the
371ten last used lists are remembered. When starting a new list, the previous
372ones are automatically kept. Two commands can be used to access older error
373lists. They set one of the existing error lists as the current one.
374
375 *:colder* *:col* *E380*
376:col[der] [count] Go to older error list. When [count] is given, do
377 this [count] times. When already at the oldest error
378 list, an error message is given.
379
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000380 *:lolder* *:lol*
381:lol[der] [count] Same as ":colder", except use the location list for
382 the current window instead of the quickfix list.
383
Bram Moolenaar071d4272004-06-13 20:20:40 +0000384 *:cnewer* *:cnew* *E381*
385:cnew[er] [count] Go to newer error list. When [count] is given, do
386 this [count] times. When already at the newest error
387 list, an error message is given.
388
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000389 *:lnewer* *:lnew*
390:lnew[er] [count] Same as ":cnewer", except use the location list for
391 the current window instead of the quickfix list.
392
Bram Moolenaar071d4272004-06-13 20:20:40 +0000393When adding a new error list, it becomes the current list.
394
395When ":colder" has been used and ":make" or ":grep" is used to add a new error
396list, one newer list is overwritten. This is especially useful if you are
397browsing with ":grep" |grep|. If you want to keep the more recent error
398lists, use ":cnewer 99" first.
399
400=============================================================================
4014. Using :make *:make_makeprg*
402
403 *:mak* *:make*
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000404:mak[e][!] [arguments] 1. If vim was built with |+autocmd|, all relevant
405 |QuickFixCmdPre| autocommands are executed.
406 2. If the 'autowrite' option is on, write any changed
Bram Moolenaar071d4272004-06-13 20:20:40 +0000407 buffers
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000408 3. An errorfile name is made from 'makeef'. If
Bram Moolenaar071d4272004-06-13 20:20:40 +0000409 'makeef' doesn't contain "##", and a file with this
410 name already exists, it is deleted.
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000411 4. The program given with the 'makeprg' option is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000412 started (default "make") with the optional
413 [arguments] and the output is saved in the
414 errorfile (for Unix it is also echoed on the
415 screen).
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000416 5. The errorfile is read using 'errorformat'.
417 6. If [!] is not given the first error is jumped to.
418 7. The errorfile is deleted.
419 8. If vim was built with |+autocmd|, all relevant
420 |QuickFixCmdPost| autocommands are executed.
421 9. You can now move through the errors with commands
Bram Moolenaar071d4272004-06-13 20:20:40 +0000422 like |:cnext| and |:cprevious|, see above.
423 This command does not accept a comment, any "
424 characters are considered part of the arguments.
425
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000426 *:lmak* *:lmake*
427:lmak[e][!] [arguments]
428 Same as ":make", except the location list for the
429 current window is used instead of the quickfix list.
430
Bram Moolenaar071d4272004-06-13 20:20:40 +0000431The ":make" command executes the command given with the 'makeprg' option.
432This is done by passing the command to the shell given with the 'shell'
433option. This works almost like typing
434
435 ":!{makeprg} [arguments] {shellpipe} {errorfile}".
436
437{makeprg} is the string given with the 'makeprg' option. Any command can be
438used, not just "make". Characters '%' and '#' are expanded as usual on a
439command-line. You can use "%<" to insert the current file name without
440extension, or "#<" to insert the alternate file name without extension, for
441example: >
442 :set makeprg=make\ #<.o
443
444[arguments] is anything that is typed after ":make".
445{shellpipe} is the 'shellpipe' option.
446{errorfile} is the 'makeef' option, with ## replaced to make it unique.
447
448The placeholder "$*" can be used for the argument list in {makeprog} if the
449command needs some additional characters after its arguments. The $* is
450replaced then by all arguments. Example: >
451 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
452or simpler >
453 :let &mp = 'latex \\nonstopmode \\input\{$*}'
454"$*" can be given multiple times, for example: >
455 :set makeprg=gcc\ -o\ $*\ $*
456
457The 'shellpipe' option defaults to ">" for the Amiga, MS-DOS and Win32. This
458means that the output of the compiler is saved in a file and not shown on the
459screen directly. For Unix "| tee" is used. The compiler output is shown on
460the screen and saved in a file the same time. Depending on the shell used
461"|& tee" or "2>&1| tee" is the default, so stderr output will be included.
462
463If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful
464for compilers that write to an errorfile themselves (e.g., Manx's Amiga C).
465
466==============================================================================
Bram Moolenaar86b68352004-12-27 21:59:20 +00004675. Using :vimgrep and :grep *grep* *lid*
468
469Vim has two ways to find matches for a pattern: Internal and external. The
470advantage of the internal grep is that it works on all systems and uses the
471powerful Vim search patterns. An external grep program can be used when the
472Vim grep does not do what you want.
473
Bram Moolenaar8fc061c2004-12-29 21:03:02 +0000474The internal method will be slower, because files are read into memory. The
475advantages are:
476- Line separators and encoding are automatically recognized, as if a file is
477 being edited.
478- Uses Vim search patterns. Multi-line patterns can be used.
479- When plugins are enabled: compressed and remote files can be searched.
480 |gzip| |netrw|
Bram Moolenaardcaf10e2005-01-21 11:55:25 +0000481- When 'hidden' is set the files are kept loaded, thus repeating a search is
482 much faster. Uses a lot of memory though!
Bram Moolenaar86b68352004-12-27 21:59:20 +0000483
484
4855.1 using Vim's internal grep
486
Bram Moolenaare49b69a2005-01-08 16:11:57 +0000487 *:vim* *:vimgrep* *E682* *E683*
Bram Moolenaar05159a02005-02-26 23:04:13 +0000488:vim[grep][!] /{pattern}/[g][j] {file} ...
Bram Moolenaar86b68352004-12-27 21:59:20 +0000489 Search for {pattern} in the files {file} ... and set
490 the error list to the matches.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000491 Without the 'g' flag each line is added only once.
492 With 'g' every match is added.
493
494 {pattern} is a Vim search pattern. Instead of
495 enclosing it in / any non-ID character (see
496 |'isident'|) can be used, so long as it does not
497 appear in {pattern}.
498 'ignorecase' applies. To overrule it put |/\c| in the
499 pattern to ignore case or |/\C| to match case.
500 'smartcase' is not used.
501
Bram Moolenaar1f35bf92006-03-07 22:38:47 +0000502 When a number is put before the command this is used
503 as the maximum number of matches to find. Use
504 ":1vimgrep pattern file" to find only the first.
505 Useful if you only want to check if there is a match
506 and quit quickly when it's found.
507
Bram Moolenaar05159a02005-02-26 23:04:13 +0000508 Without the 'j' flag Vim jumps to the first match.
509 With 'j' only the quickfix list is updated.
510 With the [!] any changes in the current buffer are
511 abandoned.
512
Bram Moolenaardcaf10e2005-01-21 11:55:25 +0000513 Every second or so the searched file name is displayed
514 to give you an idea of the progress made.
Bram Moolenaar8fc061c2004-12-29 21:03:02 +0000515 Examples: >
516 :vimgrep /an error/ *.c
517 :vimgrep /\<FileName\>/ *.h include/*
Bram Moolenaar231334e2005-07-25 20:46:57 +0000518 :vimgrep /myfunc/ **/*.c
519< For the use of "**" see |starstar-wildcard|.
Bram Moolenaar86b68352004-12-27 21:59:20 +0000520
Bram Moolenaar8fc061c2004-12-29 21:03:02 +0000521:vim[grep][!] {pattern} {file} ...
522 Like above, but instead of enclosing the pattern in a
523 non-ID character use a white-separated pattern. The
524 pattern must start with an ID character.
525 Example: >
526 :vimgrep Error *.c
527<
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000528 *:lv* *:lvimgrep*
529:lv[imgrep][!] /{pattern}/[g][j] {file} ...
530:lv[imgrep][!] {pattern} {file} ...
531 Same as ":vimgrep", except the location list for the
532 current window is used instead of the quickfix list.
533
Bram Moolenaar86b68352004-12-27 21:59:20 +0000534 *:vimgrepa* *:vimgrepadd*
Bram Moolenaar05159a02005-02-26 23:04:13 +0000535:vimgrepa[dd][!] /{pattern}/[g][j] {file} ...
536:vimgrepa[dd][!] {pattern} {file} ...
Bram Moolenaar86b68352004-12-27 21:59:20 +0000537 Just like ":vimgrep", but instead of making a new list
538 of errors the matches are appended to the current
539 list.
540
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000541 *:lvimgrepa* *:lvimgrepadd*
542:lvimgrepa[dd][!] /{pattern}/[g][j] {file} ...
543:lvimgrepa[dd][!] {pattern} {file} ...
544 Same as ":vimgrepadd", except the location list for
545 the current window is used instead of the quickfix
546 list.
Bram Moolenaar86b68352004-12-27 21:59:20 +0000547
5485.2 External grep
Bram Moolenaar071d4272004-06-13 20:20:40 +0000549
550Vim can interface with "grep" and grep-like programs (such as the GNU
551id-utils) in a similar way to its compiler integration (see |:make| above).
552
553[Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where
554"re" stands for Regular Expression.]
555
556 *:gr* *:grep*
557:gr[ep][!] [arguments] Just like ":make", but use 'grepprg' instead of
558 'makeprg' and 'grepformat' instead of 'errorformat'.
Bram Moolenaar86b68352004-12-27 21:59:20 +0000559 When 'grepprg' is "internal" this works like
560 |:vimgrep|. Note that the pattern needs to be
561 enclosed in separator characters then.
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000562
563 *:lgr* *:lgrep*
564:lgr[ep][!] [arguments] Same as ":grep", except the location list for the
565 current window is used instead of the quickfix list.
566
Bram Moolenaar071d4272004-06-13 20:20:40 +0000567 *:grepa* *:grepadd*
568:grepa[dd][!] [arguments]
569 Just like ":grep", but instead of making a new list of
570 errors the matches are appended to the current list.
571 Example: >
572 :grep nothing %
573 :bufdo grepadd! something %
574< The first command makes a new error list which is
575 empty. The second command executes "grepadd" for each
576 listed buffer. Note the use of ! to avoid that
577 ":grepadd" jumps to the first error, which is not
578 allowed with |:bufdo|.
579
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000580 *:lgrepa* *:lgrepadd*
581:lgrepa[dd][!] [arguments]
582 Same as ":grepadd", except the location list for the
583 current window is used instead of the quickfix list.
584
Bram Moolenaar86b68352004-12-27 21:59:20 +00005855.3 Setting up external grep
Bram Moolenaar071d4272004-06-13 20:20:40 +0000586
587If you have a standard "grep" program installed, the :grep command may work
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000588well with the defaults. The syntax is very similar to the standard command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000589
590 :grep foo *.c
591
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000592Will search all files with the .c extension for the substring "foo". The
Bram Moolenaar071d4272004-06-13 20:20:40 +0000593arguments to :grep are passed straight to the "grep" program, so you can use
594whatever options your "grep" supports.
595
596By default, :grep invokes grep with the -n option (show file and line
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000597numbers). You can change this with the 'grepprg' option. You will need to set
Bram Moolenaar071d4272004-06-13 20:20:40 +0000598'grepprg' if:
599
600a) You are using a program that isn't called "grep"
601b) You have to call grep with a full path
602c) You want to pass other options automatically (e.g. case insensitive
603 search.)
604
605Once "grep" has executed, Vim parses the results using the 'grepformat'
606option. This option works in the same way as the 'errorformat' option - see
607that for details. You may need to change 'grepformat' from the default if
608your grep outputs in a non-standard format, or you are using some other
609program with a special format.
610
611Once the results are parsed, Vim loads the first file containing a match and
612jumps to the appropriate line, in the same way that it jumps to a compiler
613error in |quickfix| mode. You can then use the |:cnext|, |:clist|, etc.
614commands to see the other matches.
615
616
Bram Moolenaar86b68352004-12-27 21:59:20 +00006175.4 Using :grep with id-utils
Bram Moolenaar071d4272004-06-13 20:20:40 +0000618
619You can set up :grep to work with the GNU id-utils like this: >
620
621 :set grepprg=lid\ -Rgrep\ -s
622 :set grepformat=%f:%l:%m
623
624then >
625 :grep (regexp)
626
627works just as you'd expect.
628(provided you remembered to mkid first :)
629
630
Bram Moolenaar86b68352004-12-27 21:59:20 +00006315.5 Browsing source code with :vimgrep or :grep
Bram Moolenaar071d4272004-06-13 20:20:40 +0000632
633Using the stack of error lists that Vim keeps, you can browse your files to
634look for functions and the functions they call. For example, suppose that you
635have to add an argument to the read_file() function. You enter this command: >
636
Bram Moolenaar86b68352004-12-27 21:59:20 +0000637 :vimgrep /\<read_file\>/ *.c
Bram Moolenaar071d4272004-06-13 20:20:40 +0000638
639You use ":cn" to go along the list of matches and add the argument. At one
640place you have to get the new argument from a higher level function msg(), and
641need to change that one too. Thus you use: >
642
Bram Moolenaar86b68352004-12-27 21:59:20 +0000643 :vimgrep /\<msg\>/ *.c
Bram Moolenaar071d4272004-06-13 20:20:40 +0000644
645While changing the msg() functions, you find another function that needs to
Bram Moolenaar86b68352004-12-27 21:59:20 +0000646get the argument from a higher level. You can again use ":vimgrep" to find
647these functions. Once you are finished with one function, you can use >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000648
649 :colder
650
651to go back to the previous one.
652
Bram Moolenaar86b68352004-12-27 21:59:20 +0000653This works like browsing a tree: ":vimgrep" goes one level deeper, creating a
Bram Moolenaar071d4272004-06-13 20:20:40 +0000654list of branches. ":colder" goes back to the previous level. You can mix
Bram Moolenaar86b68352004-12-27 21:59:20 +0000655this use of ":vimgrep" and "colder" to browse all the locations in a tree-like
Bram Moolenaar071d4272004-06-13 20:20:40 +0000656way. If you do this consistently, you will find all locations without the
657need to write down a "todo" list.
658
659=============================================================================
6606. Selecting a compiler *compiler-select*
661
662 *:comp* *:compiler* *E666*
663:comp[iler][!] {name} Set options to work with compiler {name}.
664 Without the "!" options are set for the
665 current buffer. With "!" global options are
666 set.
667 If you use ":compiler foo" in "file.foo" and
668 then ":compiler! bar" in another buffer, Vim
669 will keep on using "foo" in "file.foo".
670 {not available when compiled without the
671 |+eval| feature}
672
673
674The Vim plugins in the "compiler" directory will set options to use the
675selected compiler. For ":compiler" local options are set, for ":compiler!"
676global options.
677 *current_compiler*
678To support older Vim versions, the plugins always use "current_compiler" and
679not "b:current_compiler". What the command actually does is the following:
680
681- Delete the "current_compiler" and "b:current_compiler" variables.
682- Define the "CompilerSet" user command. With "!" it does ":set", without "!"
683 it does ":setlocal".
684- Execute ":runtime! compiler/{name}.vim". The plugins are expected to set
685 options with "CompilerSet" and set the "current_compiler" variable to the
686 name of the compiler.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000687- Delete the "CompilerSet" user command.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000688- Set "b:current_compiler" to the value of "current_compiler".
689- Without "!" the old value of "current_compiler" is restored.
690
691
692For writing a compiler plugin, see |write-compiler-plugin|.
693
694
695MANX AZTEC C *quickfix-manx* *compiler-manx*
696
697To use Vim with Manx's Aztec C compiler on the Amiga you should do the
698following:
699- Set the CCEDIT environment variable with the command: >
700 mset "CCEDIT=vim -q"
701- Compile with the -qf option. If the compiler finds any errors, Vim is
702 started and the cursor is positioned on the first error. The error message
703 will be displayed on the last line. You can go to other errors with the
704 commands mentioned above. You can fix the errors and write the file(s).
705- If you exit Vim normally the compiler will re-compile the same file. If you
706 exit with the :cq command, the compiler will terminate. Do this if you
707 cannot fix the error, or if another file needs to be compiled first.
708
709There are some restrictions to the Quickfix mode on the Amiga. The
710compiler only writes the first 25 errors to the errorfile (Manx's
711documentation does not say how to get more). If you want to find the others,
712you will have to fix a few errors and exit the editor. After recompiling,
713up to 25 remaining errors will be found.
714
715If Vim was started from the compiler, the :sh and some :! commands will not
716work, because Vim is then running in the same process as the compiler and
717stdin (standard input) will not be interactive.
718
719
720PYUNIT COMPILER *compiler-pyunit*
721
722This is not actually a compiler, but a unit testing framework for the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000723Python language. It is included into standard Python distribution
724starting from version 2.0. For older versions, you can get it from
Bram Moolenaar071d4272004-06-13 20:20:40 +0000725http://pyunit.sourceforge.net.
726
727When you run your tests with the help of the framework, possible errors
728are parsed by Vim and presented for you in quick-fix mode.
729
730Unfortunately, there is no standard way to run the tests.
731The alltests.py script seems to be used quite often, that's all.
732Useful values for the 'makeprg' options therefore are:
733 setlocal makeprg=./alltests.py " Run a testsuite
734 setlocal makeprg=python % " Run a single testcase
735
736Also see http://vim.sourceforge.net/tip_view.php?tip_id=280.
737
738
739TEX COMPILER *compiler-tex*
740
741Included in the distribution compiler for TeX ($VIMRUNTIME/compiler/tex.vim)
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000742uses make command if possible. If the compiler finds a file named "Makefile"
Bram Moolenaar071d4272004-06-13 20:20:40 +0000743or "makefile" in the current directory, it supposes that you want to process
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000744your *TeX files with make, and the makefile does the right work. In this case
745compiler sets 'errorformat' for *TeX output and leaves 'makeprg' untouched. If
Bram Moolenaar071d4272004-06-13 20:20:40 +0000746neither "Makefile" nor "makefile" is found, the compiler will not use make.
747You can force the compiler to ignore makefiles by defining
748b:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked for
749existence only).
750
751If the compiler chose not to use make, it need to choose a right program for
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000752processing your input. If b:tex_flavor or g:tex_flavor (in this precedence)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000753variable exists, it defines TeX flavor for :make (actually, this is the name
754of executed command), and if both variables do not exist, it defaults to
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000755"latex". For example, while editing chapter2.tex \input-ed from mypaper.tex
Bram Moolenaar071d4272004-06-13 20:20:40 +0000756written in AMS-TeX: >
757
758 :let b:tex_flavor = 'amstex'
759 :compiler tex
760< [editing...] >
761 :make mypaper
762
763Note that you must specify a name of the file to process as an argument (to
764process the right file when editing \input-ed or \include-ed file; portable
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000765solution for substituting % for no arguments is welcome). This is not in the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000766semantics of make, where you specify a target, not source, but you may specify
767filename without extension ".tex" and mean this as "make filename.dvi or
768filename.pdf or filename.some_result_extension according to compiler".
769
770Note: tex command line syntax is set to usable both for MikTeX (suggestion
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000771by Srinath Avadhanula) and teTeX (checked by Artem Chuprina). Suggestion
Bram Moolenaar071d4272004-06-13 20:20:40 +0000772from |errorformat-LaTeX| is too complex to keep it working for different
773shells and OSes and also does not allow to use other available TeX options,
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000774if any. If your TeX doesn't support "-interaction=nonstopmode", please
Bram Moolenaar071d4272004-06-13 20:20:40 +0000775report it with different means to express \nonstopmode from the command line.
776
777=============================================================================
7787. The error format *error-file-format*
779
780 *errorformat* *E372* *E373* *E374*
781 *E375* *E376* *E377* *E378*
782The 'errorformat' option specifies a list of formats that are recognized. The
783first format that matches with an error message is used. You can add several
784formats for different messages your compiler produces, or even entries for
785multiple compilers. See |efm-entries|.
786
787Each entry in 'errorformat' is a scanf-like string that describes the format.
788First, you need to know how scanf works. Look in the documentation of your
789C compiler. Below you find the % items that Vim understands. Others are
790invalid.
791
792Special characters in 'errorformat' are comma and backslash. See
793|efm-entries| for how to deal with them. Note that a literal "%" is matched
794by "%%", thus it is not escaped with a backslash.
795
796Note: By default the difference between upper and lowercase is ignored. If
797you want to match case, add "\C" to the pattern |/\C|.
798
799
800Basic items
801
802 %f file name (finds a string)
803 %l line number (finds a number)
804 %c column number (finds a number representing character
805 column of the error, (1 <tab> == 1 character column))
806 %v virtual column number (finds a number representing
807 screen column of the error (1 <tab> == 8 screen
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000808 columns))
Bram Moolenaar071d4272004-06-13 20:20:40 +0000809 %t error type (finds a single character)
810 %n error number (finds a number)
811 %m error message (finds a string)
812 %r matches the "rest" of a single-line file message %O/P/Q
813 %p pointer line (finds a sequence of '-', '.' or ' ' and
814 uses the length for the column number)
815 %*{conv} any scanf non-assignable conversion
816 %% the single '%' character
Bram Moolenaar2641f772005-03-25 21:58:17 +0000817 %s search text (finds a string)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000818
Bram Moolenaare344bea2005-09-01 20:46:49 +0000819The "%f" conversion may depend on the current 'isfname' setting. "~/" is
Bram Moolenaarf4630b62005-05-20 21:31:17 +0000820expanded to the home directory and environment variables are expanded.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000821
Bram Moolenaare344bea2005-09-01 20:46:49 +0000822The "%f" and "%m" conversions have to detect the end of the string. This
Bram Moolenaar482aaeb2005-09-29 18:26:07 +0000823normally happens by matching following characters and items. When nothing is
Bram Moolenaare344bea2005-09-01 20:46:49 +0000824following the rest of the line is matched. If "%f" is followed by a '%' or a
825backslash, it will look for a sequence of 'isfname' characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000826
827On MS-DOS, MS-Windows and OS/2 a leading "C:" will be included in "%f", even
828when using "%f:". This means that a file name which is a single alphabetical
829letter will not be detected.
830
831The "%p" conversion is normally followed by a "^". It's used for compilers
832that output a line like: >
833 ^
834or >
835 ---------^
836to indicate the column of the error. This is to be used in a multi-line error
837message. See |errorformat-javac| for a useful example.
838
Bram Moolenaar2641f772005-03-25 21:58:17 +0000839The "%s" conversion specifies the text to search for to locate the error line.
840The text is used as a literal string. The anchors "^" and "$" are added to
841the text to locate the error line exactly matching the search text and the
842text is prefixed with the "\V" atom to make it "very nomagic". The "%s"
843conversion can be used to locate lines without a line number in the error
844output. Like the output of the "grep" shell command.
845When the pattern is present the line number will not be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000846
847Changing directory
848
849The following uppercase conversion characters specify the type of special
850format strings. At most one of them may be given as a prefix at the begin
851of a single comma-separated format pattern.
852Some compilers produce messages that consist of directory names that have to
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000853be prepended to each file name read by %f (example: GNU make). The following
Bram Moolenaar071d4272004-06-13 20:20:40 +0000854codes can be used to scan these directory names; they will be stored in an
855internal directory stack. *E379*
856 %D "enter directory" format string; expects a following
857 %f that finds the directory name
858 %X "leave directory" format string; expects following %f
859
860When defining an "enter directory" or "leave directory" format, the "%D" or
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000861"%X" has to be given at the start of that substring. Vim tracks the directory
Bram Moolenaar071d4272004-06-13 20:20:40 +0000862changes and prepends the current directory to each erroneous file found with a
863relative path. See |quickfix-directory-stack| for details, tips and
864limitations.
865
866
867Multi-line messages *errorformat-multi-line*
868
869It is possible to read the output of programs that produce multi-line
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000870messages, i.e. error strings that consume more than one line. Possible
Bram Moolenaar071d4272004-06-13 20:20:40 +0000871prefixes are:
872 %E start of a multi-line error message
873 %W start of a multi-line warning message
874 %I start of a multi-line informational message
875 %A start of a multi-line message (unspecified type)
876 %C continuation of a multi-line message
877 %Z end of a multi-line message
878These can be used with '+' and '-', see |efm-ignore| below.
879
880Example: Your compiler happens to write out errors in the following format
881(leading line numbers not being part of the actual output):
882
883 1 Error 275
884 2 line 42
885 3 column 3
886 4 ' ' expected after '--'
887
888The appropriate error format string has to look like this: >
889 :set efm=%EError\ %n,%Cline\ %l,%Ccolumn\ %c,%Z%m
890
891And the |:clist| error message generated for this error is:
892
893 1:42 col 3 error 275: ' ' expected after '--'
894
895Another example: Think of a Python interpreter that produces the following
896error message (line numbers are not part of the actual output):
897
898 1 ==============================================================
899 2 FAIL: testGetTypeIdCachesResult (dbfacadeTest.DjsDBFacadeTest)
900 3 --------------------------------------------------------------
901 4 Traceback (most recent call last):
902 5 File "unittests/dbfacadeTest.py", line 89, in testFoo
903 6 self.assertEquals(34, dtid)
904 7 File "/usr/lib/python2.2/unittest.py", line 286, in
905 8 failUnlessEqual
906 9 raise self.failureException, \
907 10 AssertionError: 34 != 33
908 11
909 12 --------------------------------------------------------------
910 13 Ran 27 tests in 0.063s
911
912Say you want |:clist| write the relevant information of this message only,
913namely:
914 5 unittests/dbfacadeTest.py:89: AssertionError: 34 != 33
915
916Then the error format string could be defined as follows: >
917 :set efm=%C\ %.%#,%A\ \ File\ \"%f\"\\,\ line\ %l%.%#,%Z%[%^\ ]%\\@=%m
918
919Note that the %C string is given before the %A here: since the expression
920' %.%#' (which stands for the regular expression ' .*') matches every line
921starting with a space, followed by any characters to the end of the line,
922it also hides line 7 which would trigger a separate error message otherwise.
923Error format strings are always parsed pattern by pattern until the first
924match occurs.
925
926
927Separate file name *errorformat-separate-filename*
928
929These prefixes are useful if the file name is given once and multiple messages
930follow that refer to this file name.
931 %O single-line file message: overread the matched part
932 %P single-line file message: push file %f onto the stack
933 %Q single-line file message: pop the last file from stack
934
935Example: Given a compiler that produces the following error logfile (without
936leading line numbers):
937
938 1 [a1.tt]
939 2 (1,17) error: ';' missing
940 3 (21,2) warning: variable 'z' not defined
941 4 (67,3) error: end of file found before string ended
942 5
943 6 [a2.tt]
944 7
945 8 [a3.tt]
946 9 NEW compiler v1.1
947 10 (2,2) warning: variable 'x' not defined
948 11 (67,3) warning: 's' already defined
949
950This logfile lists several messages for each file enclosed in [...] which are
951properly parsed by an error format like this: >
952 :set efm=%+P[%f],(%l\\,%c)%*[\ ]%t%*[^:]:\ %m,%-Q
953
954A call of |:clist| writes them accordingly with their correct filenames:
955
956 2 a1.tt:1 col 17 error: ';' missing
957 3 a1.tt:21 col 2 warning: variable 'z' not defined
958 4 a1.tt:67 col 3 error: end of file found before string ended
959 8 a3.tt:2 col 2 warning: variable 'x' not defined
960 9 a3.tt:67 col 3 warning: 's' already defined
961
962Unlike the other prefixes that all match against whole lines, %P, %Q and %O
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000963can be used to match several patterns in the same line. Thus it is possible
Bram Moolenaar071d4272004-06-13 20:20:40 +0000964to parse even nested files like in the following line:
965 {"file1" {"file2" error1} error2 {"file3" error3 {"file4" error4 error5}}}
966The %O then parses over strings that do not contain any push/pop file name
967information. See |errorformat-LaTeX| for an extended example.
968
969
970Ignoring and using whole messages *efm-ignore*
971
972The codes '+' or '-' can be combined with the uppercase codes above; in that
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000973case they have to precede the letter, e.g. '%+A' or '%-G':
Bram Moolenaar071d4272004-06-13 20:20:40 +0000974 %- do not include the matching multi-line in any output
975 %+ include the whole matching line in the %m error string
976
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000977One prefix is only useful in combination with '+' or '-', namely %G. It parses
Bram Moolenaar071d4272004-06-13 20:20:40 +0000978over lines containing general information like compiler version strings or
979other headers that can be skipped.
980 %-G ignore this message
981 %+G general message
982
983
984Pattern matching
985
986The scanf()-like "%*[]" notation is supported for backward-compatibility
987with previous versions of Vim. However, it is also possible to specify
988(nearly) any Vim supported regular expression in format strings.
989Since meta characters of the regular expression language can be part of
990ordinary matching strings or file names (and therefore internally have to
991be escaped), meta symbols have to be written with leading '%':
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000992 %\ the single '\' character. Note that this has to be
Bram Moolenaar071d4272004-06-13 20:20:40 +0000993 escaped ("%\\") in ":set errorformat=" definitions.
994 %. the single '.' character.
995 %# the single '*'(!) character.
996 %^ the single '^' character.
997 %$ the single '$' character.
998 %[ the single '[' character for a [] character range.
999 %~ the single '~' character.
1000When using character classes in expressions (see |/\i| for an overview),
1001terms containing the "\+" quantifier can be written in the scanf() "%*"
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001002notation. Example: "%\\d%\\+" ("\d\+", "any number") is equivalent to "%*\\d".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001003Important note: The \(...\) grouping of sub-matches can not be used in format
1004specifications because it is reserved for internal conversions.
1005
1006
1007Multiple entries in 'errorformat' *efm-entries*
1008
1009To be able to detect output from several compilers, several format patterns
1010may be put in 'errorformat', separated by commas (note: blanks after the comma
1011are ignored). The first pattern that has a complete match is used. If no
1012match is found, matching parts from the last one will be used, although the
1013file name is removed and the error message is set to the whole message. If
1014there is a pattern that may match output from several compilers (but not in a
1015right way), put it after one that is more restrictive.
1016
1017To include a comma in a pattern precede it with a backslash (you have to type
1018two in a ":set" command). To include a backslash itself give two backslashes
1019(you have to type four in a ":set" command). You also need to put a backslash
1020before a space for ":set".
1021
1022
1023Valid matches *quickfix-valid*
1024
1025If a line does not completely match one of the entries in 'errorformat', the
1026whole line is put in the error message and the entry is marked "not valid"
1027These lines are skipped with the ":cn" and ":cp" commands (unless there is
1028no valid line at all). You can use ":cl!" to display all the error messages.
1029
1030If the error format does not contain a file name Vim cannot switch to the
1031correct file. You will have to do this by hand.
1032
1033
1034Examples
1035
1036The format of the file from the Amiga Aztec compiler is:
1037
1038 filename>linenumber:columnnumber:errortype:errornumber:errormessage
1039
1040 filename name of the file in which the error was detected
1041 linenumber line number where the error was detected
1042 columnnumber column number where the error was detected
1043 errortype type of the error, normally a single 'E' or 'W'
1044 errornumber number of the error (for lookup in the manual)
1045 errormessage description of the error
1046
1047This can be matched with this 'errorformat' entry:
1048 %f>%l:%c:%t:%n:%m
1049
1050Some examples for C compilers that produce single-line error outputs:
1051%f:%l:\ %t%*[^0123456789]%n:\ %m for Manx/Aztec C error messages
1052 (scanf() doesn't understand [0-9])
1053%f\ %l\ %t%*[^0-9]%n:\ %m for SAS C
1054\"%f\"\\,%*[^0-9]%l:\ %m for generic C compilers
1055%f:%l:\ %m for GCC
1056%f:%l:\ %m,%Dgmake[%*\\d]:\ Entering\ directory\ `%f',
1057%Dgmake[%*\\d]:\ Leaving\ directory\ `%f'
1058 for GCC with gmake (concat the lines!)
1059%f(%l)\ :\ %*[^:]:\ %m old SCO C compiler (pre-OS5)
1060%f(%l)\ :\ %t%*[^0-9]%n:\ %m idem, with error type and number
1061%f:%l:\ %m,In\ file\ included\ from\ %f:%l:,\^I\^Ifrom\ %f:%l%m
1062 for GCC, with some extras
1063
1064Extended examples for the handling of multi-line messages are given below,
1065see |errorformat-Jikes| and |errorformat-LaTeX|.
1066
1067Note the backslash in front of a space and double quote. It is required for
1068the :set command. There are two backslashes in front of a comma, one for the
1069:set command and one to avoid recognizing the comma as a separator of error
1070formats.
1071
1072
1073Filtering messages
1074
1075If you have a compiler that produces error messages that do not fit in the
1076format string, you could write a program that translates the error messages
1077into this format. You can use this program with the ":make" command by
1078changing the 'makeprg' option. For example: >
1079 :set mp=make\ \\\|&\ error_filter
1080The backslashes before the pipe character are required to avoid it to be
1081recognized as a command separator. The backslash before each space is
1082required for the set command.
1083
1084=============================================================================
10858. The directory stack *quickfix-directory-stack*
1086
1087Quickfix maintains a stack for saving all used directories parsed from the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001088make output. For GNU-make this is rather simple, as it always prints the
1089absolute path of all directories it enters and leaves. Regardless if this is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001090done via a 'cd' command in the makefile or with the parameter "-C dir" (change
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001091to directory before reading the makefile). It may be useful to use the switch
Bram Moolenaar071d4272004-06-13 20:20:40 +00001092"-w" to force GNU-make to print out the working directory before and after
1093processing.
1094
1095Maintaining the correct directory is more complicated if you don't use
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001096GNU-make. AIX-make for example doesn't print any information about its
1097working directory. Then you need to enhance the makefile. In the makefile of
1098LessTif there is a command which echoes "Making {target} in {dir}". The
1099special problem here is that it doesn't print informations on leaving the
1100directory and that it doesn't print the absolute path.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001101
1102To solve the problem with relative paths and missing "leave directory"
1103messages Vim uses following algorithm:
1104
11051) Check if the given directory is a subdirectory of the current directory.
1106 If this is true, store it as the current directory.
11072) If it is not a subdir of the current directory, try if this is a
1108 subdirectory of one of the upper directories.
11093) If the directory still isn't found, it is assumed to be a subdirectory
1110 of Vim's current directory.
1111
1112Additionally it is checked for every file, if it really exists in the
1113identified directory. If not, it is searched in all other directories of the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001114directory stack (NOT the directory subtree!). If it is still not found, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001115assumed that it is in Vim's current directory.
1116
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001117There are limitation in this algorithm. This examples assume that make just
Bram Moolenaar071d4272004-06-13 20:20:40 +00001118prints information about entering a directory in the form "Making all in dir".
1119
11201) Assume you have following directories and files:
1121 ./dir1
1122 ./dir1/file1.c
1123 ./file1.c
1124
1125 If make processes the directory "./dir1" before the current directory and
1126 there is an error in the file "./file1.c", you will end up with the file
1127 "./dir1/file.c" loaded by Vim.
1128
1129 This can only be solved with a "leave directory" message.
1130
11312) Assume you have following directories and files:
1132 ./dir1
1133 ./dir1/dir2
1134 ./dir2
1135
1136 You get the following:
1137
1138 Make output Directory interpreted by Vim
1139 ------------------------ ----------------------------
1140 Making all in dir1 ./dir1
1141 Making all in dir2 ./dir1/dir2
1142 Making all in dir2 ./dir1/dir2
1143
1144 This can be solved by printing absolute directories in the "enter directory"
1145 message or by printing "leave directory" messages..
1146
1147To avoid this problems, ensure to print absolute directory names and "leave
1148directory" messages.
1149
1150Examples for Makefiles:
1151
1152Unix:
1153 libs:
1154 for dn in $(LIBDIRS); do \
1155 (cd $$dn; echo "Entering dir '$$(pwd)'"; make); \
1156 echo "Leaving dir"; \
1157 done
1158
1159Add
1160 %DEntering\ dir\ '%f',%XLeaving\ dir
1161to your 'errorformat' to handle the above output.
1162
1163Note that Vim doesn't check if the directory name in a "leave directory"
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001164messages is the current directory. This is why you could just use the message
Bram Moolenaar071d4272004-06-13 20:20:40 +00001165"Leaving dir".
1166
1167=============================================================================
11689. Specific error file formats *errorformats*
1169
1170 *errorformat-Jikes*
1171Jikes(TM), a source-to-bytecode Java compiler published by IBM Research,
1172produces simple multi-line error messages.
1173
1174An 'errorformat' string matching the produced messages is shown below.
1175The following lines can be placed in the user's |vimrc| to overwrite Vim's
1176recognized default formats, or see |:set+=| how to install this format
1177additionally to the default. >
1178
1179 :set efm=%A%f:%l:%c:%*\\d:%*\\d:,
1180 \%C%*\\s%trror:%m,
1181 \%+C%*[^:]%trror:%m,
1182 \%C%*\\s%tarning:%m,
1183 \%C%m
1184<
1185Jikes(TM) produces a single-line error message when invoked with the option
1186"+E", and can be matched with the following: >
1187
1188 :set efm=%f:%l:%v:%*\\d:%*\\d:%*\\s%m
1189<
1190 *errorformat-javac*
1191This 'errorformat' has been reported to work well for javac, which outputs a
1192line with "^" to indicate the column of the error: >
1193 :set efm=%A%f:%l:\ %m,%-Z%p^,%-C%.%#
1194or: >
1195 :set efm=%A%f:%l:\ %m,%+Z%p^,%+C%.%#,%-G%.%#
1196<
1197 *errorformat-ant*
1198For ant (http://jakarta.apache.org/) the above errorformat has to be modified
1199to honour the leading [javac] in front of each javac output line: >
1200 :set efm=%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#
1201
1202The 'errorformat' can also be configured to handle ant together with either
1203javac or jikes. If you're using jikes, you should tell ant to use jikes' +E
1204command line switch which forces jikes to generate one-line error messages.
1205This is what the second line (of a build.xml file) below does: >
1206 <property name = "build.compiler" value = "jikes"/>
1207 <property name = "build.compiler.emacs" value = "true"/>
1208
1209The 'errorformat' which handles ant with both javac and jikes is: >
1210 :set efm=\ %#[javac]\ %#%f:%l:%c:%*\\d:%*\\d:\ %t%[%^:]%#:%m,
1211 \%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#
1212<
1213 *errorformat-jade*
1214parsing jade (see http://www.jclark.com/) errors is simple: >
1215 :set efm=jade:%f:%l:%c:%t:%m
1216<
1217 *errorformat-LaTeX*
1218The following is an example how an 'errorformat' string can be specified
1219for the (La)TeX typesetting system which displays error messages over
1220multiple lines. The output of ":clist" and ":cc" etc. commands displays
1221multi-lines in a single line, leading white space is removed.
1222It should be easy to adopt the above LaTeX errorformat to any compiler output
1223consisting of multi-line errors.
1224
1225The commands can be placed in a |vimrc| file or some other Vim script file,
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001226e.g. a script containing LaTeX related stuff which is loaded only when editing
Bram Moolenaar071d4272004-06-13 20:20:40 +00001227LaTeX sources.
1228Make sure to copy all lines of the example (in the given order), afterwards
1229remove the comment lines. For the '\' notation at the start of some lines see
1230|line-continuation|.
1231
1232 First prepare 'makeprg' such that LaTeX will report multiple
1233 errors; do not stop when the first error has occurred: >
1234 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
1235<
1236 Start of multi-line error messages: >
1237 :set efm=%E!\ LaTeX\ %trror:\ %m,
1238 \%E!\ %m,
1239< Start of multi-line warning messages; the first two also
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001240 include the line number. Meaning of some regular expressions:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001241 - "%.%#" (".*") matches a (possibly empty) string
1242 - "%*\\d" ("\d\+") matches a number >
1243 \%+WLaTeX\ %.%#Warning:\ %.%#line\ %l%.%#,
1244 \%+W%.%#\ at\ lines\ %l--%*\\d,
1245 \%WLaTeX\ %.%#Warning:\ %m,
1246< Possible continuations of error/warning messages; the first
1247 one also includes the line number: >
1248 \%Cl.%l\ %m,
1249 \%+C\ \ %m.,
1250 \%+C%.%#-%.%#,
1251 \%+C%.%#[]%.%#,
1252 \%+C[]%.%#,
1253 \%+C%.%#%[{}\\]%.%#,
1254 \%+C<%.%#>%.%#,
1255 \%C\ \ %m,
1256< Lines that match the following patterns do not contain any
1257 important information; do not include them in messages: >
1258 \%-GSee\ the\ LaTeX%m,
1259 \%-GType\ \ H\ <return>%m,
1260 \%-G\ ...%.%#,
1261 \%-G%.%#\ (C)\ %.%#,
1262 \%-G(see\ the\ transcript%.%#),
1263< Generally exclude any empty or whitespace-only line from
1264 being displayed: >
1265 \%-G\\s%#,
1266< The LaTeX output log does not specify the names of erroneous
1267 source files per line; rather they are given globally,
1268 enclosed in parentheses.
1269 The following patterns try to match these names and store
1270 them in an internal stack. The patterns possibly scan over
1271 the same input line (one after another), the trailing "%r"
1272 conversion indicates the "rest" of the line that will be
1273 parsed in the next go until the end of line is reached.
1274
1275 Overread a file name enclosed in '('...')'; do not push it
1276 on a stack since the file apparently does not contain any
1277 error: >
1278 \%+O(%f)%r,
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001279< Push a file name onto the stack. The name is given after '(': >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001280 \%+P(%f%r,
1281 \%+P\ %\\=(%f%r,
1282 \%+P%*[^()](%f%r,
1283 \%+P[%\\d%[^()]%#(%f%r,
1284< Pop the last stored file name when a ')' is scanned: >
1285 \%+Q)%r,
1286 \%+Q%*[^()])%r,
1287 \%+Q[%\\d%*[^()])%r
1288
1289Note that in some cases file names in the LaTeX output log cannot be parsed
1290properly. The parser might have been messed up by unbalanced parentheses
1291then. The above example tries to catch the most relevant cases only.
1292You can customize the given setting to suit your own purposes, for example,
1293all the annoying "Overfull ..." warnings could be excluded from being
1294recognized as an error.
1295Alternatively to filtering the LaTeX compiler output, it is also possible
1296to directly read the *.log file that is produced by the [La]TeX compiler.
1297This contains even more useful information about possible error causes.
1298However, to properly parse such a complex file, an external filter should
1299be used. See the description further above how to make such a filter known
1300by Vim.
1301
1302 *errorformat-Perl*
1303In $VIMRUNTIME/tools you can find the efm_perl.pl script, which filters Perl
1304error messages into a format that quickfix mode will understand. See the
1305start of the file about how to use it.
1306
1307
1308
1309 vim:tw=78:ts=8:ft=help:norl: