|
874
|
1 *tagsrch.txt* For Vim version 7.0. Last change: 2006 Apr 24
|
|
7
|
2
|
|
|
3
|
|
|
4 VIM REFERENCE MANUAL by Bram Moolenaar
|
|
|
5
|
|
|
6
|
|
|
7 Tags and special searches *tags-and-searches*
|
|
|
8
|
|
|
9 See section |29.1| of the user manual for an introduction.
|
|
|
10
|
|
|
11 1. Jump to a tag |tag-commands|
|
|
|
12 2. Tag stack |tag-stack|
|
|
|
13 3. Tag match list |tag-matchlist|
|
|
|
14 4. Tags details |tag-details|
|
|
|
15 5. Tags file format |tags-file-format|
|
|
|
16 6. Include file searches |include-search|
|
|
|
17
|
|
|
18 ==============================================================================
|
|
|
19 1. Jump to a tag *tag-commands*
|
|
|
20
|
|
|
21 *tag* *tags*
|
|
|
22 A tag is an identifier that appears in a "tags" file. It is a sort of label
|
|
|
23 that can be jumped to. For example: In C programs each function name can be
|
|
|
24 used as a tag. The "tags" file has to be generated by a program like ctags,
|
|
|
25 before the tag commands can be used.
|
|
|
26
|
|
|
27 With the ":tag" command the cursor will be positioned on the tag. With the
|
|
|
28 CTRL-] command, the keyword on which the cursor is standing is used as the
|
|
|
29 tag. If the cursor is not on a keyword, the first keyword to the right of the
|
|
|
30 cursor is used.
|
|
|
31
|
|
|
32 The ":tag" command works very well for C programs. If you see a call to a
|
|
|
33 function and wonder what that function does, position the cursor inside of the
|
|
|
34 function name and hit CTRL-]. This will bring you to the function definition.
|
|
|
35 An easy way back is with the CTRL-T command. Also read about the tag stack
|
|
|
36 below.
|
|
|
37
|
|
|
38 *:ta* *:tag* *E426* *E429*
|
|
685
|
39 :[count]ta[g][!] {ident}
|
|
|
40 Jump to the definition of {ident}, using the
|
|
7
|
41 information in the tags file(s). Put {ident} in the
|
|
|
42 tag stack. See |tag-!| for [!].
|
|
|
43 {ident} can be a regexp pattern, see |tag-regexp|.
|
|
685
|
44 When there are several matching tags for {ident}, jump
|
|
|
45 to the [count] one. When [count] is omitted the
|
|
|
46 first one is jumped to. See |tag-matchlist| for
|
|
|
47 jumping to other matching tags.
|
|
7
|
48
|
|
|
49 g<LeftMouse> *g<LeftMouse>*
|
|
|
50 <C-LeftMouse> *<C-LeftMouse>* *CTRL-]*
|
|
|
51 CTRL-] Jump to the definition of the keyword under the
|
|
|
52 cursor. Same as ":tag {ident}", where {ident} is the
|
|
685
|
53 keyword under or after cursor.
|
|
|
54 When there are several matching tags for {ident}, jump
|
|
|
55 to the [count] one. When no [count] is given the
|
|
|
56 first one is jumped to. See |tag-matchlist| for
|
|
|
57 jumping to other matching tags.
|
|
|
58 {Vi: identifier after the cursor}
|
|
7
|
59
|
|
|
60 *v_CTRL-]*
|
|
|
61 {Visual}CTRL-] Same as ":tag {ident}", where {ident} is the text that
|
|
|
62 is highlighted. {not in Vi}
|
|
|
63
|
|
|
64 *telnet-CTRL-]*
|
|
|
65 CTRL-] is the default telnet escape key. When you type CTRL-] to jump to a
|
|
|
66 tag, you will get the telnet prompt instead. Most versions of telnet allow
|
|
|
67 changing or disabling the default escape key. See the telnet man page. You
|
|
|
68 can 'telnet -E {Hostname}' to disable the escape character, or 'telnet -e
|
|
|
69 {EscapeCharacter} {Hostname}' to specify another escape character. If
|
|
56
|
70 possible, try to use "ssh" instead of "telnet" to avoid this problem.
|
|
7
|
71
|
|
|
72 *tag-priority*
|
|
|
73 When there are multiple matches for a tag, this priority is used:
|
|
|
74 1. "FSC" A full matching static tag for the current file.
|
|
|
75 2. "F C" A full matching global tag for the current file.
|
|
|
76 3. "F " A full matching global tag for another file.
|
|
|
77 4. "FS " A full matching static tag for another file.
|
|
|
78 5. " SC" An ignore-case matching static tag for the current file.
|
|
|
79 6. " C" An ignore-case matching global tag for the current file.
|
|
|
80 7. " " An ignore-case matching global tag for another file.
|
|
|
81 8. " S " An ignore-case matching static tag for another file.
|
|
|
82
|
|
|
83 Note that when the current file changes, the priority list is mostly not
|
|
|
84 changed, to avoid confusion when using ":tnext". It is changed when using
|
|
|
85 ":tag {ident}".
|
|
|
86
|
|
|
87 The ignore-case matches are not found for a ":tag" command when the
|
|
|
88 'ignorecase' option is off. They are found when a pattern is used (starting
|
|
|
89 with a "/") and for ":tselect", also when 'ignorecase' is off. Note that
|
|
|
90 using ignore-case tag searching disables binary searching in the tags file,
|
|
|
91 which causes a slowdown. This can be avoided by fold-case sorting the tag
|
|
|
92 file. See the 'tagbsearch' option for an explanation.
|
|
|
93
|
|
|
94 ==============================================================================
|
|
|
95 2. Tag stack *tag-stack* *tagstack* *E425*
|
|
|
96
|
|
|
97 On the tag stack is remembered which tags you jumped to, and from where.
|
|
|
98 Tags are only pushed onto the stack when the 'tagstack' option is set.
|
|
|
99
|
|
|
100 g<RightMouse> *g<RightMouse>*
|
|
|
101 <C-RightMouse> *<C-RightMouse>* *CTRL-T*
|
|
|
102 CTRL-T Jump to [count] older entry in the tag stack
|
|
|
103 (default 1). {not in Vi}
|
|
|
104
|
|
|
105 *:po* *:pop* *E555* *E556*
|
|
|
106 :[count]po[p][!] Jump to [count] older entry in tag stack (default 1).
|
|
|
107 See |tag-!| for [!]. {not in Vi}
|
|
|
108
|
|
|
109 :[count]ta[g][!] Jump to [count] newer entry in tag stack (default 1).
|
|
|
110 See |tag-!| for [!]. {not in Vi}
|
|
|
111
|
|
|
112 *:tags*
|
|
|
113 :tags Show the contents of the tag stack. The active
|
|
|
114 entry is marked with a '>'. {not in Vi}
|
|
|
115
|
|
|
116 The output of ":tags" looks like this:
|
|
|
117
|
|
|
118 # TO tag FROM line in file/line
|
|
|
119 1 1 main 1 harddisk2:text/vim/test
|
|
|
120 > 2 2 FuncA 58 i = FuncA(10);
|
|
|
121 3 1 FuncC 357 harddisk2:text/vim/src/amiga.c
|
|
|
122
|
|
|
123 This list shows the tags that you jumped to and the cursor position before
|
|
|
124 that jump. The older tags are at the top, the newer at the bottom.
|
|
|
125
|
|
|
126 The '>' points to the active entry. This is the tag that will be used by the
|
|
|
127 next ":tag" command. The CTRL-T and ":pop" command will use the position
|
|
|
128 above the active entry.
|
|
|
129
|
|
|
130 Below the "TO" is the number of the current match in the match list. Note
|
|
|
131 that this doesn't change when using ":pop" or ":tag".
|
|
|
132
|
|
|
133 The line number and file name are remembered to be able to get back to where
|
|
|
134 you were before the tag command. The line number will be correct, also when
|
|
|
135 deleting/inserting lines, unless this was done by another program (e.g.
|
|
|
136 another instance of Vim).
|
|
|
137
|
|
|
138 For the current file, the "file/line" column shows the text at the position.
|
|
|
139 An indent is removed and a long line is truncated to fit in the window.
|
|
|
140
|
|
|
141 You can jump to previously used tags with several commands. Some examples:
|
|
|
142
|
|
|
143 ":pop" or CTRL-T to position before previous tag
|
|
|
144 {count}CTRL-T to position before {count} older tag
|
|
|
145 ":tag" to newer tag
|
|
|
146 ":0tag" to last used tag
|
|
|
147
|
|
|
148 The most obvious way to use this is while browsing through the call graph of
|
|
|
149 a program. Consider the following call graph:
|
|
|
150
|
|
|
151 main ---> FuncA ---> FuncC
|
|
|
152 ---> FuncB
|
|
|
153
|
|
|
154 (Explanation: main calls FuncA and FuncB; FuncA calls FuncC).
|
|
|
155 You can get from main to FuncA by using CTRL-] on the call to FuncA. Then
|
|
|
156 you can CTRL-] to get to FuncC. If you now want to go back to main you can
|
|
|
157 use CTRL-T twice. Then you can CTRL-] to FuncB.
|
|
|
158
|
|
|
159 If you issue a ":ta {ident}" or CTRL-] command, this tag is inserted at the
|
|
|
160 current position in the stack. If the stack was full (it can hold up to 20
|
|
|
161 entries), the oldest entry is deleted and the older entries shift one
|
|
|
162 position up (their index number is decremented by one). If the last used
|
|
|
163 entry was not at the bottom, the entries below the last used one are
|
|
|
164 deleted. This means that an old branch in the call graph is lost. After the
|
|
|
165 commands explained above the tag stack will look like this:
|
|
|
166
|
|
|
167 # TO tag FROM line in file
|
|
|
168 1 main 1 harddisk2:text/vim/test
|
|
|
169 2 FuncB 59 harddisk2:text/vim/src/main.c
|
|
|
170
|
|
|
171 *E73*
|
|
|
172 When you try to use the tag stack while it doesn't contain anything you will
|
|
|
173 get an error message.
|
|
|
174
|
|
|
175 ==============================================================================
|
|
|
176 3. Tag match list *tag-matchlist* *E427* *E428*
|
|
|
177
|
|
|
178 When there are several matching tags, these commands can be used to jump
|
|
|
179 between them. Note that these command don't change the tag stack, they keep
|
|
|
180 the same entry.
|
|
|
181
|
|
|
182 *:ts* *:tselect*
|
|
|
183 :ts[elect][!] [ident] List the tags that match [ident], using the
|
|
|
184 information in the tags file(s).
|
|
|
185 When [ident] is not given, the last tag name from the
|
|
|
186 tag stack is used.
|
|
|
187 With a '>' in the first column is indicated which is
|
|
|
188 the current position in the list (if there is one).
|
|
|
189 [ident] can be a regexp pattern, see |tag-regexp|.
|
|
|
190 See |tag-priority| for the priorities used in the
|
|
|
191 listing. {not in Vi}
|
|
|
192 Example output:
|
|
|
193
|
|
|
194 >
|
|
|
195 nr pri kind tag file
|
|
|
196 1 F f mch_delay os_amiga.c
|
|
|
197 mch_delay(msec, ignoreinput)
|
|
|
198 > 2 F f mch_delay os_msdos.c
|
|
|
199 mch_delay(msec, ignoreinput)
|
|
|
200 3 F f mch_delay os_unix.c
|
|
|
201 mch_delay(msec, ignoreinput)
|
|
|
202 Enter nr of choice (<CR> to abort):
|
|
|
203 <
|
|
|
204 See |tag-priority| for the "pri" column. Note that
|
|
|
205 this depends on the current file, thus using
|
|
|
206 ":tselect xxx" can produce different results.
|
|
|
207 The "kind" column gives the kind of tag, if this was
|
|
|
208 included in the tags file.
|
|
|
209 The "info" column shows information that could be
|
|
|
210 found in the tags file. It depends on the program
|
|
|
211 that produced the tags file.
|
|
|
212 When the list is long, you may get the |more-prompt|.
|
|
|
213 If you already see the tag you want to use, you can
|
|
|
214 type 'q' and enter the number.
|
|
|
215
|
|
|
216 *:sts* *:stselect*
|
|
|
217 :sts[elect][!] [ident] Does ":tselect[!] [ident]" and splits the window for
|
|
|
218 the selected tag. {not in Vi}
|
|
|
219
|
|
|
220 *g]*
|
|
|
221 g] Like CTRL-], but use ":tselect" instead of ":tag".
|
|
|
222 {not in Vi}
|
|
|
223
|
|
|
224 *v_g]*
|
|
|
225 {Visual}g] Same as "g]", but use the highlighted text as the
|
|
|
226 identifier. {not in Vi}
|
|
|
227
|
|
|
228 *:tj* *:tjump*
|
|
|
229 :tj[ump][!] [ident] Like ":tselect", but jump to the tag directly when
|
|
|
230 there is only one match. {not in Vi}
|
|
|
231
|
|
|
232 *:stj* *:stjump*
|
|
|
233 :stj[ump][!] [ident] Does ":tjump[!] [ident]" and splits the window for the
|
|
|
234 selected tag. {not in Vi}
|
|
|
235
|
|
|
236 *g_CTRL-]*
|
|
|
237 g CTRL-] Like CTRL-], but use ":tjump" instead of ":tag".
|
|
|
238 {not in Vi}
|
|
|
239
|
|
|
240 *v_g_CTRL-]*
|
|
|
241 {Visual}g CTRL-] Same as "g CTRL-]", but use the highlighted text as
|
|
|
242 the identifier. {not in Vi}
|
|
|
243
|
|
|
244 *:tn* *:tnext*
|
|
|
245 :[count]tn[ext][!] Jump to [count] next matching tag (default 1). See
|
|
|
246 |tag-!| for [!]. {not in Vi}
|
|
|
247
|
|
|
248 *:tp* *:tprevious*
|
|
|
249 :[count]tp[revious][!] Jump to [count] previous matching tag (default 1).
|
|
|
250 See |tag-!| for [!]. {not in Vi}
|
|
|
251
|
|
|
252 *:tN* *:tNext*
|
|
|
253 :[count]tN[ext][!] Same as ":tprevious". {not in Vi}
|
|
|
254
|
|
|
255 *:tr* *:trewind*
|
|
|
256 :[count]tr[ewind][!] Jump to first matching tag. If [count] is given, jump
|
|
|
257 to [count]th matching tag. See |tag-!| for [!]. {not
|
|
|
258 in Vi}
|
|
|
259
|
|
|
260 *:tf* *:tfirst*
|
|
237
|
261 :[count]tf[irst][!] Same as ":trewind". {not in Vi}
|
|
7
|
262
|
|
|
263 *:tl* *:tlast*
|
|
|
264 :tl[ast][!] Jump to last matching tag. See |tag-!| for [!]. {not
|
|
|
265 in Vi}
|
|
|
266
|
|
651
|
267 *:lt* *:ltag*
|
|
|
268 :lt[ag][!] [ident] Jump to tag [ident] and add the matching tags to a new
|
|
|
269 location list for the current window. [ident] can be
|
|
|
270 a regexp pattern, see |tag-regexp|. When [ident] is
|
|
|
271 not given, the last tag name from the tag stack is
|
|
|
272 used. The search pattern to locate the tag line is
|
|
|
273 prefixed with "\V" to escape all the special
|
|
|
274 characters (very nomagic). The location list showing
|
|
|
275 the matching tags is independent of the tag stack.
|
|
|
276 See |tag-!| for [!].
|
|
|
277 {not in Vi}
|
|
7
|
278
|
|
|
279 When there is no other message, Vim shows which matching tag has been jumped
|
|
|
280 to, and the number of matching tags: >
|
|
|
281 tag 1 of 3 or more
|
|
|
282 The " or more" is used to indicate that Vim didn't try all the tags files yet.
|
|
|
283 When using ":tnext" a few times, or with ":tlast", more matches may be found.
|
|
|
284
|
|
|
285 When you didn't see this message because of some other message, or you just
|
|
|
286 want to know where you are, this command will show it again (and jump to the
|
|
|
287 same tag as last time): >
|
|
|
288 :0tn
|
|
|
289 <
|
|
|
290 *tag-skip-file*
|
|
|
291 When a matching tag is found for which the file doesn't exist, this match is
|
|
|
292 skipped and the next matching tag is used. Vim reports this, to notify you of
|
|
|
293 missing files. When the end of the list of matches has been reached, an error
|
|
|
294 message is given.
|
|
|
295
|
|
651
|
296 *tag-preview*
|
|
7
|
297 The tag match list can also be used in the preview window. The commands are
|
|
|
298 the same as above, with a "p" prepended.
|
|
|
299 {not available when compiled without the |+quickfix| feature}
|
|
|
300
|
|
|
301 *:pts* *:ptselect*
|
|
|
302 :pts[elect][!] [ident] Does ":tselect[!] [ident]" and shows the new tag in a
|
|
237
|
303 "Preview" window. See |:ptag| for more info.
|
|
7
|
304 {not in Vi}
|
|
|
305
|
|
|
306 *:ptj* *:ptjump*
|
|
|
307 :ptj[ump][!] [ident] Does ":tjump[!] [ident]" and shows the new tag in a
|
|
237
|
308 "Preview" window. See |:ptag| for more info.
|
|
7
|
309 {not in Vi}
|
|
|
310
|
|
|
311 *:ptn* *:ptnext*
|
|
|
312 :[count]ptn[ext][!] ":tnext" in the preview window. See |:ptag|.
|
|
|
313 {not in Vi}
|
|
|
314
|
|
|
315 *:ptp* *:ptprevious*
|
|
|
316 :[count]ptp[revious][!] ":tprevious" in the preview window. See |:ptag|.
|
|
|
317 {not in Vi}
|
|
|
318
|
|
|
319 *:ptN* *:ptNext*
|
|
|
320 :[count]ptN[ext][!] Same as ":ptprevious". {not in Vi}
|
|
|
321
|
|
|
322 *:ptr* *:ptrewind*
|
|
|
323 :[count]ptr[ewind][!] ":trewind" in the preview window. See |:ptag|.
|
|
|
324 {not in Vi}
|
|
|
325
|
|
|
326 *:ptf* *:ptfirst*
|
|
237
|
327 :[count]ptf[irst][!] Same as ":ptrewind". {not in Vi}
|
|
7
|
328
|
|
|
329 *:ptl* *:ptlast*
|
|
|
330 :ptl[ast][!] ":tlast" in the preview window. See |:ptag|.
|
|
|
331 {not in Vi}
|
|
|
332
|
|
|
333 ==============================================================================
|
|
|
334 4. Tags details *tag-details*
|
|
|
335
|
|
|
336 *static-tag*
|
|
|
337 A static tag is a tag that is defined for a specific file. In a C program
|
|
|
338 this could be a static function.
|
|
|
339
|
|
|
340 In Vi jumping to a tag sets the current search pattern. This means that
|
|
|
341 the "n" command after jumping to a tag does not search for the same pattern
|
|
|
342 that it did before jumping to the tag. Vim does not do this as we consider it
|
|
|
343 to be a bug. You can still find the tag search pattern in the search history.
|
|
|
344 If you really want the old Vi behavior, set the 't' flag in 'cpoptions'.
|
|
|
345
|
|
|
346 *tag-binary-search*
|
|
|
347 Vim uses binary searching in the tags file to find the desired tag quickly
|
|
|
348 (when enabled at compile time |+tag_binary|). But this only works if the
|
|
|
349 tags file was sorted on ASCII byte value. Therefore, if no match was found,
|
|
|
350 another try is done with a linear search. If you only want the linear search,
|
|
|
351 reset the 'tagbsearch' option. Or better: Sort the tags file!
|
|
|
352
|
|
|
353 Note that the binary searching is disabled when not looking for a tag with a
|
|
|
354 specific name. This happens when ignoring case and when a regular expression
|
|
|
355 is used that doesn't start with a fixed string. Tag searching can be a lot
|
|
|
356 slower then. The former can be avoided by case-fold sorting the tags file.
|
|
|
357 See 'tagbsearch' for details.
|
|
|
358
|
|
|
359 *tag-regexp*
|
|
|
360 The ":tag" and "tselect" commands accept a regular expression argument. See
|
|
|
361 |pattern| for the special characters that can be used.
|
|
|
362 When the argument starts with '/', it is used as a pattern. If the argument
|
|
|
363 does not start with '/', it is taken literally, as a full tag name.
|
|
|
364 Examples: >
|
|
|
365 :tag main
|
|
|
366 < jumps to the tag "main" that has the highest priority. >
|
|
|
367 :tag /^get
|
|
|
368 < jumps to the tag that starts with "get" and has the highest priority. >
|
|
|
369 :tag /norm
|
|
|
370 < lists all the tags that contain "norm", including "id_norm".
|
|
|
371 When the argument both exists literally, and match when used as a regexp, a
|
|
|
372 literal match has a higher priority. For example, ":tag /open" matches "open"
|
|
|
373 before "open_file" and "file_open".
|
|
415
|
374 When using a pattern case is ignored. If you want to match case use "\C" in
|
|
|
375 the pattern.
|
|
7
|
376
|
|
|
377 *tag-!*
|
|
|
378 If the tag is in the current file this will always work. Otherwise the
|
|
|
379 performed actions depend on whether the current file was changed, whether a !
|
|
|
380 is added to the command and on the 'autowrite' option:
|
|
|
381
|
|
|
382 tag in file autowrite ~
|
|
|
383 current file changed ! option action ~
|
|
|
384 -----------------------------------------------------------------------------
|
|
|
385 yes x x x goto tag
|
|
|
386 no no x x read other file, goto tag
|
|
|
387 no yes yes x abandon current file, read other file, goto
|
|
|
388 tag
|
|
|
389 no yes no on write current file, read other file, goto
|
|
|
390 tag
|
|
|
391 no yes no off fail
|
|
|
392 -----------------------------------------------------------------------------
|
|
|
393
|
|
|
394 - If the tag is in the current file, the command will always work.
|
|
|
395 - If the tag is in another file and the current file was not changed, the
|
|
|
396 other file will be made the current file and read into the buffer.
|
|
|
397 - If the tag is in another file, the current file was changed and a ! is
|
|
|
398 added to the command, the changes to the current file are lost, the other
|
|
|
399 file will be made the current file and read into the buffer.
|
|
|
400 - If the tag is in another file, the current file was changed and the
|
|
|
401 'autowrite' option is on, the current file will be written, the other
|
|
|
402 file will be made the current file and read into the buffer.
|
|
|
403 - If the tag is in another file, the current file was changed and the
|
|
|
404 'autowrite' option is off, the command will fail. If you want to save
|
|
|
405 the changes, use the ":w" command and then use ":tag" without an argument.
|
|
|
406 This works because the tag is put on the stack anyway. If you want to lose
|
|
|
407 the changes you can use the ":tag!" command.
|
|
|
408
|
|
|
409 *tag-security*
|
|
|
410 Note that Vim forbids some commands, for security reasons. This works like
|
|
|
411 using the 'secure' option for exrc/vimrc files in the current directory. See
|
|
|
412 |trojan-horse| and |sandbox|.
|
|
|
413 When the {tagaddress} changes a buffer, you will get a warning message:
|
|
|
414 "WARNING: tag command changed a buffer!!!"
|
|
|
415 In a future version changing the buffer will be impossible. All this for
|
|
|
416 security reasons: Somebody might hide a nasty command in the tags file, which
|
|
|
417 would otherwise go unnoticed. Example: >
|
|
|
418 :$d|/tag-function-name/
|
|
237
|
419 {this security prevention is not present in Vi}
|
|
7
|
420
|
|
|
421 In Vi the ":tag" command sets the last search pattern when the tag is searched
|
|
|
422 for. In Vim this is not done, the previous search pattern is still remembered,
|
|
|
423 unless the 't' flag is present in 'cpoptions'. The search pattern is always
|
|
|
424 put in the search history, so you can modify it if searching fails.
|
|
|
425
|
|
|
426 *emacs-tags* *emacs_tags* *E430*
|
|
|
427 Emacs style tag files are only supported if Vim was compiled with the
|
|
|
428 |+emacs_tags| feature enabled. Sorry, there is no explanation about Emacs tag
|
|
|
429 files here, it is only supported for backwards compatibility :-).
|
|
|
430
|
|
|
431 *tags-option*
|
|
|
432 The 'tags' option is a list of file names. Each of these files is searched
|
|
|
433 for the tag. This can be used to use a different tags file than the default
|
|
|
434 file "tags". It can also be used to access a common tags file.
|
|
|
435
|
|
|
436 The next file in the list is not used when:
|
|
|
437 - A matching static tag for the current buffer has been found.
|
|
|
438 - A matching global tag has been found.
|
|
|
439 This also depends on the 'ignorecase' option. If it is off, and the tags file
|
|
|
440 only has a match without matching case, the next tags file is searched for a
|
|
|
441 match with matching case. If no tag with matching case is found, the first
|
|
|
442 match without matching case is used. If 'ignorecase' is on, and a matching
|
|
|
443 global tag with or without matching case is found, this one is used, no
|
|
|
444 further tags files are searched.
|
|
|
445
|
|
|
446 When a tag file name starts with "./", the '.' is replaced with the path of
|
|
|
447 the current file. This makes it possible to use a tags file in the directory
|
|
|
448 where the current file is (no matter what the current directory is). The idea
|
|
|
449 of using "./" is that you can define which tag file is searched first: In the
|
|
|
450 current directory ("tags,./tags") or in the directory of the current file
|
|
|
451 ("./tags,tags").
|
|
|
452
|
|
|
453 For example: >
|
|
|
454 :set tags=./tags,tags,/home/user/commontags
|
|
|
455
|
|
|
456 In this example the tag will first be searched for in the file "tags" in the
|
|
|
457 directory where the current file is. Next the "tags" file in the current
|
|
|
458 directory. If it is not found there, then the file "/home/user/commontags"
|
|
|
459 will be searched for the tag.
|
|
|
460
|
|
|
461 This can be switched off by including the 'd' flag in 'cpoptions', to make
|
|
557
|
462 it Vi compatible. "./tags" will then be the tags file in the current
|
|
7
|
463 directory, instead of the tags file in the directory where the current file
|
|
|
464 is.
|
|
|
465
|
|
|
466 Instead of the comma a space may be used. Then a backslash is required for
|
|
|
467 the space to be included in the string option: >
|
|
|
468 :set tags=tags\ /home/user/commontags
|
|
|
469
|
|
|
470 To include a space in a file name use three backslashes. To include a comma
|
|
|
471 in a file name use two backslashes. For example, use: >
|
|
|
472 :set tags=tag\\\ file,/home/user/common\\,tags
|
|
|
473
|
|
|
474 for the files "tag file" and "/home/user/common,tags". The 'tags' option will
|
|
|
475 have the value "tag\ file,/home/user/common\,tags".
|
|
|
476
|
|
|
477 If the 'tagrelative' option is on (which is the default) and using a tag file
|
|
|
478 in another directory, file names in that tag file are relative to the
|
|
|
479 directory where the tag file is.
|
|
|
480
|
|
|
481 ==============================================================================
|
|
|
482 5. Tags file format *tags-file-format* *E431*
|
|
|
483
|
|
|
484 *ctags* *jtags*
|
|
|
485 A tags file can be created with an external command, for example "ctags". It
|
|
|
486 will contain a tag for each function. Some versions of "ctags" will also make
|
|
|
487 a tag for each "#defined" macro, typedefs, enums, etc.
|
|
|
488
|
|
|
489 Some programs that generate tags files:
|
|
|
490 ctags As found on most Unix systems. Only supports C. Only
|
|
|
491 does the basic work.
|
|
20
|
492 *Exuberant_ctags*
|
|
7
|
493 exuberant ctags This a very good one. It works for C, C++, Java,
|
|
|
494 Fortran, Eiffel and others. It can generate tags for
|
|
|
495 many items. See http://ctags.sourceforge.net.
|
|
|
496 etags Connected to Emacs. Supports many languages.
|
|
|
497 JTags For Java, in Java. It can be found at
|
|
|
498 http://www.fleiner.com/jtags/.
|
|
|
499 ptags.py For Python, in Python. Found in your Python source
|
|
|
500 directory at Tools/scripts/ptags.py.
|
|
|
501 ptags For Perl, in Perl. It can be found at
|
|
|
502 http://www.eleves.ens.fr:8080/home/nthiery/Tags/.
|
|
|
503 gnatxref For Ada. See http://www.gnuada.org/. gnatxref is
|
|
|
504 part of the gnat package.
|
|
|
505
|
|
|
506
|
|
|
507 The lines in the tags file must have one of these three formats:
|
|
|
508
|
|
|
509 1. {tagname} {TAB} {tagfile} {TAB} {tagaddress}
|
|
|
510 2. {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress}
|
|
|
511 3. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..
|
|
|
512
|
|
|
513 The first is a normal tag, which is completely compatible with Vi. It is the
|
|
|
514 only format produced by traditional ctags implementations. This is often used
|
|
|
515 for functions that are global, also referenced in other files.
|
|
|
516
|
|
|
517 The lines in the tags file can end in <LF> or <CR><LF>. On the Macintosh <CR>
|
|
|
518 also works. The <CR> and <NL> characters can never appear inside a line.
|
|
|
519
|
|
|
520 *tag-old-static*
|
|
|
521 The second format is for a static tag only. It is obsolete now, replaced by
|
|
|
522 the third format. It is only supported by Elvis 1.x and Vim and a few
|
|
|
523 versions of ctags. A static tag is often used for functions that are local,
|
|
|
524 only referenced in the file {tagfile}. Note that for the static tag, the two
|
|
|
525 occurrences of {tagfile} must be exactly the same. Also see |tags-option|
|
|
|
526 below, for how static tags are used.
|
|
|
527
|
|
|
528 The third format is new. It includes additional information in optional
|
|
|
529 fields at the end of each line. It is backwards compatible with Vi. It is
|
|
|
530 only supported by new versions of ctags (such as Exuberant ctags).
|
|
|
531
|
|
|
532 {tagname} The identifier. Normally the name of a function, but it can
|
|
|
533 be any identifier. It cannot contain a <Tab>.
|
|
|
534 {TAB} One <Tab> character. Note: previous versions allowed any
|
|
|
535 white space here. This has been abandoned to allow spaces in
|
|
|
536 {tagfile}. It can be re-enabled by including the
|
|
|
537 |+tag_any_white| feature at compile time. *tag-any-white*
|
|
|
538 {tagfile} The file that contains the definition of {tagname}. It can
|
|
|
539 have an absolute or relative path. It may contain environment
|
|
|
540 variables and wildcards (although the use of wildcards is
|
|
|
541 doubtful). It cannot contain a <Tab>.
|
|
|
542 {tagaddress} The Ex command that positions the cursor on the tag. It can
|
|
|
543 be any Ex command, although restrictions apply (see
|
|
|
544 |tag-security|). Posix only allows line numbers and search
|
|
|
545 commands, which are mostly used.
|
|
|
546 {term} ;" The two characters semicolon and double quote. This is
|
|
|
547 interpreted by Vi as the start of a comment, which makes the
|
|
|
548 following be ignored. This is for backwards compatibility
|
|
|
549 with Vi, it ignores the following fields.
|
|
|
550 {field} .. A list of optional fields. Each field has the form:
|
|
|
551
|
|
|
552 <Tab>{fieldname}:{value}
|
|
|
553
|
|
|
554 The {fieldname} identifies the field, and can only contain
|
|
|
555 alphabetical characters [a-zA-Z].
|
|
|
556 The {value} is any string, but cannot contain a <Tab>.
|
|
|
557 These characters are special:
|
|
|
558 "\t" stands for a <Tab>
|
|
|
559 "\r" stands for a <CR>
|
|
|
560 "\n" stands for a <NL>
|
|
|
561 "\\" stands for a single '\' character
|
|
|
562
|
|
|
563 There is one field that doesn't have a ':'. This is the kind
|
|
|
564 of the tag. It is handled like it was preceded with "kind:".
|
|
|
565 See the documentation of ctags for the kinds it produces.
|
|
|
566
|
|
|
567 The only other field currently recognized by Vim is "file:"
|
|
|
568 (with an empty value). It is used for a static tag.
|
|
|
569
|
|
|
570 The first lines in the tags file can contain lines that start with
|
|
|
571 !_TAG_
|
|
|
572 These are sorted to the first lines, only rare tags that start with "!" can
|
|
|
573 sort to before them. Vim recognizes two items. The first one is the line
|
|
|
574 that indicates if the file was sorted. When this line is found, Vim uses
|
|
|
575 binary searching for the tags file:
|
|
|
576 !_TAG_FILE_SORTED<Tab>1<Tab>{anything} ~
|
|
|
577
|
|
|
578 A tag file may be case-fold sorted to avoid a linear search when 'ignorecase'
|
|
|
579 is on. See 'tagbsearch' for details. The value '2' should be used then:
|
|
|
580 !_TAG_FILE_SORTED<Tab>2<Tab>{anything} ~
|
|
|
581
|
|
|
582 The other tag that Vim recognizes, but only when compiled with the
|
|
|
583 |+multi_byte| feature, is the encoding of the tags file:
|
|
|
584 !_TAG_FILE_ENCODING<Tab>utf-8<Tab>{anything} ~
|
|
|
585 Here "utf-8" is the encoding used for the tags. Vim will then convert the tag
|
|
|
586 being searched for from 'encoding' to the encoding of the tags file. And when
|
|
|
587 listing tags the reverse happens. When the conversion fails the unconverted
|
|
|
588 tag is used.
|
|
|
589
|
|
|
590 *tag-search*
|
|
|
591 The command can be any Ex command, but often it is a search command.
|
|
|
592 Examples:
|
|
|
593 tag1 file1 /^main(argc, argv)/ ~
|
|
|
594 tag2 file2 108 ~
|
|
|
595
|
|
|
596 The command is always executed with 'magic' not set. The only special
|
|
|
597 characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>).
|
|
|
598 See |pattern|. Note that you must put a backslash before each backslash in
|
|
|
599 the search text. This is for backwards compatibility with Vi.
|
|
|
600
|
|
|
601 *E434* *E435*
|
|
|
602 If the command is a normal search command (it starts and ends with "/" or
|
|
|
603 "?"), some special handling is done:
|
|
|
604 - Searching starts on line 1 of the file.
|
|
|
605 The direction of the search is forward for "/", backward for "?".
|
|
237
|
606 Note that 'wrapscan' does not matter, the whole file is always searched. (Vi
|
|
|
607 does use 'wrapscan', which caused tags sometimes not be found.) {Vi starts
|
|
7
|
608 searching in line 2 of another file. It does not find a tag in line 1 of
|
|
|
609 another file when 'wrapscan' is not set}
|
|
|
610 - If the search fails, another try is done ignoring case. If that fails too,
|
|
|
611 a search is done for:
|
|
|
612 "^tagname[ \t]*("
|
|
|
613 (the tag with '^' prepended and "[ \t]*(" appended). When using function
|
|
|
614 names, this will find the function name when it is in column 0. This will
|
|
|
615 help when the arguments to the function have changed since the tags file was
|
|
|
616 made. If this search also fails another search is done with:
|
|
|
617 "^[#a-zA-Z_].*\<tagname[ \t]*("
|
|
|
618 This means: A line starting with '#' or an identifier and containing the tag
|
|
|
619 followed by white space and a '('. This will find macro names and function
|
|
237
|
620 names with a type prepended. {the extra searches are not in Vi}
|
|
7
|
621
|
|
|
622 ==============================================================================
|
|
|
623 6. Include file searches *include-search* *definition-search*
|
|
|
624 *E387* *E388* *E389*
|
|
|
625
|
|
|
626 These commands look for a string in the current file and in all encountered
|
|
|
627 included files (recursively). This can be used to find the definition of a
|
|
|
628 variable, function or macro. If you only want to search in the current
|
|
|
629 buffer, use the commands listed at |pattern-searches|.
|
|
|
630
|
|
|
631 These commands are not available when the |+find_in_path| feature was disabled
|
|
|
632 at compile time.
|
|
|
633
|
|
|
634 When a line is encountered that includes another file, that file is searched
|
|
|
635 before continuing in the current buffer. Files included by included files are
|
|
|
636 also searched. When an include file could not be found it is silently
|
|
|
637 ignored. Use the |:checkpath| command to discover which files could not be
|
|
|
638 found, possibly your 'path' option is not set up correctly. Note: the
|
|
|
639 included file is searched, not a buffer that may be editing that file. Only
|
|
|
640 for the current file the lines in the buffer are used.
|
|
|
641
|
|
|
642 The string can be any keyword or a defined macro. For the keyword any match
|
|
|
643 will be found. For defined macros only lines that match with the 'define'
|
|
|
644 option will be found. The default is "^#\s*define", which is for C programs.
|
|
|
645 For other languages you probably want to change this. See 'define' for an
|
|
|
646 example for C++. The string cannot contain an end-of-line, only matches
|
|
|
647 within a line are found.
|
|
|
648
|
|
|
649 When a match is found for a defined macro, the displaying of lines continues
|
|
|
650 with the next line when a line ends in a backslash.
|
|
|
651
|
|
|
652 The commands that start with "[" start searching from the start of the current
|
|
|
653 file. The commands that start with "]" start at the current cursor position.
|
|
|
654
|
|
|
655 The 'include' option is used to define a line that includes another file. The
|
|
|
656 default is "\^#\s*include", which is for C programs. Note: Vim does not
|
|
|
657 recognize C syntax, if the 'include' option matches a line inside
|
|
|
658 "#ifdef/#endif" or inside a comment, it is searched anyway. The 'isfname'
|
|
|
659 option is used to recognize the file name that comes after the matched
|
|
|
660 pattern.
|
|
|
661
|
|
|
662 The 'path' option is used to find the directory for the include files that
|
|
|
663 do not have an absolute path.
|
|
|
664
|
|
|
665 The 'comments' option is used for the commands that display a single line or
|
|
|
666 jump to a line. It defines patterns that may start a comment. Those lines
|
|
|
667 are ignored for the search, unless [!] is used. One exception: When the line
|
|
|
668 matches the pattern "^# *define" it is not considered to be a comment.
|
|
|
669
|
|
|
670 If you want to list matches, and then select one to jump to, you could use a
|
|
|
671 mapping to do that for you. Here is an example: >
|
|
|
672
|
|
|
673 :map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " . nr ."[\t"<CR>
|
|
|
674 <
|
|
|
675 *[i*
|
|
|
676 [i Display the first line that contains the keyword
|
|
|
677 under the cursor. The search starts at the beginning
|
|
|
678 of the file. Lines that look like a comment are
|
|
|
679 ignored (see 'comments' option). If a count is given,
|
|
|
680 the count'th matching line is displayed, and comment
|
|
|
681 lines are not ignored. {not in Vi}
|
|
|
682
|
|
|
683 *]i*
|
|
|
684 ]i like "[i", but start at the current cursor position.
|
|
|
685 {not in Vi}
|
|
|
686
|
|
|
687 *:is* *:isearch*
|
|
|
688 :[range]is[earch][!] [count] [/]pattern[/]
|
|
|
689 Like "[i" and "]i", but search in [range] lines
|
|
|
690 (default: whole file).
|
|
|
691 See |:search-args| for [/] and [!]. {not in Vi}
|
|
|
692
|
|
|
693 *[I*
|
|
|
694 [I Display all lines that contain the keyword under the
|
|
|
695 cursor. Filenames and line numbers are displayed
|
|
|
696 for the found lines. The search starts at the
|
|
|
697 beginning of the file. {not in Vi}
|
|
|
698
|
|
|
699 *]I*
|
|
|
700 ]I like "[I", but start at the current cursor position.
|
|
|
701 {not in Vi}
|
|
|
702
|
|
|
703 *:il* *:ilist*
|
|
|
704 :[range]il[ist][!] [/]pattern[/]
|
|
|
705 Like "[I" and "]I", but search in [range] lines
|
|
|
706 (default: whole file).
|
|
|
707 See |:search-args| for [/] and [!]. {not in Vi}
|
|
|
708
|
|
|
709 *[_CTRL-I*
|
|
|
710 [ CTRL-I Jump to the first line that contains the keyword
|
|
|
711 under the cursor. The search starts at the beginning
|
|
|
712 of the file. Lines that look like a comment are
|
|
|
713 ignored (see 'comments' option). If a count is given,
|
|
|
714 the count'th matching line is jumped to, and comment
|
|
|
715 lines are not ignored. {not in Vi}
|
|
|
716
|
|
|
717 *]_CTRL-I*
|
|
|
718 ] CTRL-I like "[ CTRL-I", but start at the current cursor
|
|
|
719 position. {not in Vi}
|
|
|
720
|
|
|
721 *:ij* *:ijump*
|
|
|
722 :[range]ij[ump][!] [count] [/]pattern[/]
|
|
|
723 Like "[ CTRL-I" and "] CTRL-I", but search in
|
|
|
724 [range] lines (default: whole file).
|
|
|
725 See |:search-args| for [/] and [!]. {not in Vi}
|
|
|
726
|
|
|
727 CTRL-W CTRL-I *CTRL-W_CTRL-I* *CTRL-W_i*
|
|
|
728 CTRL-W i Open a new window, with the cursor on the first line
|
|
|
729 that contains the keyword under the cursor. The
|
|
|
730 search starts at the beginning of the file. Lines
|
|
|
731 that look like a comment line are ignored (see
|
|
|
732 'comments' option). If a count is given, the count'th
|
|
|
733 matching line is jumped to, and comment lines are not
|
|
|
734 ignored. {not in Vi}
|
|
|
735
|
|
|
736 *:isp* *:isplit*
|
|
|
737 :[range]isp[lit][!] [count] [/]pattern[/]
|
|
|
738 Like "CTRL-W i" and "CTRL-W i", but search in
|
|
|
739 [range] lines (default: whole file).
|
|
|
740 See |:search-args| for [/] and [!]. {not in Vi}
|
|
|
741
|
|
|
742 *[d*
|
|
|
743 [d Display the first macro definition that contains the
|
|
|
744 macro under the cursor. The search starts from the
|
|
|
745 beginning of the file. If a count is given, the
|
|
|
746 count'th matching line is displayed. {not in Vi}
|
|
|
747
|
|
|
748 *]d*
|
|
|
749 ]d like "[d", but start at the current cursor position.
|
|
|
750 {not in Vi}
|
|
|
751
|
|
|
752 *:ds* *:dsearch*
|
|
|
753 :[range]ds[earch][!] [count] [/]string[/]
|
|
|
754 Like "[d" and "]d", but search in [range] lines
|
|
|
755 (default: whole file).
|
|
|
756 See |:search-args| for [/] and [!]. {not in Vi}
|
|
|
757
|
|
|
758 *[D*
|
|
|
759 [D Display all macro definitions that contain the macro
|
|
|
760 under the cursor. Filenames and line numbers are
|
|
|
761 displayed for the found lines. The search starts
|
|
|
762 from the beginning of the file. {not in Vi}
|
|
|
763
|
|
|
764 *]D*
|
|
|
765 ]D like "[D", but start at the current cursor position.
|
|
|
766 {not in Vi}
|
|
|
767
|
|
169
|
768 *:dli* *:dlist*
|
|
7
|
769 :[range]dl[ist][!] [/]string[/]
|
|
|
770 Like "[D" and "]D", but search in [range] lines
|
|
|
771 (default: whole file).
|
|
|
772 See |:search-args| for [/] and [!]. {not in Vi}
|
|
169
|
773 Note that ":dl" works like ":delete" with the "l"
|
|
|
774 flag.
|
|
7
|
775
|
|
|
776 *[_CTRL-D*
|
|
|
777 [ CTRL-D Jump to the first macro definition that contains the
|
|
|
778 keyword under the cursor. The search starts from
|
|
|
779 the beginning of the file. If a count is given, the
|
|
|
780 count'th matching line is jumped to. {not in Vi}
|
|
|
781
|
|
|
782 *]_CTRL-D*
|
|
|
783 ] CTRL-D like "[ CTRL-D", but start at the current cursor
|
|
|
784 position. {not in Vi}
|
|
|
785
|
|
|
786 *:dj* *:djump*
|
|
|
787 :[range]dj[ump][!] [count] [/]string[/]
|
|
|
788 Like "[ CTRL-D" and "] CTRL-D", but search in
|
|
|
789 [range] lines (default: whole file).
|
|
|
790 See |:search-args| for [/] and [!]. {not in Vi}
|
|
|
791
|
|
|
792 CTRL-W CTRL-D *CTRL-W_CTRL-D* *CTRL-W_d*
|
|
|
793 CTRL-W d Open a new window, with the cursor on the first
|
|
|
794 macro definition line that contains the keyword
|
|
|
795 under the cursor. The search starts from the
|
|
|
796 beginning of the file. If a count is given, the
|
|
|
797 count'th matching line is jumped to. {not in Vi}
|
|
|
798
|
|
|
799 *:dsp* *:dsplit*
|
|
|
800 :[range]dsp[lit][!] [count] [/]string[/]
|
|
|
801 Like "CTRL-W d", but search in [range] lines
|
|
|
802 (default: whole file).
|
|
|
803 See |:search-args| for [/] and [!]. {not in Vi}
|
|
|
804
|
|
|
805 *:che* *:checkpath*
|
|
|
806 :che[ckpath] List all the included files that could not be found.
|
|
|
807 {not in Vi}
|
|
|
808
|
|
|
809 :che[ckpath]! List all the included files. {not in Vi}
|
|
|
810
|
|
|
811 *:search-args*
|
|
|
812 Common arguments for the commands above:
|
|
|
813 [!] When included, find matches in lines that are recognized as comments.
|
|
|
814 When excluded, a match is ignored when the line is recognized as a
|
|
|
815 comment (according to 'comments'), or the match is in a C comment (after
|
|
|
816 "//" or inside /* */). Note that a match may be missed if a line is
|
|
|
817 recognized as a comment, but the comment ends halfway the line.
|
|
|
818 And if the line is a comment, but it is not recognized (according to
|
|
|
819 'comments') a match may be found in it anyway. Example: >
|
|
|
820 /* comment
|
|
|
821 foobar */
|
|
|
822 < A match for "foobar" is found, because this line is not recognized as a
|
|
|
823 comment (even though syntax highlighting does recognize it).
|
|
|
824 Note: Since a macro definition mostly doesn't look like a comment, the
|
|
|
825 [!] makes no difference for ":dlist", ":dsearch" and ":djump".
|
|
|
826 [/] A pattern can be surrounded by '/'. Without '/' only whole words are
|
|
|
827 matched, using the pattern "\<pattern\>". Only after the second '/' a
|
|
|
828 next command can be appended with '|'. Example: >
|
|
|
829 :isearch /string/ | echo "the last one"
|
|
|
830 < For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern
|
|
|
831 is used as a literal string, not as a search pattern.
|
|
|
832
|
|
|
833 vim:tw=78:ts=8:ft=help:norl:
|
