Mercurial > vim
annotate runtime/doc/tagsrch.txt @ 35407:4ee73f91bad2
runtime(keymap): include Georgian keymap
Commit: https://github.com/vim/vim/commit/79a14c061bb7c5caafba09b9244f87be37693cf6
Author: Misho <nnamper@gmail.com>
Date: Fri Jun 14 20:13:17 2024 +0200
runtime(keymap): include Georgian keymap
closes: https://github.com/vim/vim/issues/15002
Signed-off-by: Misho <nnamper@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
author | Christian Brabandt <cb@256bit.org> |
---|---|
date | Fri, 14 Jun 2024 20:15:09 +0200 |
parents | 7191ebc28df2 |
children | d65d3d29e9ac |
rev | line source |
---|---|
34565
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
1 *tagsrch.txt* For Vim version 9.1. Last change: 2024 Mar 16 |
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| | |
16447
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
17 7. Using 'tagfunc' |tag-function| |
7 | 18 |
19 ============================================================================== | |
20 1. Jump to a tag *tag-commands* | |
21 | |
22 *tag* *tags* | |
23 A tag is an identifier that appears in a "tags" file. It is a sort of label | |
24 that can be jumped to. For example: In C programs each function name can be | |
25 used as a tag. The "tags" file has to be generated by a program like ctags, | |
26 before the tag commands can be used. | |
27 | |
28 With the ":tag" command the cursor will be positioned on the tag. With the | |
29 CTRL-] command, the keyword on which the cursor is standing is used as the | |
30 tag. If the cursor is not on a keyword, the first keyword to the right of the | |
31 cursor is used. | |
32 | |
33 The ":tag" command works very well for C programs. If you see a call to a | |
34 function and wonder what that function does, position the cursor inside of the | |
35 function name and hit CTRL-]. This will bring you to the function definition. | |
36 An easy way back is with the CTRL-T command. Also read about the tag stack | |
37 below. | |
38 | |
39 *:ta* *:tag* *E426* *E429* | |
13857 | 40 :[count]ta[g][!] {name} |
41 Jump to the definition of {name}, using the | |
42 information in the tags file(s). Put {name} in the | |
7 | 43 tag stack. See |tag-!| for [!]. |
13857 | 44 {name} can be a regexp pattern, see |tag-regexp|. |
45 When there are several matching tags for {name}, jump | |
685 | 46 to the [count] one. When [count] is omitted the |
47 first one is jumped to. See |tag-matchlist| for | |
48 jumping to other matching tags. | |
7 | 49 |
50 g<LeftMouse> *g<LeftMouse>* | |
51 <C-LeftMouse> *<C-LeftMouse>* *CTRL-]* | |
52 CTRL-] Jump to the definition of the keyword under the | |
13857 | 53 cursor. Same as ":tag {name}", where {name} is the |
685 | 54 keyword under or after cursor. |
13857 | 55 When there are several matching tags for {name}, jump |
685 | 56 to the [count] one. When no [count] is given the |
57 first one is jumped to. See |tag-matchlist| for | |
58 jumping to other matching tags. | |
7 | 59 |
60 *v_CTRL-]* | |
13857 | 61 {Visual}CTRL-] Same as ":tag {name}", where {name} is the text that |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
62 is highlighted. |
7 | 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 | |
13857 | 85 ":tag {name}". |
7 | 86 |
9913
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
87 The ignore-case matches are not found for a ":tag" command when: |
17036 | 88 - 'tagcase' is "followic" and the 'ignorecase' option is off |
89 - 'tagcase' is "followscs" and the 'ignorecase' option is off and the | |
90 'smartcase' option is off or the pattern contains an upper case character. | |
9913
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
91 - 'tagcase' is "match" |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
92 - 'tagcase' is "smart" and the pattern contains an upper case character. |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
93 |
10218
584c835a2de1
commit https://github.com/vim/vim/commit/50ba526fbf3e9e5e0e6b0b3086a4d5df581ebc7e
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
94 The ignore-case matches are found when: |
9913
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
95 - a pattern is used (starting with a "/") |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
96 - for ":tselect" |
17036 | 97 - when 'tagcase' is "followic" and 'ignorecase' is on |
98 - when 'tagcase' is "followscs" and 'ignorecase' is on or the 'smartcase' | |
99 option is on and the pattern does not contain an upper case character | |
100 - when 'tagcase' is "ignore" | |
32004 | 101 - when 'tagcase' is "smart" and the pattern does not contain an upper case |
17036 | 102 character |
9913
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
103 |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
104 Note that using ignore-case tag searching disables binary searching in the |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
105 tags file, which causes a slowdown. This can be avoided by fold-case sorting |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
106 the tag file. See the 'tagbsearch' option for an explanation. |
7 | 107 |
108 ============================================================================== | |
109 2. Tag stack *tag-stack* *tagstack* *E425* | |
110 | |
111 On the tag stack is remembered which tags you jumped to, and from where. | |
112 Tags are only pushed onto the stack when the 'tagstack' option is set. | |
113 | |
114 g<RightMouse> *g<RightMouse>* | |
115 <C-RightMouse> *<C-RightMouse>* *CTRL-T* | |
116 CTRL-T Jump to [count] older entry in the tag stack | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
117 (default 1). |
7 | 118 |
119 *:po* *:pop* *E555* *E556* | |
120 :[count]po[p][!] Jump to [count] older entry in tag stack (default 1). | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
121 See |tag-!| for [!]. |
7 | 122 |
123 :[count]ta[g][!] Jump to [count] newer entry in tag stack (default 1). | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
124 See |tag-!| for [!]. |
7 | 125 |
126 *:tags* | |
127 :tags Show the contents of the tag stack. The active | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
128 entry is marked with a '>'. |
7 | 129 |
130 The output of ":tags" looks like this: | |
131 | |
2681 | 132 # TO tag FROM line in file/text |
7 | 133 1 1 main 1 harddisk2:text/vim/test |
134 > 2 2 FuncA 58 i = FuncA(10); | |
135 3 1 FuncC 357 harddisk2:text/vim/src/amiga.c | |
136 | |
137 This list shows the tags that you jumped to and the cursor position before | |
138 that jump. The older tags are at the top, the newer at the bottom. | |
139 | |
140 The '>' points to the active entry. This is the tag that will be used by the | |
141 next ":tag" command. The CTRL-T and ":pop" command will use the position | |
142 above the active entry. | |
143 | |
144 Below the "TO" is the number of the current match in the match list. Note | |
145 that this doesn't change when using ":pop" or ":tag". | |
146 | |
147 The line number and file name are remembered to be able to get back to where | |
148 you were before the tag command. The line number will be correct, also when | |
149 deleting/inserting lines, unless this was done by another program (e.g. | |
150 another instance of Vim). | |
151 | |
2681 | 152 For the current file, the "file/text" column shows the text at the position. |
7 | 153 An indent is removed and a long line is truncated to fit in the window. |
154 | |
155 You can jump to previously used tags with several commands. Some examples: | |
156 | |
157 ":pop" or CTRL-T to position before previous tag | |
158 {count}CTRL-T to position before {count} older tag | |
159 ":tag" to newer tag | |
160 ":0tag" to last used tag | |
161 | |
162 The most obvious way to use this is while browsing through the call graph of | |
163 a program. Consider the following call graph: | |
164 | |
165 main ---> FuncA ---> FuncC | |
166 ---> FuncB | |
167 | |
168 (Explanation: main calls FuncA and FuncB; FuncA calls FuncC). | |
169 You can get from main to FuncA by using CTRL-] on the call to FuncA. Then | |
170 you can CTRL-] to get to FuncC. If you now want to go back to main you can | |
171 use CTRL-T twice. Then you can CTRL-] to FuncB. | |
172 | |
13857 | 173 If you issue a ":ta {name}" or CTRL-] command, this tag is inserted at the |
7 | 174 current position in the stack. If the stack was full (it can hold up to 20 |
175 entries), the oldest entry is deleted and the older entries shift one | |
176 position up (their index number is decremented by one). If the last used | |
177 entry was not at the bottom, the entries below the last used one are | |
178 deleted. This means that an old branch in the call graph is lost. After the | |
179 commands explained above the tag stack will look like this: | |
180 | |
2681 | 181 # TO tag FROM line in file/text |
182 1 1 main 1 harddisk2:text/vim/test | |
183 2 1 FuncB 59 harddisk2:text/vim/src/main.c | |
7 | 184 |
15033 | 185 The |gettagstack()| function returns the tag stack of a specified window. The |
186 |settagstack()| function modifies the tag stack of a window. | |
15016
c338c91086b9
patch 8.1.0519: cannot save and restore the tag stack
Bram Moolenaar <Bram@vim.org>
parents:
14421
diff
changeset
|
187 |
19968 | 188 *tagstack-examples* |
189 Write to the tag stack just like `:tag` but with a user-defined | |
190 jumper#jump_to_tag function: > | |
191 " Store where we're jumping from before we jump. | |
192 let tag = expand('<cword>') | |
193 let pos = [bufnr()] + getcurpos()[1:] | |
194 let item = {'bufnr': pos[0], 'from': pos, 'tagname': tag} | |
195 if jumper#jump_to_tag(tag) | |
196 " Jump was successful, write previous location to tag stack. | |
197 let winid = win_getid() | |
198 let stack = gettagstack(winid) | |
199 let stack['items'] = [item] | |
200 call settagstack(winid, stack, 't') | |
201 endif | |
202 < | |
203 Set current index of the tag stack to 4: > | |
204 call settagstack(1005, {'curidx' : 4}) | |
205 < | |
206 Push a new item onto the tag stack: > | |
207 let pos = [bufnr('myfile.txt'), 10, 1, 0] | |
208 let newtag = [{'tagname' : 'mytag', 'from' : pos}] | |
209 call settagstack(2, {'items' : newtag}, 'a') | |
210 < | |
7 | 211 *E73* |
212 When you try to use the tag stack while it doesn't contain anything you will | |
213 get an error message. | |
214 | |
215 ============================================================================== | |
216 3. Tag match list *tag-matchlist* *E427* *E428* | |
217 | |
218 When there are several matching tags, these commands can be used to jump | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
219 between them. Note that these commands don't change the tag stack, they keep |
7 | 220 the same entry. |
221 | |
222 *:ts* *:tselect* | |
13857 | 223 :ts[elect][!] [name] List the tags that match [name], using the |
7 | 224 information in the tags file(s). |
13857 | 225 When [name] is not given, the last tag name from the |
7 | 226 tag stack is used. |
12756
3b26420fc639
Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents:
10218
diff
changeset
|
227 See |tag-!| for [!]. |
7 | 228 With a '>' in the first column is indicated which is |
229 the current position in the list (if there is one). | |
13857 | 230 [name] can be a regexp pattern, see |tag-regexp|. |
7 | 231 See |tag-priority| for the priorities used in the |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
232 listing. |
7 | 233 Example output: |
234 | |
235 > | |
19039
d20ed2e5a776
Update a few runtime files.
Bram Moolenaar <Bram@vim.org>
parents:
18879
diff
changeset
|
236 # pri kind tag file |
7 | 237 1 F f mch_delay os_amiga.c |
238 mch_delay(msec, ignoreinput) | |
239 > 2 F f mch_delay os_msdos.c | |
240 mch_delay(msec, ignoreinput) | |
241 3 F f mch_delay os_unix.c | |
242 mch_delay(msec, ignoreinput) | |
19039
d20ed2e5a776
Update a few runtime files.
Bram Moolenaar <Bram@vim.org>
parents:
18879
diff
changeset
|
243 Type number and <Enter> (empty cancels): |
7 | 244 < |
245 See |tag-priority| for the "pri" column. Note that | |
246 this depends on the current file, thus using | |
247 ":tselect xxx" can produce different results. | |
248 The "kind" column gives the kind of tag, if this was | |
249 included in the tags file. | |
250 The "info" column shows information that could be | |
251 found in the tags file. It depends on the program | |
252 that produced the tags file. | |
253 When the list is long, you may get the |more-prompt|. | |
254 If you already see the tag you want to use, you can | |
255 type 'q' and enter the number. | |
256 | |
257 *:sts* *:stselect* | |
13857 | 258 :sts[elect][!] [name] Does ":tselect[!] [name]" and splits the window for |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
259 the selected tag. |
7 | 260 |
261 *g]* | |
262 g] Like CTRL-], but use ":tselect" instead of ":tag". | |
263 | |
264 *v_g]* | |
265 {Visual}g] Same as "g]", but use the highlighted text as the | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
266 identifier. |
7 | 267 |
268 *:tj* *:tjump* | |
13857 | 269 :tj[ump][!] [name] Like ":tselect", but jump to the tag directly when |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
270 there is only one match. |
7 | 271 |
272 *:stj* *:stjump* | |
13857 | 273 :stj[ump][!] [name] Does ":tjump[!] [name]" and splits the window for the |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
274 selected tag. |
7 | 275 |
276 *g_CTRL-]* | |
277 g CTRL-] Like CTRL-], but use ":tjump" instead of ":tag". | |
278 | |
279 *v_g_CTRL-]* | |
280 {Visual}g CTRL-] Same as "g CTRL-]", but use the highlighted text as | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
281 the identifier. |
7 | 282 |
283 *:tn* *:tnext* | |
284 :[count]tn[ext][!] Jump to [count] next matching tag (default 1). See | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
285 |tag-!| for [!]. |
7 | 286 |
287 *:tp* *:tprevious* | |
288 :[count]tp[revious][!] Jump to [count] previous matching tag (default 1). | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
289 See |tag-!| for [!]. |
7 | 290 |
291 *:tN* *:tNext* | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
292 :[count]tN[ext][!] Same as ":tprevious". |
7 | 293 |
294 *:tr* *:trewind* | |
295 :[count]tr[ewind][!] Jump to first matching tag. If [count] is given, jump | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
296 to [count]th matching tag. See |tag-!| for [!]. |
7 | 297 |
298 *:tf* *:tfirst* | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
299 :[count]tf[irst][!] Same as ":trewind". |
7 | 300 |
301 *:tl* *:tlast* | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
302 :tl[ast][!] Jump to last matching tag. See |tag-!| for [!]. |
7 | 303 |
651 | 304 *:lt* *:ltag* |
13857 | 305 :lt[ag][!] [name] Jump to tag [name] and add the matching tags to a new |
306 location list for the current window. [name] can be | |
307 a regexp pattern, see |tag-regexp|. When [name] is | |
651 | 308 not given, the last tag name from the tag stack is |
309 used. The search pattern to locate the tag line is | |
310 prefixed with "\V" to escape all the special | |
311 characters (very nomagic). The location list showing | |
312 the matching tags is independent of the tag stack. | |
313 See |tag-!| for [!]. | |
7 | 314 |
315 When there is no other message, Vim shows which matching tag has been jumped | |
316 to, and the number of matching tags: > | |
317 tag 1 of 3 or more | |
318 The " or more" is used to indicate that Vim didn't try all the tags files yet. | |
319 When using ":tnext" a few times, or with ":tlast", more matches may be found. | |
320 | |
321 When you didn't see this message because of some other message, or you just | |
322 want to know where you are, this command will show it again (and jump to the | |
323 same tag as last time): > | |
324 :0tn | |
325 < | |
326 *tag-skip-file* | |
327 When a matching tag is found for which the file doesn't exist, this match is | |
328 skipped and the next matching tag is used. Vim reports this, to notify you of | |
329 missing files. When the end of the list of matches has been reached, an error | |
330 message is given. | |
331 | |
651 | 332 *tag-preview* |
7 | 333 The tag match list can also be used in the preview window. The commands are |
334 the same as above, with a "p" prepended. | |
335 {not available when compiled without the |+quickfix| feature} | |
336 | |
337 *:pts* *:ptselect* | |
13857 | 338 :pts[elect][!] [name] Does ":tselect[!] [name]" and shows the new tag in a |
237 | 339 "Preview" window. See |:ptag| for more info. |
7 | 340 |
341 *:ptj* *:ptjump* | |
13857 | 342 :ptj[ump][!] [name] Does ":tjump[!] [name]" and shows the new tag in a |
237 | 343 "Preview" window. See |:ptag| for more info. |
7 | 344 |
345 *:ptn* *:ptnext* | |
346 :[count]ptn[ext][!] ":tnext" in the preview window. See |:ptag|. | |
347 | |
348 *:ptp* *:ptprevious* | |
349 :[count]ptp[revious][!] ":tprevious" in the preview window. See |:ptag|. | |
350 | |
351 *:ptN* *:ptNext* | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
352 :[count]ptN[ext][!] Same as ":ptprevious". |
7 | 353 |
354 *:ptr* *:ptrewind* | |
355 :[count]ptr[ewind][!] ":trewind" in the preview window. See |:ptag|. | |
356 | |
357 *:ptf* *:ptfirst* | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
358 :[count]ptf[irst][!] Same as ":ptrewind". |
7 | 359 |
360 *:ptl* *:ptlast* | |
361 :ptl[ast][!] ":tlast" in the preview window. See |:ptag|. | |
362 | |
363 ============================================================================== | |
364 4. Tags details *tag-details* | |
365 | |
366 *static-tag* | |
367 A static tag is a tag that is defined for a specific file. In a C program | |
368 this could be a static function. | |
369 | |
19055
8645b73b3645
patch 8.2.0088: insufficient tests for tags; bug in using extra tag field
Bram Moolenaar <Bram@vim.org>
parents:
19039
diff
changeset
|
370 In Vi jumping to a tag sets the current search pattern. This means that the |
8645b73b3645
patch 8.2.0088: insufficient tests for tags; bug in using extra tag field
Bram Moolenaar <Bram@vim.org>
parents:
19039
diff
changeset
|
371 "n" command after jumping to a tag does not search for the same pattern that |
8645b73b3645
patch 8.2.0088: insufficient tests for tags; bug in using extra tag field
Bram Moolenaar <Bram@vim.org>
parents:
19039
diff
changeset
|
372 it did before jumping to the tag. Vim does not do this as we consider it to |
8645b73b3645
patch 8.2.0088: insufficient tests for tags; bug in using extra tag field
Bram Moolenaar <Bram@vim.org>
parents:
19039
diff
changeset
|
373 be a bug. If you really want the old Vi behavior, set the 't' flag in |
8645b73b3645
patch 8.2.0088: insufficient tests for tags; bug in using extra tag field
Bram Moolenaar <Bram@vim.org>
parents:
19039
diff
changeset
|
374 'cpoptions'. |
7 | 375 |
376 *tag-binary-search* | |
377 Vim uses binary searching in the tags file to find the desired tag quickly | |
378 (when enabled at compile time |+tag_binary|). But this only works if the | |
379 tags file was sorted on ASCII byte value. Therefore, if no match was found, | |
380 another try is done with a linear search. If you only want the linear search, | |
381 reset the 'tagbsearch' option. Or better: Sort the tags file! | |
382 | |
383 Note that the binary searching is disabled when not looking for a tag with a | |
384 specific name. This happens when ignoring case and when a regular expression | |
385 is used that doesn't start with a fixed string. Tag searching can be a lot | |
386 slower then. The former can be avoided by case-fold sorting the tags file. | |
387 See 'tagbsearch' for details. | |
388 | |
389 *tag-regexp* | |
5244 | 390 The ":tag" and ":tselect" commands accept a regular expression argument. See |
7 | 391 |pattern| for the special characters that can be used. |
392 When the argument starts with '/', it is used as a pattern. If the argument | |
393 does not start with '/', it is taken literally, as a full tag name. | |
394 Examples: > | |
395 :tag main | |
396 < jumps to the tag "main" that has the highest priority. > | |
397 :tag /^get | |
398 < jumps to the tag that starts with "get" and has the highest priority. > | |
399 :tag /norm | |
400 < lists all the tags that contain "norm", including "id_norm". | |
401 When the argument both exists literally, and match when used as a regexp, a | |
402 literal match has a higher priority. For example, ":tag /open" matches "open" | |
403 before "open_file" and "file_open". | |
415 | 404 When using a pattern case is ignored. If you want to match case use "\C" in |
405 the pattern. | |
7 | 406 |
407 *tag-!* | |
408 If the tag is in the current file this will always work. Otherwise the | |
409 performed actions depend on whether the current file was changed, whether a ! | |
34565
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
410 is added to the command and on the 'autowrite' and 'winfixbuf' options: |
7 | 411 |
34565
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
412 tag in file winfixbuf autowrite ~ |
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
413 current file changed ! option option action ~ |
34470
dd8f5311cee5
patch 9.1.0147: Cannot keep a buffer focused in a window
Christian Brabandt <cb@256bit.org>
parents:
34057
diff
changeset
|
414 ----------------------------------------------------------------------------- |
34565
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
415 yes x x off x goto tag |
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
416 no no x off x read other file, goto tag |
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
417 no yes yes off x abandon current file, |
34470
dd8f5311cee5
patch 9.1.0147: Cannot keep a buffer focused in a window
Christian Brabandt <cb@256bit.org>
parents:
34057
diff
changeset
|
418 read other file, goto tag |
34565
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
419 no yes no off on write current file, |
34470
dd8f5311cee5
patch 9.1.0147: Cannot keep a buffer focused in a window
Christian Brabandt <cb@256bit.org>
parents:
34057
diff
changeset
|
420 read other file, goto tag |
34565
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
421 no yes no off off fail |
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
422 yes x yes x x goto tag |
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
423 no no no on x fail |
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
424 no yes no on x fail |
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
425 no yes no on on fail |
eda0365c992c
runtime(doc): make :h tag-! more consistent (#14208)
Christian Brabandt <cb@256bit.org>
parents:
34470
diff
changeset
|
426 no yes no on off fail |
34470
dd8f5311cee5
patch 9.1.0147: Cannot keep a buffer focused in a window
Christian Brabandt <cb@256bit.org>
parents:
34057
diff
changeset
|
427 ----------------------------------------------------------------------------- |
7 | 428 |
429 - If the tag is in the current file, the command will always work. | |
430 - If the tag is in another file and the current file was not changed, the | |
431 other file will be made the current file and read into the buffer. | |
432 - If the tag is in another file, the current file was changed and a ! is | |
433 added to the command, the changes to the current file are lost, the other | |
434 file will be made the current file and read into the buffer. | |
435 - If the tag is in another file, the current file was changed and the | |
436 'autowrite' option is on, the current file will be written, the other | |
437 file will be made the current file and read into the buffer. | |
438 - If the tag is in another file, the current file was changed and the | |
439 'autowrite' option is off, the command will fail. If you want to save | |
440 the changes, use the ":w" command and then use ":tag" without an argument. | |
441 This works because the tag is put on the stack anyway. If you want to lose | |
442 the changes you can use the ":tag!" command. | |
34470
dd8f5311cee5
patch 9.1.0147: Cannot keep a buffer focused in a window
Christian Brabandt <cb@256bit.org>
parents:
34057
diff
changeset
|
443 - If the tag is in another file and the window includes 'winfixbuf', the |
dd8f5311cee5
patch 9.1.0147: Cannot keep a buffer focused in a window
Christian Brabandt <cb@256bit.org>
parents:
34057
diff
changeset
|
444 command will fail. If the tag is in the same file then it may succeed. |
7 | 445 |
446 *tag-security* | |
447 Note that Vim forbids some commands, for security reasons. This works like | |
448 using the 'secure' option for exrc/vimrc files in the current directory. See | |
449 |trojan-horse| and |sandbox|. | |
450 When the {tagaddress} changes a buffer, you will get a warning message: | |
451 "WARNING: tag command changed a buffer!!!" | |
452 In a future version changing the buffer will be impossible. All this for | |
453 security reasons: Somebody might hide a nasty command in the tags file, which | |
454 would otherwise go unnoticed. Example: > | |
455 :$d|/tag-function-name/ | |
456 | |
457 In Vi the ":tag" command sets the last search pattern when the tag is searched | |
458 for. In Vim this is not done, the previous search pattern is still remembered, | |
19055
8645b73b3645
patch 8.2.0088: insufficient tests for tags; bug in using extra tag field
Bram Moolenaar <Bram@vim.org>
parents:
19039
diff
changeset
|
459 unless the 't' flag is present in 'cpoptions'. |
7 | 460 |
461 *emacs-tags* *emacs_tags* *E430* | |
462 Emacs style tag files are only supported if Vim was compiled with the | |
463 |+emacs_tags| feature enabled. Sorry, there is no explanation about Emacs tag | |
464 files here, it is only supported for backwards compatibility :-). | |
465 | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
466 Lines in Emacs tags files can be very long. Vim only deals with lines of up |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
467 to about 510 bytes. To see whether lines are ignored set 'verbose' to 5 or |
18594 | 468 higher. Non-Emacs tags file lines can be any length. |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
469 |
7 | 470 *tags-option* |
471 The 'tags' option is a list of file names. Each of these files is searched | |
472 for the tag. This can be used to use a different tags file than the default | |
473 file "tags". It can also be used to access a common tags file. | |
474 | |
475 The next file in the list is not used when: | |
476 - A matching static tag for the current buffer has been found. | |
477 - A matching global tag has been found. | |
9913
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
478 This also depends on whether case is ignored. Case is ignored when: |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
479 - 'tagcase' is "followic" and 'ignorecase' is set |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
480 - 'tagcase' is "ignore" |
9975
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
481 - 'tagcase' is "smart" and the pattern only contains lower case |
9913
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
482 characters. |
9975
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
483 - 'tagcase' is "followscs" and 'smartcase' is set and the pattern only |
9913
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
484 contains lower case characters. |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
485 If case is not ignored, and the tags file only has a match without matching |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
486 case, the next tags file is searched for a match with matching case. If no |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
487 tag with matching case is found, the first match without matching case is |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
488 used. If case is ignored, and a matching global tag with or without matching |
bb00c661b3a4
commit https://github.com/vim/vim/commit/66e29d7112e437b2b50efe1f82c7e892736d23e4
Christian Brabandt <cb@256bit.org>
parents:
7266
diff
changeset
|
489 case is found, this one is used, no further tags files are searched. |
7 | 490 |
491 When a tag file name starts with "./", the '.' is replaced with the path of | |
492 the current file. This makes it possible to use a tags file in the directory | |
493 where the current file is (no matter what the current directory is). The idea | |
494 of using "./" is that you can define which tag file is searched first: In the | |
495 current directory ("tags,./tags") or in the directory of the current file | |
496 ("./tags,tags"). | |
497 | |
498 For example: > | |
499 :set tags=./tags,tags,/home/user/commontags | |
500 | |
501 In this example the tag will first be searched for in the file "tags" in the | |
502 directory where the current file is. Next the "tags" file in the current | |
503 directory. If it is not found there, then the file "/home/user/commontags" | |
504 will be searched for the tag. | |
505 | |
506 This can be switched off by including the 'd' flag in 'cpoptions', to make | |
557 | 507 it Vi compatible. "./tags" will then be the tags file in the current |
7 | 508 directory, instead of the tags file in the directory where the current file |
509 is. | |
510 | |
511 Instead of the comma a space may be used. Then a backslash is required for | |
512 the space to be included in the string option: > | |
513 :set tags=tags\ /home/user/commontags | |
514 | |
515 To include a space in a file name use three backslashes. To include a comma | |
516 in a file name use two backslashes. For example, use: > | |
517 :set tags=tag\\\ file,/home/user/common\\,tags | |
518 | |
519 for the files "tag file" and "/home/user/common,tags". The 'tags' option will | |
520 have the value "tag\ file,/home/user/common\,tags". | |
521 | |
522 If the 'tagrelative' option is on (which is the default) and using a tag file | |
523 in another directory, file names in that tag file are relative to the | |
524 directory where the tag file is. | |
525 | |
526 ============================================================================== | |
527 5. Tags file format *tags-file-format* *E431* | |
528 | |
529 *ctags* *jtags* | |
530 A tags file can be created with an external command, for example "ctags". It | |
531 will contain a tag for each function. Some versions of "ctags" will also make | |
532 a tag for each "#defined" macro, typedefs, enums, etc. | |
533 | |
534 Some programs that generate tags files: | |
535 ctags As found on most Unix systems. Only supports C. Only | |
536 does the basic work. | |
20115 | 537 universal ctags A maintained version of ctags based on exuberant |
538 ctags. See https://ctags.io. | |
20 | 539 *Exuberant_ctags* |
17036 | 540 exuberant ctags This is a very good one. It works for C, C++, Java, |
7 | 541 Fortran, Eiffel and others. It can generate tags for |
542 many items. See http://ctags.sourceforge.net. | |
20115 | 543 No new version since 2009. |
7 | 544 etags Connected to Emacs. Supports many languages. |
545 JTags For Java, in Java. It can be found at | |
546 http://www.fleiner.com/jtags/. | |
547 ptags.py For Python, in Python. Found in your Python source | |
548 directory at Tools/scripts/ptags.py. | |
35158
7191ebc28df2
runtime(doc): update and remove some invalid links
Christian Brabandt <cb@256bit.org>
parents:
34565
diff
changeset
|
549 ptags For Perl, in Perl. It can be found at (link seems |
7191ebc28df2
runtime(doc): update and remove some invalid links
Christian Brabandt <cb@256bit.org>
parents:
34565
diff
changeset
|
550 dead): |
7 | 551 http://www.eleves.ens.fr:8080/home/nthiery/Tags/. |
552 gnatxref For Ada. See http://www.gnuada.org/. gnatxref is | |
553 part of the gnat package. | |
554 | |
555 | |
16176
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
556 The lines in the tags file must have one of these two formats: |
7 | 557 |
558 1. {tagname} {TAB} {tagfile} {TAB} {tagaddress} | |
16176
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
559 2. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} .. |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
560 |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
561 Previously an old format was supported, see |tag-old-static|. |
7 | 562 |
16176
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
563 The first format is a normal tag, which is completely compatible with Vi. It |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
564 is the only format produced by traditional ctags implementations. This is |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
565 often used for functions that are global, also referenced in other files. |
7 | 566 |
23305 | 567 The lines in the tags file can end in <NL> or <CR><NL>. On the Macintosh <CR> |
7 | 568 also works. The <CR> and <NL> characters can never appear inside a line. |
569 | |
16176
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
570 The second format is new. It includes additional information in optional |
7 | 571 fields at the end of each line. It is backwards compatible with Vi. It is |
28141 | 572 only supported by new versions of ctags (such as Universal ctags or Exuberant |
573 ctags). | |
7 | 574 |
575 {tagname} The identifier. Normally the name of a function, but it can | |
576 be any identifier. It cannot contain a <Tab>. | |
577 {TAB} One <Tab> character. Note: previous versions allowed any | |
578 white space here. This has been abandoned to allow spaces in | |
16086 | 579 {tagfile}. |
7 | 580 {tagfile} The file that contains the definition of {tagname}. It can |
581 have an absolute or relative path. It may contain environment | |
582 variables and wildcards (although the use of wildcards is | |
583 doubtful). It cannot contain a <Tab>. | |
584 {tagaddress} The Ex command that positions the cursor on the tag. It can | |
585 be any Ex command, although restrictions apply (see | |
586 |tag-security|). Posix only allows line numbers and search | |
587 commands, which are mostly used. | |
588 {term} ;" The two characters semicolon and double quote. This is | |
589 interpreted by Vi as the start of a comment, which makes the | |
590 following be ignored. This is for backwards compatibility | |
15808
37d31fc37a5a
patch 8.1.0911: tag line with Ex command cannot have extra fields
Bram Moolenaar <Bram@vim.org>
parents:
15033
diff
changeset
|
591 with Vi, it ignores the following fields. Example: |
37d31fc37a5a
patch 8.1.0911: tag line with Ex command cannot have extra fields
Bram Moolenaar <Bram@vim.org>
parents:
15033
diff
changeset
|
592 APP file /^static int APP;$/;" v |
37d31fc37a5a
patch 8.1.0911: tag line with Ex command cannot have extra fields
Bram Moolenaar <Bram@vim.org>
parents:
15033
diff
changeset
|
593 When {tagaddress} is not a line number or search pattern, then |
37d31fc37a5a
patch 8.1.0911: tag line with Ex command cannot have extra fields
Bram Moolenaar <Bram@vim.org>
parents:
15033
diff
changeset
|
594 {term} must be |;". Here the bar ends the command (excluding |
37d31fc37a5a
patch 8.1.0911: tag line with Ex command cannot have extra fields
Bram Moolenaar <Bram@vim.org>
parents:
15033
diff
changeset
|
595 the bar) and ;" is used to have Vi ignore the rest of the |
37d31fc37a5a
patch 8.1.0911: tag line with Ex command cannot have extra fields
Bram Moolenaar <Bram@vim.org>
parents:
15033
diff
changeset
|
596 line. Example: |
37d31fc37a5a
patch 8.1.0911: tag line with Ex command cannot have extra fields
Bram Moolenaar <Bram@vim.org>
parents:
15033
diff
changeset
|
597 APP file.c call cursor(3, 4)|;" v |
16023 | 598 |
7 | 599 {field} .. A list of optional fields. Each field has the form: |
600 | |
601 <Tab>{fieldname}:{value} | |
602 | |
603 The {fieldname} identifies the field, and can only contain | |
604 alphabetical characters [a-zA-Z]. | |
605 The {value} is any string, but cannot contain a <Tab>. | |
606 These characters are special: | |
607 "\t" stands for a <Tab> | |
608 "\r" stands for a <CR> | |
609 "\n" stands for a <NL> | |
610 "\\" stands for a single '\' character | |
611 | |
612 There is one field that doesn't have a ':'. This is the kind | |
613 of the tag. It is handled like it was preceded with "kind:". | |
614 See the documentation of ctags for the kinds it produces. | |
615 | |
616 The only other field currently recognized by Vim is "file:" | |
617 (with an empty value). It is used for a static tag. | |
618 | |
16176
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
619 |
7 | 620 The first lines in the tags file can contain lines that start with |
621 !_TAG_ | |
622 These are sorted to the first lines, only rare tags that start with "!" can | |
623 sort to before them. Vim recognizes two items. The first one is the line | |
624 that indicates if the file was sorted. When this line is found, Vim uses | |
625 binary searching for the tags file: | |
626 !_TAG_FILE_SORTED<Tab>1<Tab>{anything} ~ | |
627 | |
7266
6ba7182fb7bd
commit https://github.com/vim/vim/commit/0f6562e9036f889185dff49a75c7fc5ffb28b307
Christian Brabandt <cb@256bit.org>
parents:
5400
diff
changeset
|
628 A tag file may be case-fold sorted to avoid a linear search when case is |
6ba7182fb7bd
commit https://github.com/vim/vim/commit/0f6562e9036f889185dff49a75c7fc5ffb28b307
Christian Brabandt <cb@256bit.org>
parents:
5400
diff
changeset
|
629 ignored. (Case is ignored when 'ignorecase' is set and 'tagcase' is |
6ba7182fb7bd
commit https://github.com/vim/vim/commit/0f6562e9036f889185dff49a75c7fc5ffb28b307
Christian Brabandt <cb@256bit.org>
parents:
5400
diff
changeset
|
630 "followic", or when 'tagcase' is "ignore".) See 'tagbsearch' for details. |
6ba7182fb7bd
commit https://github.com/vim/vim/commit/0f6562e9036f889185dff49a75c7fc5ffb28b307
Christian Brabandt <cb@256bit.org>
parents:
5400
diff
changeset
|
631 The value '2' should be used then: |
7 | 632 !_TAG_FILE_SORTED<Tab>2<Tab>{anything} ~ |
633 | |
15878 | 634 The other tag that Vim recognizes is the encoding of the tags file: |
7 | 635 !_TAG_FILE_ENCODING<Tab>utf-8<Tab>{anything} ~ |
636 Here "utf-8" is the encoding used for the tags. Vim will then convert the tag | |
637 being searched for from 'encoding' to the encoding of the tags file. And when | |
638 listing tags the reverse happens. When the conversion fails the unconverted | |
639 tag is used. | |
640 | |
641 *tag-search* | |
642 The command can be any Ex command, but often it is a search command. | |
643 Examples: | |
644 tag1 file1 /^main(argc, argv)/ ~ | |
645 tag2 file2 108 ~ | |
646 | |
647 The command is always executed with 'magic' not set. The only special | |
648 characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>). | |
649 See |pattern|. Note that you must put a backslash before each backslash in | |
650 the search text. This is for backwards compatibility with Vi. | |
651 | |
652 *E434* *E435* | |
653 If the command is a normal search command (it starts and ends with "/" or | |
654 "?"), some special handling is done: | |
655 - Searching starts on line 1 of the file. | |
656 The direction of the search is forward for "/", backward for "?". | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
657 Note that 'wrapscan' does not matter, the whole file is always searched. |
7 | 658 - If the search fails, another try is done ignoring case. If that fails too, |
659 a search is done for: | |
660 "^tagname[ \t]*(" | |
661 (the tag with '^' prepended and "[ \t]*(" appended). When using function | |
662 names, this will find the function name when it is in column 0. This will | |
663 help when the arguments to the function have changed since the tags file was | |
664 made. If this search also fails another search is done with: | |
665 "^[#a-zA-Z_].*\<tagname[ \t]*(" | |
666 This means: A line starting with '#' or an identifier and containing the tag | |
667 followed by white space and a '('. This will find macro names and function | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
668 names with a type prepended. |
7 | 669 |
16176
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
670 |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
671 *tag-old-static* |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
672 Until March 2019 (patch 8.1.1092) an outdated format was supported: |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
673 {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress} |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
674 |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
675 This format is for a static tag only. It is obsolete now, replaced by |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
676 the second format. It is only supported by Elvis 1.x, older Vim versions and |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
677 a few versions of ctags. A static tag is often used for functions that are |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
678 local, only referenced in the file {tagfile}. Note that for the static tag, |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
679 the two occurrences of {tagfile} must be exactly the same. Also see |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
680 |tags-option| below, for how static tags are used. |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
681 |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
682 The support was removed, since when you can update to the new Vim version you |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
683 should also be able to update ctags to one that supports the second format. |
4d7ee5609652
patch 8.1.1093: support for outdated tags format slows down tag parsing
Bram Moolenaar <Bram@vim.org>
parents:
16086
diff
changeset
|
684 |
7 | 685 ============================================================================== |
686 6. Include file searches *include-search* *definition-search* | |
687 *E387* *E388* *E389* | |
688 | |
689 These commands look for a string in the current file and in all encountered | |
690 included files (recursively). This can be used to find the definition of a | |
691 variable, function or macro. If you only want to search in the current | |
692 buffer, use the commands listed at |pattern-searches|. | |
693 | |
694 These commands are not available when the |+find_in_path| feature was disabled | |
695 at compile time. | |
696 | |
697 When a line is encountered that includes another file, that file is searched | |
698 before continuing in the current buffer. Files included by included files are | |
699 also searched. When an include file could not be found it is silently | |
700 ignored. Use the |:checkpath| command to discover which files could not be | |
701 found, possibly your 'path' option is not set up correctly. Note: the | |
702 included file is searched, not a buffer that may be editing that file. Only | |
703 for the current file the lines in the buffer are used. | |
704 | |
705 The string can be any keyword or a defined macro. For the keyword any match | |
706 will be found. For defined macros only lines that match with the 'define' | |
707 option will be found. The default is "^#\s*define", which is for C programs. | |
708 For other languages you probably want to change this. See 'define' for an | |
709 example for C++. The string cannot contain an end-of-line, only matches | |
710 within a line are found. | |
711 | |
712 When a match is found for a defined macro, the displaying of lines continues | |
713 with the next line when a line ends in a backslash. | |
714 | |
715 The commands that start with "[" start searching from the start of the current | |
716 file. The commands that start with "]" start at the current cursor position. | |
717 | |
718 The 'include' option is used to define a line that includes another file. The | |
719 default is "\^#\s*include", which is for C programs. Note: Vim does not | |
720 recognize C syntax, if the 'include' option matches a line inside | |
721 "#ifdef/#endif" or inside a comment, it is searched anyway. The 'isfname' | |
722 option is used to recognize the file name that comes after the matched | |
723 pattern. | |
724 | |
725 The 'path' option is used to find the directory for the include files that | |
726 do not have an absolute path. | |
727 | |
728 The 'comments' option is used for the commands that display a single line or | |
729 jump to a line. It defines patterns that may start a comment. Those lines | |
730 are ignored for the search, unless [!] is used. One exception: When the line | |
731 matches the pattern "^# *define" it is not considered to be a comment. | |
732 | |
733 If you want to list matches, and then select one to jump to, you could use a | |
734 mapping to do that for you. Here is an example: > | |
735 | |
27903 | 736 :map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " .. nr .. "[\t"<CR> |
7 | 737 < |
738 *[i* | |
739 [i Display the first line that contains the keyword | |
740 under the cursor. The search starts at the beginning | |
741 of the file. Lines that look like a comment are | |
742 ignored (see 'comments' option). If a count is given, | |
743 the count'th matching line is displayed, and comment | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
744 lines are not ignored. |
7 | 745 |
746 *]i* | |
747 ]i like "[i", but start at the current cursor position. | |
748 | |
749 *:is* *:isearch* | |
750 :[range]is[earch][!] [count] [/]pattern[/] | |
751 Like "[i" and "]i", but search in [range] lines | |
752 (default: whole file). | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
753 See |:search-args| for [/] and [!]. |
7 | 754 |
755 *[I* | |
756 [I Display all lines that contain the keyword under the | |
757 cursor. Filenames and line numbers are displayed | |
758 for the found lines. The search starts at the | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
759 beginning of the file. |
7 | 760 |
761 *]I* | |
762 ]I like "[I", but start at the current cursor position. | |
763 | |
764 *:il* *:ilist* | |
765 :[range]il[ist][!] [/]pattern[/] | |
766 Like "[I" and "]I", but search in [range] lines | |
767 (default: whole file). | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
768 See |:search-args| for [/] and [!]. |
7 | 769 |
770 *[_CTRL-I* | |
771 [ CTRL-I Jump to the first line that contains the keyword | |
772 under the cursor. The search starts at the beginning | |
773 of the file. Lines that look like a comment are | |
774 ignored (see 'comments' option). If a count is given, | |
775 the count'th matching line is jumped to, and comment | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
776 lines are not ignored. |
7 | 777 |
778 *]_CTRL-I* | |
779 ] CTRL-I like "[ CTRL-I", but start at the current cursor | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
780 position. |
7 | 781 |
782 *:ij* *:ijump* | |
783 :[range]ij[ump][!] [count] [/]pattern[/] | |
784 Like "[ CTRL-I" and "] CTRL-I", but search in | |
785 [range] lines (default: whole file). | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
786 See |:search-args| for [/] and [!]. |
7 | 787 |
788 CTRL-W CTRL-I *CTRL-W_CTRL-I* *CTRL-W_i* | |
789 CTRL-W i Open a new window, with the cursor on the first line | |
790 that contains the keyword under the cursor. The | |
791 search starts at the beginning of the file. Lines | |
792 that look like a comment line are ignored (see | |
793 'comments' option). If a count is given, the count'th | |
794 matching line is jumped to, and comment lines are not | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
795 ignored. |
7 | 796 |
797 *:isp* *:isplit* | |
798 :[range]isp[lit][!] [count] [/]pattern[/] | |
799 Like "CTRL-W i" and "CTRL-W i", but search in | |
800 [range] lines (default: whole file). | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
801 See |:search-args| for [/] and [!]. |
7 | 802 |
803 *[d* | |
804 [d Display the first macro definition that contains the | |
805 macro under the cursor. The search starts from the | |
806 beginning of the file. If a count is given, the | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
807 count'th matching line is displayed. |
7 | 808 |
809 *]d* | |
810 ]d like "[d", but start at the current cursor position. | |
811 | |
812 *:ds* *:dsearch* | |
813 :[range]ds[earch][!] [count] [/]string[/] | |
814 Like "[d" and "]d", but search in [range] lines | |
815 (default: whole file). | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
816 See |:search-args| for [/] and [!]. |
7 | 817 |
818 *[D* | |
819 [D Display all macro definitions that contain the macro | |
820 under the cursor. Filenames and line numbers are | |
821 displayed for the found lines. The search starts | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
822 from the beginning of the file. |
7 | 823 |
824 *]D* | |
825 ]D like "[D", but start at the current cursor position. | |
826 | |
169 | 827 *:dli* *:dlist* |
3224 | 828 :[range]dli[st][!] [/]string[/] |
5400 | 829 Like `[D` and `]D`, but search in [range] lines |
7 | 830 (default: whole file). |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
831 See |:search-args| for [/] and [!]. |
5400 | 832 Note that `:dl` works like `:delete` with the "l" |
833 flag, not `:dlist`. | |
7 | 834 |
835 *[_CTRL-D* | |
836 [ CTRL-D Jump to the first macro definition that contains the | |
837 keyword under the cursor. The search starts from | |
838 the beginning of the file. If a count is given, the | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
839 count'th matching line is jumped to. |
7 | 840 |
841 *]_CTRL-D* | |
842 ] CTRL-D like "[ CTRL-D", but start at the current cursor | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
843 position. |
7 | 844 |
845 *:dj* *:djump* | |
846 :[range]dj[ump][!] [count] [/]string[/] | |
847 Like "[ CTRL-D" and "] CTRL-D", but search in | |
848 [range] lines (default: whole file). | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
849 See |:search-args| for [/] and [!]. |
7 | 850 |
851 CTRL-W CTRL-D *CTRL-W_CTRL-D* *CTRL-W_d* | |
852 CTRL-W d Open a new window, with the cursor on the first | |
853 macro definition line that contains the keyword | |
854 under the cursor. The search starts from the | |
855 beginning of the file. If a count is given, the | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
856 count'th matching line is jumped to. |
7 | 857 |
858 *:dsp* *:dsplit* | |
859 :[range]dsp[lit][!] [count] [/]string[/] | |
860 Like "CTRL-W d", but search in [range] lines | |
861 (default: whole file). | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
862 See |:search-args| for [/] and [!]. |
7 | 863 |
17036 | 864 *:che* *:chec* *:check* *:checkpath* |
7 | 865 :che[ckpath] List all the included files that could not be found. |
866 | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16447
diff
changeset
|
867 :che[ckpath]! List all the included files. |
7 | 868 |
869 *:search-args* | |
870 Common arguments for the commands above: | |
9975
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
871 [!] When included, find matches in lines that are recognized as comments. |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
872 When excluded, a match is ignored when the line is recognized as a |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
873 comment (according to 'comments'), or the match is in a C comment |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
874 (after "//" or inside /* */). Note that a match may be missed if a |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
875 line is recognized as a comment, but the comment ends halfway the line. |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
876 And if the line is a comment, but it is not recognized (according to |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
877 'comments') a match may be found in it anyway. Example: > |
7 | 878 /* comment |
879 foobar */ | |
9975
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
880 < A match for "foobar" is found, because this line is not recognized as |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
881 a comment (even though syntax highlighting does recognize it). |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
882 Note: Since a macro definition mostly doesn't look like a comment, the |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
883 [!] makes no difference for ":dlist", ":dsearch" and ":djump". |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
884 [/] A pattern can be surrounded by '/'. Without '/' only whole words are |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
885 matched, using the pattern "\<pattern\>". Only after the second '/' a |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
886 next command can be appended with '|'. Example: > |
7 | 887 :isearch /string/ | echo "the last one" |
9975
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
888 < For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern |
03fa8a51e9dc
commit https://github.com/vim/vim/commit/e4a3bcf28d92d0bde9ca227ccb40d401038185e5
Christian Brabandt <cb@256bit.org>
parents:
9913
diff
changeset
|
889 is used as a literal string, not as a search pattern. |
7 | 890 |
16447
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
891 ============================================================================== |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
892 7. Using 'tagfunc' *tag-function* |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
893 |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
894 It is possible to provide Vim with a function which will generate a list of |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
895 tags used for commands like |:tag|, |:tselect| and Normal mode tag commands |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
896 like |CTRL-]|. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
897 |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
898 The function used for generating the taglist is specified by setting the |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
899 'tagfunc' option. The function will be called with three arguments: |
30202 | 900 pattern The tag identifier or pattern used during the tag search. |
901 flags String containing flags to control the function behavior. | |
902 info Dict containing the following entries: | |
16447
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
903 buf_ffname Full filename which can be used for priority. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
904 user_data Custom data String, if stored in the tag |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
905 stack previously by tagfunc. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
906 |
30202 | 907 Note that in a legacy function "a:" needs to be prepended to the argument name |
908 when using it. | |
909 | |
24186
4902263c302e
patch 8.2.2634: 'tagfunc' does not indicate using a pattern
Bram Moolenaar <Bram@vim.org>
parents:
23305
diff
changeset
|
910 Currently up to three flags may be passed to the tag function: |
16447
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
911 'c' The function was invoked by a normal command being processed |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
912 (mnemonic: the tag function may use the context around the |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
913 cursor to perform a better job of generating the tag list.) |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
914 'i' In Insert mode, the user was completing a tag (with |
24186
4902263c302e
patch 8.2.2634: 'tagfunc' does not indicate using a pattern
Bram Moolenaar <Bram@vim.org>
parents:
23305
diff
changeset
|
915 |i_CTRL-X_CTRL-]| or 'completeopt' contains `t`). |
4902263c302e
patch 8.2.2634: 'tagfunc' does not indicate using a pattern
Bram Moolenaar <Bram@vim.org>
parents:
23305
diff
changeset
|
916 'r' The first argument to tagfunc should be interpreted as a |
4902263c302e
patch 8.2.2634: 'tagfunc' does not indicate using a pattern
Bram Moolenaar <Bram@vim.org>
parents:
23305
diff
changeset
|
917 |pattern| (see |tag-regexp|), such as when using: > |
4902263c302e
patch 8.2.2634: 'tagfunc' does not indicate using a pattern
Bram Moolenaar <Bram@vim.org>
parents:
23305
diff
changeset
|
918 :tag /pat |
4902263c302e
patch 8.2.2634: 'tagfunc' does not indicate using a pattern
Bram Moolenaar <Bram@vim.org>
parents:
23305
diff
changeset
|
919 < It is also given when completing in insert mode. |
4902263c302e
patch 8.2.2634: 'tagfunc' does not indicate using a pattern
Bram Moolenaar <Bram@vim.org>
parents:
23305
diff
changeset
|
920 If this flag is not present, the argument is usually taken |
4902263c302e
patch 8.2.2634: 'tagfunc' does not indicate using a pattern
Bram Moolenaar <Bram@vim.org>
parents:
23305
diff
changeset
|
921 literally as the full tag name. |
16447
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
922 |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
923 Note that when 'tagfunc' is set, the priority of the tags described in |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
924 |tag-priority| does not apply. Instead, the priority is exactly as the |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
925 ordering of the elements in the list returned by the function. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
926 *E987* |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
927 The function should return a List of Dict entries. Each Dict must at least |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
928 include the following entries and each value must be a string: |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
929 name Name of the tag. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
930 filename Name of the file where the tag is defined. It is |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
931 either relative to the current directory or a full path. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
932 cmd Ex command used to locate the tag in the file. This |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
933 can be either an Ex search pattern or a line number. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
934 Note that the format is similar to that of |taglist()|, which makes it possible |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
935 to use its output to generate the result. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
936 The following fields are optional: |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
937 kind Type of the tag. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
938 user_data String of custom data stored in the tag stack which |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
939 can be used to disambiguate tags between operations. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
940 |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
941 If the function returns |v:null| instead of a List, a standard tag lookup will |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
942 be performed instead. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
943 |
17036 | 944 It is not allowed to change the tagstack from inside 'tagfunc'. *E986* |
30202 | 945 It is not allowed to close a window or change window from inside 'tagfunc'. |
946 *E1299* | |
16447
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
947 |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
948 The following is a hypothetical example of a function used for 'tagfunc'. It |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
949 uses the output of |taglist()| to generate the result: a list of tags in the |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
950 inverse order of file names. |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
951 > |
19303 | 952 function TagFunc(pattern, flags, info) |
953 function CompareFilenames(item1, item2) | |
16447
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
954 let f1 = a:item1['filename'] |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
955 let f2 = a:item2['filename'] |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
956 return f1 >=# f2 ? |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
957 \ -1 : f1 <=# f2 ? 1 : 0 |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
958 endfunction |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
959 |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
960 let result = taglist(a:pattern) |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
961 call sort(result, "CompareFilenames") |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
962 |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
963 return result |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
964 endfunc |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
965 set tagfunc=TagFunc |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
966 < |
54ffc82f38a8
patch 8.1.1228: not possible to process tags with a function
Bram Moolenaar <Bram@vim.org>
parents:
16176
diff
changeset
|
967 |
14421 | 968 vim:tw=78:ts=8:noet:ft=help:norl: |