mirror of https://github.com/neovim/neovim.git
962 lines
39 KiB
Plaintext
962 lines
39 KiB
Plaintext
*tagsrch.txt* Nvim
|
|
|
|
|
|
VIM REFERENCE MANUAL by Bram Moolenaar
|
|
|
|
|
|
Tags and special searches *tags-and-searches*
|
|
|
|
See section |29.1| of the user manual for an introduction.
|
|
|
|
Type |gO| to see the table of contents.
|
|
|
|
==============================================================================
|
|
1. Jump to a tag *tag-commands*
|
|
|
|
*tag* *tags*
|
|
A tag is an identifier that appears in a "tags" file. It is a sort of label
|
|
that can be jumped to. For example: In C programs each function name can be
|
|
used as a tag. The "tags" file has to be generated by a program like ctags,
|
|
before the tag commands can be used.
|
|
|
|
With the ":tag" command the cursor will be positioned on the tag. With the
|
|
CTRL-] command, the keyword on which the cursor is standing is used as the
|
|
tag. If the cursor is not on a keyword, the first keyword to the right of the
|
|
cursor is used.
|
|
|
|
The ":tag" command works very well for C programs. If you see a call to a
|
|
function and wonder what that function does, position the cursor inside of the
|
|
function name and hit CTRL-]. This will bring you to the function definition.
|
|
An easy way back is with the CTRL-T command. Also read about the tag stack
|
|
below.
|
|
|
|
*:ta* *:tag* *E426* *E429*
|
|
:[count]ta[g][!] {name}
|
|
Jump to the definition of {name}, using the
|
|
information in the tags file(s). Put {name} in the
|
|
tag stack. See |tag-!| for [!].
|
|
{name} can be a regexp pattern, see |tag-regexp|.
|
|
When there are several matching tags for {name}, jump
|
|
to the [count] one. When [count] is omitted the
|
|
first one is jumped to. See |tag-matchlist| for
|
|
jumping to other matching tags.
|
|
|
|
g<LeftMouse> *g<LeftMouse>*
|
|
<C-LeftMouse> *<C-LeftMouse>* *CTRL-]*
|
|
CTRL-] Jump to the definition of the keyword under the
|
|
cursor. Same as ":tag {name}", where {name} is the
|
|
keyword under or after cursor.
|
|
When there are several matching tags for {name}, jump
|
|
to the [count] one. When no [count] is given the
|
|
first one is jumped to. See |tag-matchlist| for
|
|
jumping to other matching tags.
|
|
|
|
*v_CTRL-]*
|
|
{Visual}CTRL-] Same as ":tag {name}", where {name} is the text that
|
|
is highlighted.
|
|
|
|
*telnet-CTRL-]*
|
|
CTRL-] is the default telnet escape key. When you type CTRL-] to jump to a
|
|
tag, you will get the telnet prompt instead. Most versions of telnet allow
|
|
changing or disabling the default escape key. See the telnet man page. You
|
|
can `telnet -E {Hostname}` to disable the escape character, or
|
|
`telnet -e {EscapeCharacter} {Hostname}` to specify another escape character.
|
|
If possible, try to use "ssh" instead of "telnet" to avoid this problem.
|
|
|
|
*tag-priority*
|
|
When there are multiple matches for a tag, this priority is used:
|
|
1. "FSC" A full matching static tag for the current file.
|
|
2. "F C" A full matching global tag for the current file.
|
|
3. "F " A full matching global tag for another file.
|
|
4. "FS " A full matching static tag for another file.
|
|
5. " SC" An ignore-case matching static tag for the current file.
|
|
6. " C" An ignore-case matching global tag for the current file.
|
|
7. " " An ignore-case matching global tag for another file.
|
|
8. " S " An ignore-case matching static tag for another file.
|
|
|
|
Note that when the current file changes, the priority list is mostly not
|
|
changed, to avoid confusion when using ":tnext". It is changed when using
|
|
":tag {name}".
|
|
|
|
The ignore-case matches are not found for a ":tag" command when:
|
|
- 'tagcase' is "followic" and the 'ignorecase' option is off
|
|
- 'tagcase' is "followscs" and the 'ignorecase' option is off and the
|
|
'smartcase' option is off or the pattern contains an upper case character.
|
|
- 'tagcase' is "match"
|
|
- 'tagcase' is "smart" and the pattern contains an upper case character.
|
|
|
|
The ignore-case matches are found when:
|
|
- a pattern is used (starting with a "/")
|
|
- for ":tselect"
|
|
- when 'tagcase' is "followic" and 'ignorecase' is on
|
|
- when 'tagcase' is "followscs" and 'ignorecase' is on or the 'smartcase'
|
|
option is on and the pattern does not contain an upper case character
|
|
- when 'tagcase' is "ignore"
|
|
- when 'tagcase' is "smart" and the pattern does not contain an upper case
|
|
character
|
|
|
|
Note that using ignore-case tag searching disables binary searching in the
|
|
tags file, which causes a slowdown. This can be avoided by fold-case sorting
|
|
the tag file. See the 'tagbsearch' option for an explanation.
|
|
|
|
==============================================================================
|
|
2. Tag stack *tag-stack* *tagstack* *E425*
|
|
|
|
On the tag stack is remembered which tags you jumped to, and from where.
|
|
Tags are only pushed onto the stack when the 'tagstack' option is set.
|
|
|
|
g<RightMouse> *g<RightMouse>*
|
|
<C-RightMouse> *<C-RightMouse>* *CTRL-T*
|
|
CTRL-T Jump to [count] older entry in the tag stack
|
|
(default 1).
|
|
|
|
*:po* *:pop* *E555* *E556*
|
|
:[count]po[p][!] Jump to [count] older entry in tag stack (default 1).
|
|
See |tag-!| for [!].
|
|
|
|
:[count]ta[g][!] Jump to [count] newer entry in tag stack (default 1).
|
|
See |tag-!| for [!].
|
|
|
|
*:tags*
|
|
:tags Show the contents of the tag stack. The active
|
|
entry is marked with a '>'.
|
|
|
|
The output of ":tags" looks like this:
|
|
|
|
# TO tag FROM line in file/text
|
|
1 1 main 1 harddisk2:text/vim/test
|
|
> 2 2 FuncA 58 i = FuncA(10);
|
|
3 1 FuncC 357 harddisk2:text/vim/src/amiga.c
|
|
|
|
This list shows the tags that you jumped to and the cursor position before
|
|
that jump. The older tags are at the top, the newer at the bottom.
|
|
|
|
The '>' points to the active entry. This is the tag that will be used by the
|
|
next ":tag" command. The CTRL-T and ":pop" command will use the position
|
|
above the active entry.
|
|
|
|
Below the "TO" is the number of the current match in the match list. Note
|
|
that this doesn't change when using ":pop" or ":tag".
|
|
|
|
The line number and file name are remembered to be able to get back to where
|
|
you were before the tag command. The line number will be correct, also when
|
|
deleting/inserting lines, unless this was done by another program (e.g.
|
|
another instance of Vim).
|
|
|
|
For the current file, the "file/text" column shows the text at the position.
|
|
An indent is removed and a long line is truncated to fit in the window.
|
|
|
|
You can jump to previously used tags with several commands. Some examples:
|
|
|
|
":pop" or CTRL-T to position before previous tag
|
|
{count}CTRL-T to position before {count} older tag
|
|
":tag" to newer tag
|
|
":0tag" to last used tag
|
|
|
|
The most obvious way to use this is while browsing through the call graph of
|
|
a program. Consider the following call graph:
|
|
|
|
main ---> FuncA ---> FuncC
|
|
---> FuncB
|
|
|
|
(Explanation: main calls FuncA and FuncB; FuncA calls FuncC).
|
|
You can get from main to FuncA by using CTRL-] on the call to FuncA. Then
|
|
you can CTRL-] to get to FuncC. If you now want to go back to main you can
|
|
use CTRL-T twice. Then you can CTRL-] to FuncB.
|
|
|
|
If you issue a ":ta {name}" or CTRL-] command, this tag is inserted at the
|
|
current position in the stack. If the stack was full (it can hold up to 20
|
|
entries), the oldest entry is deleted and the older entries shift one
|
|
position up (their index number is decremented by one). If the last used
|
|
entry was not at the bottom, the entries below the last used one are
|
|
deleted. This means that an old branch in the call graph is lost. After the
|
|
commands explained above the tag stack will look like this:
|
|
|
|
# TO tag FROM line in file/text
|
|
1 1 main 1 harddisk2:text/vim/test
|
|
2 1 FuncB 59 harddisk2:text/vim/src/main.c
|
|
|
|
The |gettagstack()| function returns the tag stack of a specified window. The
|
|
|settagstack()| function modifies the tag stack of a window.
|
|
|
|
*tagstack-examples*
|
|
Write to the tag stack just like `:tag` but with a user-defined
|
|
jumper#jump_to_tag function: >
|
|
" Store where we're jumping from before we jump.
|
|
let tag = expand('<cword>')
|
|
let pos = [bufnr()] + getcurpos()[1:]
|
|
let item = {'bufnr': pos[0], 'from': pos, 'tagname': tag}
|
|
if jumper#jump_to_tag(tag)
|
|
" Jump was successful, write previous location to tag stack.
|
|
let winid = win_getid()
|
|
let stack = gettagstack(winid)
|
|
let stack['items'] = [item]
|
|
call settagstack(winid, stack, 't')
|
|
endif
|
|
<
|
|
Set current index of the tag stack to 4: >
|
|
call settagstack(1005, {'curidx' : 4})
|
|
<
|
|
Push a new item onto the tag stack: >
|
|
let pos = [bufnr('myfile.txt'), 10, 1, 0]
|
|
let newtag = [{'tagname' : 'mytag', 'from' : pos}]
|
|
call settagstack(2, {'items' : newtag}, 'a')
|
|
<
|
|
*E73*
|
|
When you try to use the tag stack while it doesn't contain anything you will
|
|
get an error message.
|
|
|
|
==============================================================================
|
|
3. Tag match list *tag-matchlist* *E427* *E428*
|
|
|
|
When there are several matching tags, these commands can be used to jump
|
|
between them. Note that these commands don't change the tag stack, they keep
|
|
the same entry.
|
|
|
|
*:ts* *:tselect*
|
|
:ts[elect][!] [name] List the tags that match [name], using the
|
|
information in the tags file(s).
|
|
When [name] is not given, the last tag name from the
|
|
tag stack is used.
|
|
See |tag-!| for [!].
|
|
With a '>' in the first column is indicated which is
|
|
the current position in the list (if there is one).
|
|
[name] can be a regexp pattern, see |tag-regexp|.
|
|
See |tag-priority| for the priorities used in the
|
|
listing.
|
|
Example output:
|
|
|
|
>
|
|
# pri kind tag file
|
|
1 F f mch_delay os_amiga.c
|
|
mch_delay(msec, ignoreinput)
|
|
> 2 F f mch_delay os_msdos.c
|
|
mch_delay(msec, ignoreinput)
|
|
3 F f mch_delay os_unix.c
|
|
mch_delay(msec, ignoreinput)
|
|
Type number and <Enter> (empty cancels):
|
|
<
|
|
See |tag-priority| for the "pri" column. Note that
|
|
this depends on the current file, thus using
|
|
":tselect xxx" can produce different results.
|
|
The "kind" column gives the kind of tag, if this was
|
|
included in the tags file.
|
|
The "info" column shows information that could be
|
|
found in the tags file. It depends on the program
|
|
that produced the tags file.
|
|
When the list is long, you may get the |more-prompt|.
|
|
If you already see the tag you want to use, you can
|
|
type 'q' and enter the number.
|
|
|
|
*:sts* *:stselect*
|
|
:sts[elect][!] [name] Does ":tselect[!] [name]" and splits the window for
|
|
the selected tag.
|
|
|
|
*g]*
|
|
g] Like CTRL-], but use ":tselect" instead of ":tag".
|
|
|
|
*v_g]*
|
|
{Visual}g] Same as "g]", but use the highlighted text as the
|
|
identifier.
|
|
|
|
*:tj* *:tjump*
|
|
:tj[ump][!] [name] Like ":tselect", but jump to the tag directly when
|
|
there is only one match.
|
|
|
|
*:stj* *:stjump*
|
|
:stj[ump][!] [name] Does ":tjump[!] [name]" and splits the window for the
|
|
selected tag.
|
|
|
|
*g_CTRL-]*
|
|
g CTRL-] Like CTRL-], but use ":tjump" instead of ":tag".
|
|
|
|
*v_g_CTRL-]*
|
|
{Visual}g CTRL-] Same as "g CTRL-]", but use the highlighted text as
|
|
the identifier.
|
|
|
|
*:tn* *:tnext*
|
|
:[count]tn[ext][!] Jump to [count] next matching tag (default 1). See
|
|
|tag-!| for [!].
|
|
|
|
*:tp* *:tprevious*
|
|
:[count]tp[revious][!] Jump to [count] previous matching tag (default 1).
|
|
See |tag-!| for [!].
|
|
|
|
*:tN* *:tNext*
|
|
:[count]tN[ext][!] Same as ":tprevious".
|
|
|
|
*:tr* *:trewind*
|
|
:[count]tr[ewind][!] Jump to first matching tag. If [count] is given, jump
|
|
to [count]th matching tag. See |tag-!| for [!].
|
|
|
|
*:tf* *:tfirst*
|
|
:[count]tf[irst][!] Same as ":trewind".
|
|
|
|
*:tl* *:tlast*
|
|
:tl[ast][!] Jump to last matching tag. See |tag-!| for [!].
|
|
|
|
*:lt* *:ltag*
|
|
:lt[ag][!] [name] Jump to tag [name] and add the matching tags to a new
|
|
location list for the current window. [name] can be
|
|
a regexp pattern, see |tag-regexp|. When [name] is
|
|
not given, the last tag name from the tag stack is
|
|
used. The search pattern to locate the tag line is
|
|
prefixed with "\V" to escape all the special
|
|
characters (very nomagic). The location list showing
|
|
the matching tags is independent of the tag stack.
|
|
See |tag-!| for [!].
|
|
|
|
When there is no other message, Vim shows which matching tag has been jumped
|
|
to, and the number of matching tags: >
|
|
tag 1 of 3 or more
|
|
The " or more" is used to indicate that Vim didn't try all the tags files yet.
|
|
When using ":tnext" a few times, or with ":tlast", more matches may be found.
|
|
|
|
When you didn't see this message because of some other message, or you just
|
|
want to know where you are, this command will show it again (and jump to the
|
|
same tag as last time): >
|
|
:0tn
|
|
<
|
|
*tag-skip-file*
|
|
When a matching tag is found for which the file doesn't exist, this match is
|
|
skipped and the next matching tag is used. Vim reports this, to notify you of
|
|
missing files. When the end of the list of matches has been reached, an error
|
|
message is given.
|
|
|
|
*tag-preview*
|
|
The tag match list can also be used in the preview window. The commands are
|
|
the same as above, with a "p" prepended.
|
|
|
|
*:pts* *:ptselect*
|
|
:pts[elect][!] [name] Does ":tselect[!] [name]" and shows the new tag in a
|
|
"Preview" window. See |:ptag| for more info.
|
|
|
|
*:ptj* *:ptjump*
|
|
:ptj[ump][!] [name] Does ":tjump[!] [name]" and shows the new tag in a
|
|
"Preview" window. See |:ptag| for more info.
|
|
|
|
*:ptn* *:ptnext*
|
|
:[count]ptn[ext][!] ":tnext" in the preview window. See |:ptag|.
|
|
|
|
*:ptp* *:ptprevious*
|
|
:[count]ptp[revious][!] ":tprevious" in the preview window. See |:ptag|.
|
|
|
|
*:ptN* *:ptNext*
|
|
:[count]ptN[ext][!] Same as ":ptprevious".
|
|
|
|
*:ptr* *:ptrewind*
|
|
:[count]ptr[ewind][!] ":trewind" in the preview window. See |:ptag|.
|
|
|
|
*:ptf* *:ptfirst*
|
|
:[count]ptf[irst][!] Same as ":ptrewind".
|
|
|
|
*:ptl* *:ptlast*
|
|
:ptl[ast][!] ":tlast" in the preview window. See |:ptag|.
|
|
|
|
==============================================================================
|
|
4. Tags details *tag-details*
|
|
|
|
*static-tag*
|
|
A static tag is a tag that is defined for a specific file. In a C program
|
|
this could be a static function.
|
|
|
|
In Vi jumping to a tag sets the current search pattern. This means that the
|
|
"n" command after jumping to a tag does not search for the same pattern that
|
|
it did before jumping to the tag. Vim does not do this as we consider it to
|
|
be a bug. If you really want the old Vi behavior, set the 't' flag in
|
|
'cpoptions'.
|
|
|
|
*tag-binary-search*
|
|
Vim uses binary searching in the tags file to find the desired tag quickly.
|
|
But this only works if the tags file was sorted on ASCII byte value.
|
|
Therefore, if no match was found, another try is done with a linear search.
|
|
If you only want the linear search, reset the 'tagbsearch' option. Or better:
|
|
Sort the tags file!
|
|
|
|
Note that the binary searching is disabled when not looking for a tag with a
|
|
specific name. This happens when ignoring case and when a regular expression
|
|
is used that doesn't start with a fixed string. Tag searching can be a lot
|
|
slower then. The former can be avoided by case-fold sorting the tags file.
|
|
See 'tagbsearch' for details.
|
|
|
|
*tag-regexp*
|
|
The ":tag" and ":tselect" commands accept a regular expression argument. See
|
|
|pattern| for the special characters that can be used.
|
|
When the argument starts with '/', it is used as a pattern. If the argument
|
|
does not start with '/', it is taken literally, as a full tag name.
|
|
Examples: >
|
|
:tag main
|
|
< jumps to the tag "main" that has the highest priority. >
|
|
:tag /^get
|
|
< jumps to the tag that starts with "get" and has the highest priority. >
|
|
:tag /norm
|
|
< lists all the tags that contain "norm", including "id_norm".
|
|
When the argument both exists literally, and match when used as a regexp, a
|
|
literal match has a higher priority. For example, ":tag /open" matches "open"
|
|
before "open_file" and "file_open".
|
|
When using a pattern case is ignored. If you want to match case use "\C" in
|
|
the pattern.
|
|
|
|
*tag-!*
|
|
If the tag is in the current file this will always work. Otherwise the
|
|
performed actions depend on whether the current file was changed, whether a !
|
|
is added to the command and on the 'autowrite' and 'winfixbuf' options:
|
|
|
|
tag in file winfixbuf autowrite ~
|
|
current file changed ! option option action ~
|
|
-----------------------------------------------------------------------------
|
|
yes x x off x goto tag
|
|
no no x off x read other file, goto tag
|
|
no yes yes off x abandon current file,
|
|
read other file, goto tag
|
|
no yes no off on write current file,
|
|
read other file, goto tag
|
|
no yes no off off fail
|
|
yes x yes x x goto tag
|
|
no no no on x fail
|
|
no yes no on x fail
|
|
no yes no on on fail
|
|
no yes no on off fail
|
|
-----------------------------------------------------------------------------
|
|
|
|
- If the tag is in the current file, the command will always work.
|
|
- If the tag is in another file and the current file was not changed, the
|
|
other file will be made the current file and read into the buffer.
|
|
- If the tag is in another file, the current file was changed and a ! is
|
|
added to the command, the changes to the current file are lost, the other
|
|
file will be made the current file and read into the buffer.
|
|
- If the tag is in another file, the current file was changed and the
|
|
'autowrite' option is on, the current file will be written, the other
|
|
file will be made the current file and read into the buffer.
|
|
- If the tag is in another file, the current file was changed and the
|
|
'autowrite' option is off, the command will fail. If you want to save
|
|
the changes, use the ":w" command and then use ":tag" without an argument.
|
|
This works because the tag is put on the stack anyway. If you want to lose
|
|
the changes you can use the ":tag!" command.
|
|
- If the tag is in another file and the window includes 'winfixbuf', the
|
|
command will fail. If the tag is in the same file then it may succeed.
|
|
|
|
*tag-security*
|
|
Note that Vim forbids some commands, for security reasons. This works like
|
|
using the 'secure' option for exrc/vimrc files in the current directory. See
|
|
|trojan-horse| and |sandbox|.
|
|
When the {tagaddress} changes a buffer, you will get a warning message:
|
|
"WARNING: tag command changed a buffer!!!"
|
|
In a future version changing the buffer will be impossible. All this for
|
|
security reasons: Somebody might hide a nasty command in the tags file, which
|
|
would otherwise go unnoticed. Example: >
|
|
:$d|/tag-function-name/
|
|
|
|
In Vi the ":tag" command sets the last search pattern when the tag is searched
|
|
for. In Vim this is not done, the previous search pattern is still remembered,
|
|
unless the 't' flag is present in 'cpoptions'.
|
|
|
|
*tags-option*
|
|
The 'tags' option is a list of file names. Each of these files is searched
|
|
for the tag. This can be used to use a different tags file than the default
|
|
file "tags". It can also be used to access a common tags file.
|
|
|
|
The next file in the list is not used when:
|
|
- A matching static tag for the current buffer has been found.
|
|
- A matching global tag has been found.
|
|
This also depends on whether case is ignored. Case is ignored when:
|
|
- 'tagcase' is "followic" and 'ignorecase' is set
|
|
- 'tagcase' is "ignore"
|
|
- 'tagcase' is "smart" and the pattern only contains lower case
|
|
characters.
|
|
- 'tagcase' is "followscs" and 'smartcase' is set and the pattern only
|
|
contains lower case characters.
|
|
If case is not ignored, and the tags file only has a match without matching
|
|
case, the next tags file is searched for a match with matching case. If no
|
|
tag with matching case is found, the first match without matching case is
|
|
used. If case is ignored, and a matching global tag with or without matching
|
|
case is found, this one is used, no further tags files are searched.
|
|
|
|
When a tag file name starts with "./", the '.' is replaced with the path of
|
|
the current file. This makes it possible to use a tags file in the directory
|
|
where the current file is (no matter what the current directory is). The idea
|
|
of using "./" is that you can define which tag file is searched first: In the
|
|
current directory ("tags,./tags") or in the directory of the current file
|
|
("./tags,tags").
|
|
|
|
For example: >
|
|
:set tags=./tags,tags,/home/user/commontags
|
|
|
|
In this example the tag will first be searched for in the file "tags" in the
|
|
directory where the current file is. Next the "tags" file in the current
|
|
directory. If it is not found there, then the file "/home/user/commontags"
|
|
will be searched for the tag.
|
|
|
|
This can be switched off by including the 'd' flag in 'cpoptions', to make
|
|
it Vi compatible. "./tags" will then be the tags file in the current
|
|
directory, instead of the tags file in the directory where the current file
|
|
is.
|
|
|
|
Instead of the comma a space may be used. Then a backslash is required for
|
|
the space to be included in the string option: >
|
|
:set tags=tags\ /home/user/commontags
|
|
|
|
To include a space in a file name use three backslashes. To include a comma
|
|
in a file name use two backslashes. For example, use: >
|
|
:set tags=tag\\\ file,/home/user/common\\,tags
|
|
|
|
for the files "tag file" and "/home/user/common,tags". The 'tags' option will
|
|
have the value "tag\ file,/home/user/common\,tags".
|
|
|
|
If the 'tagrelative' option is on (which is the default) and using a tag file
|
|
in another directory, file names in that tag file are relative to the
|
|
directory where the tag file is.
|
|
|
|
==============================================================================
|
|
5. Tags file format *tags-file-format* *E431*
|
|
|
|
*ctags* *jtags*
|
|
A tags file can be created with an external command, for example "ctags". It
|
|
will contain a tag for each function. Some versions of "ctags" will also make
|
|
a tag for each "#defined" macro, typedefs, enums, etc.
|
|
|
|
Some programs that generate tags files:
|
|
ctags As found on most Unix systems. Only supports C. Only
|
|
does the basic work.
|
|
universal ctags A maintained version of ctags based on exuberant
|
|
ctags. See https://ctags.io.
|
|
*Exuberant_ctags*
|
|
exuberant ctags Works for C, C++, Java, Fortran, Eiffel and others.
|
|
See https://ctags.sourceforge.net. No new version
|
|
since 2009.
|
|
JTags For Java, in Java. It can be found at
|
|
https://www.fleiner.com/jtags/.
|
|
ptags.py For Python, in Python. Found in your Python source
|
|
directory at Tools/scripts/ptags.py.
|
|
|
|
|
|
The lines in the tags file must have one of these two formats:
|
|
|
|
1. {tagname} {TAB} {tagfile} {TAB} {tagaddress}
|
|
2. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..
|
|
|
|
Previously an old format was supported, see |tag-old-static|.
|
|
|
|
The first format is a normal tag, which is completely compatible with Vi. It
|
|
is the only format produced by traditional ctags implementations. This is
|
|
often used for functions that are global, also referenced in other files.
|
|
|
|
The lines in the tags file can end in <NL> or <CR><NL>. On the Macintosh <CR>
|
|
also works. The <CR> and <NL> characters can never appear inside a line.
|
|
|
|
The second format is new. It includes additional information in optional
|
|
fields at the end of each line. It is backwards compatible with Vi. It is
|
|
only supported by new versions of ctags (such as Universal ctags or Exuberant
|
|
ctags).
|
|
|
|
{tagname} The identifier. Normally the name of a function, but it can
|
|
be any identifier. It cannot contain a <Tab>.
|
|
{TAB} One <Tab> character. Note: previous versions allowed any
|
|
white space here. This has been abandoned to allow spaces in
|
|
{tagfile}.
|
|
{tagfile} The file that contains the definition of {tagname}. It can
|
|
have an absolute or relative path. It may contain environment
|
|
variables and wildcards (although the use of wildcards is
|
|
doubtful). It cannot contain a <Tab>.
|
|
{tagaddress} The Ex command that positions the cursor on the tag. It can
|
|
be any Ex command, although restrictions apply (see
|
|
|tag-security|). Posix only allows line numbers and search
|
|
commands, which are mostly used.
|
|
{term} ;" The two characters semicolon and double quote. This is
|
|
interpreted by Vi as the start of a comment, which makes the
|
|
following be ignored. This is for backwards compatibility
|
|
with Vi, it ignores the following fields. Example:
|
|
APP file /^static int APP;$/;" v
|
|
When {tagaddress} is not a line number or search pattern, then
|
|
{term} must be `|;"`. Here the bar ends the command (excluding
|
|
the bar) and `;"` is used to have Vi ignore the rest of the
|
|
line. Example:
|
|
APP file.c call cursor(3, 4)|;" v
|
|
|
|
{field} .. A list of optional fields. Each field has the form:
|
|
|
|
<Tab>{fieldname}:{value}
|
|
|
|
The {fieldname} identifies the field, and can only contain
|
|
alphabetical characters [a-zA-Z].
|
|
The {value} is any string, but cannot contain a <Tab>.
|
|
These characters are special:
|
|
"\t" stands for a <Tab>
|
|
"\r" stands for a <CR>
|
|
"\n" stands for a <NL>
|
|
"\\" stands for a single '\' character
|
|
|
|
There is one field that doesn't have a ':'. This is the kind
|
|
of the tag. It is handled like it was preceded with "kind:".
|
|
See the documentation of ctags for the kinds it produces.
|
|
|
|
The only other field currently recognized by Vim is "file:"
|
|
(with an empty value). It is used for a static tag.
|
|
|
|
|
|
The first lines in the tags file can contain lines that start with
|
|
!_TAG_
|
|
These are sorted to the first lines, only rare tags that start with "!" can
|
|
sort to before them. Vim recognizes two items. The first one is the line
|
|
that indicates if the file was sorted. When this line is found, Vim uses
|
|
binary searching for the tags file:
|
|
!_TAG_FILE_SORTED<Tab>1<Tab>{anything} ~
|
|
|
|
A tag file may be case-fold sorted to avoid a linear search when case is
|
|
ignored. (Case is ignored when 'ignorecase' is set and 'tagcase' is
|
|
"followic", or when 'tagcase' is "ignore".) See 'tagbsearch' for details.
|
|
The value '2' should be used then:
|
|
!_TAG_FILE_SORTED<Tab>2<Tab>{anything} ~
|
|
|
|
The other tag that Vim recognizes is the encoding of the tags file:
|
|
!_TAG_FILE_ENCODING<Tab>utf-8<Tab>{anything} ~
|
|
Here "utf-8" is the encoding used for the tags. Vim will then convert the tag
|
|
being searched for from 'encoding' to the encoding of the tags file. And when
|
|
listing tags the reverse happens. When the conversion fails the unconverted
|
|
tag is used.
|
|
|
|
*tag-search*
|
|
The command can be any Ex command, but often it is a search command.
|
|
Examples:
|
|
tag1 file1 /^main(argc, argv)/ ~
|
|
tag2 file2 108 ~
|
|
|
|
The command is always executed with 'magic' not set. The only special
|
|
characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>).
|
|
See |pattern|. Note that you must put a backslash before each backslash in
|
|
the search text. This is for backwards compatibility with Vi.
|
|
|
|
*E434* *E435*
|
|
If the command is a normal search command (it starts and ends with "/" or
|
|
"?"), some special handling is done:
|
|
- Searching starts on line 1 of the file.
|
|
The direction of the search is forward for "/", backward for "?".
|
|
Note that 'wrapscan' does not matter, the whole file is always searched.
|
|
- If the search fails, another try is done ignoring case. If that fails too,
|
|
a search is done for:
|
|
"^tagname[ \t]*("
|
|
(the tag with '^' prepended and "[ \t]*(" appended). When using function
|
|
names, this will find the function name when it is in column 0. This will
|
|
help when the arguments to the function have changed since the tags file was
|
|
made. If this search also fails another search is done with:
|
|
"^[#a-zA-Z_].*\<tagname[ \t]*("
|
|
This means: A line starting with '#' or an identifier and containing the tag
|
|
followed by white space and a '('. This will find macro names and function
|
|
names with a type prepended.
|
|
|
|
|
|
*tag-old-static*
|
|
Until March 2019 (patch 8.1.1092) an outdated format was supported:
|
|
{tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress}
|
|
|
|
This format is for a static tag only. It is obsolete now, replaced by
|
|
the second format. It is only supported by Elvis 1.x, older Vim versions and
|
|
a few versions of ctags. A static tag is often used for functions that are
|
|
local, only referenced in the file {tagfile}. Note that for the static tag,
|
|
the two occurrences of {tagfile} must be exactly the same. Also see
|
|
|tags-option| below, for how static tags are used.
|
|
|
|
The support was removed, since when you can update to the new Vim version you
|
|
should also be able to update ctags to one that supports the second format.
|
|
|
|
==============================================================================
|
|
6. Include file searches *include-search* *definition-search*
|
|
*E387* *E388* *E389*
|
|
|
|
These commands look for a string in the current file and in all encountered
|
|
included files (recursively). This can be used to find the definition of a
|
|
variable, function or macro. If you only want to search in the current
|
|
buffer, use the commands listed at |pattern-searches|.
|
|
|
|
When a line is encountered that includes another file, that file is searched
|
|
before continuing in the current buffer. Files included by included files are
|
|
also searched. When an include file could not be found it is silently
|
|
ignored. Use the |:checkpath| command to discover which files could not be
|
|
found, possibly your 'path' option is not set up correctly. Note: the
|
|
included file is searched, not a buffer that may be editing that file. Only
|
|
for the current file the lines in the buffer are used.
|
|
|
|
The string can be any keyword or a defined macro. For the keyword any match
|
|
will be found. For defined macros only lines that match with the 'define'
|
|
option will be found. The default is "^#\s*define", which is for C programs.
|
|
For other languages you probably want to change this. See 'define' for an
|
|
example for C++. The string cannot contain an end-of-line, only matches
|
|
within a line are found.
|
|
|
|
When a match is found for a defined macro, the displaying of lines continues
|
|
with the next line when a line ends in a backslash.
|
|
|
|
The commands that start with "[" start searching from the start of the current
|
|
file. The commands that start with "]" start at the current cursor position.
|
|
|
|
The 'include' option is used to define a line that includes another file. The
|
|
default is "\^#\s*include", which is for C programs. Note: Vim does not
|
|
recognize C syntax, if the 'include' option matches a line inside
|
|
"#ifdef/#endif" or inside a comment, it is searched anyway. The 'isfname'
|
|
option is used to recognize the file name that comes after the matched
|
|
pattern.
|
|
|
|
The 'path' option is used to find the directory for the include files that
|
|
do not have an absolute path.
|
|
|
|
The 'comments' option is used for the commands that display a single line or
|
|
jump to a line. It defines patterns that may start a comment. Those lines
|
|
are ignored for the search, unless [!] is used. One exception: When the line
|
|
matches the pattern `"^# *define"` it is not considered to be a comment.
|
|
|
|
If you want to list matches, and then select one to jump to, you could use a
|
|
mapping to do that for you. Here is an example: >
|
|
|
|
:map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " .. nr .. "[\t"<CR>
|
|
<
|
|
*[i*
|
|
[i Display the first line that contains the keyword
|
|
under the cursor. The search starts at the beginning
|
|
of the file. Lines that look like a comment are
|
|
ignored (see 'comments' option). If a count is given,
|
|
the count'th matching line is displayed, and comment
|
|
lines are not ignored.
|
|
|
|
*]i*
|
|
]i like "[i", but start at the current cursor position.
|
|
|
|
*:is* *:isearch*
|
|
:[range]is[earch][!] [count] [/]pattern[/]
|
|
Like "[i" and "]i", but search in [range] lines
|
|
(default: whole file).
|
|
See |:search-args| for [/] and [!].
|
|
|
|
*[I*
|
|
[I Display all lines that contain the keyword under the
|
|
cursor. Filenames and line numbers are displayed
|
|
for the found lines. The search starts at the
|
|
beginning of the file.
|
|
|
|
*]I*
|
|
]I like "[I", but start at the current cursor position.
|
|
|
|
*:il* *:ilist*
|
|
:[range]il[ist][!] [/]pattern[/]
|
|
Like "[I" and "]I", but search in [range] lines
|
|
(default: whole file).
|
|
See |:search-args| for [/] and [!].
|
|
|
|
*[_CTRL-I*
|
|
[ CTRL-I Jump to the first line that contains the keyword
|
|
under the cursor. The search starts at the beginning
|
|
of the file. Lines that look like a comment are
|
|
ignored (see 'comments' option). If a count is given,
|
|
the count'th matching line is jumped to, and comment
|
|
lines are not ignored.
|
|
|
|
*]_CTRL-I*
|
|
] CTRL-I like "[ CTRL-I", but start at the current cursor
|
|
position.
|
|
|
|
*:ij* *:ijump*
|
|
:[range]ij[ump][!] [count] [/]pattern[/]
|
|
Like "[ CTRL-I" and "] CTRL-I", but search in
|
|
[range] lines (default: whole file).
|
|
See |:search-args| for [/] and [!].
|
|
|
|
CTRL-W CTRL-I *CTRL-W_CTRL-I* *CTRL-W_i*
|
|
CTRL-W i Open a new window, with the cursor on the first line
|
|
that contains the keyword under the cursor. The
|
|
search starts at the beginning of the file. Lines
|
|
that look like a comment line are ignored (see
|
|
'comments' option). If a count is given, the count'th
|
|
matching line is jumped to, and comment lines are not
|
|
ignored.
|
|
|
|
*:isp* *:isplit*
|
|
:[range]isp[lit][!] [count] [/]pattern[/]
|
|
Like "CTRL-W i" and "CTRL-W i", but search in
|
|
[range] lines (default: whole file).
|
|
See |:search-args| for [/] and [!].
|
|
|
|
*[d*
|
|
[d Display the first macro definition that contains the
|
|
macro under the cursor. The search starts from the
|
|
beginning of the file. If a count is given, the
|
|
count'th matching line is displayed.
|
|
|
|
*[d-default*
|
|
Jumps to the previous diagnostic in the current buffer
|
|
by default. |vim.diagnostic.jump()| |default-mappings|
|
|
|
|
*]d*
|
|
]d like "[d", but start at the current cursor position.
|
|
|
|
*]d-default*
|
|
Jumps to the next diagnostic in the current buffer by
|
|
default. |vim.diagnostic.jump()| |default-mappings|
|
|
|
|
*:ds* *:dsearch*
|
|
:[range]ds[earch][!] [count] [/]string[/]
|
|
Like "[d" and "]d", but search in [range] lines
|
|
(default: whole file).
|
|
See |:search-args| for [/] and [!].
|
|
|
|
*[D*
|
|
[D Display all macro definitions that contain the macro
|
|
under the cursor. Filenames and line numbers are
|
|
displayed for the found lines. The search starts
|
|
from the beginning of the file.
|
|
|
|
*[D-default*
|
|
Jumps to the first diagnostic in the current buffer by
|
|
default. |vim.diagnostic.jump()| |default-mappings|
|
|
|
|
*]D*
|
|
]D like "[D", but start at the current cursor position.
|
|
|
|
*]D-default*
|
|
Jumps to the last diagnostic in the current buffer by
|
|
default. |vim.diagnostic.jump()| |default-mappings|
|
|
|
|
*:dli* *:dlist*
|
|
:[range]dli[st][!] [/]string[/]
|
|
Like `[D` and `]D`, but search in [range] lines
|
|
(default: whole file).
|
|
See |:search-args| for [/] and [!].
|
|
Note that `:dl` works like `:delete` with the "l"
|
|
flag, not `:dlist`.
|
|
|
|
*[_CTRL-D*
|
|
[ CTRL-D Jump to the first macro definition that contains the
|
|
keyword under the cursor. The search starts from
|
|
the beginning of the file. If a count is given, the
|
|
count'th matching line is jumped to.
|
|
|
|
*]_CTRL-D*
|
|
] CTRL-D like "[ CTRL-D", but start at the current cursor
|
|
position.
|
|
|
|
*:dj* *:djump*
|
|
:[range]dj[ump][!] [count] [/]string[/]
|
|
Like "[ CTRL-D" and "] CTRL-D", but search in
|
|
[range] lines (default: whole file).
|
|
See |:search-args| for [/] and [!].
|
|
|
|
CTRL-W CTRL-D *CTRL-W_CTRL-D* *CTRL-W_d*
|
|
CTRL-W d Open a new window, with the cursor on the first
|
|
macro definition line that contains the keyword
|
|
under the cursor. The search starts from the
|
|
beginning of the file. If a count is given, the
|
|
count'th matching line is jumped to.
|
|
|
|
*CTRL-W_d-default*
|
|
Mapped to |vim.diagnostic.open_float()| by default.
|
|
|default-mappings|
|
|
|
|
*:dsp* *:dsplit*
|
|
:[range]dsp[lit][!] [count] [/]string[/]
|
|
Like "CTRL-W d", but search in [range] lines
|
|
(default: whole file).
|
|
See |:search-args| for [/] and [!].
|
|
|
|
*:checkp* *:checkpath*
|
|
:checkp[ath] List all the included files that could not be found.
|
|
|
|
:checkp[ath]! List all the included files.
|
|
|
|
*:search-args*
|
|
Common arguments for the commands above:
|
|
[!] When included, find matches in lines that are recognized as comments.
|
|
When excluded, a match is ignored when the line is recognized as a
|
|
comment (according to 'comments'), or the match is in a C comment
|
|
(after "//" or inside `/* */`). Note that a match may be missed if a
|
|
line is recognized as a comment, but the comment ends halfway the line.
|
|
And if the line is a comment, but it is not recognized (according to
|
|
'comments') a match may be found in it anyway. Example: >
|
|
/* comment
|
|
foobar */
|
|
< A match for "foobar" is found, because this line is not recognized as
|
|
a comment (even though syntax highlighting does recognize it).
|
|
Note: Since a macro definition mostly doesn't look like a comment, the
|
|
[!] makes no difference for ":dlist", ":dsearch" and ":djump".
|
|
[/] A pattern can be surrounded by "/". Without "/" only whole words are
|
|
matched, using the pattern "\<pattern\>". Only after the second "/" a
|
|
next command can be appended with "|". Example: >
|
|
:isearch /string/ | echo "the last one"
|
|
< For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern
|
|
is used as a literal string, not as a search pattern.
|
|
|
|
==============================================================================
|
|
7. Using 'tagfunc' *tag-function*
|
|
|
|
It is possible to provide Vim with a function which will generate a list of
|
|
tags used for commands like |:tag|, |:tselect| and Normal mode tag commands
|
|
like |CTRL-]|.
|
|
|
|
The function used for generating the taglist is specified by setting the
|
|
'tagfunc' option. The function will be called with three arguments:
|
|
pattern The tag identifier or pattern used during the tag search.
|
|
flags String containing flags to control the function behavior.
|
|
info Dict containing the following entries:
|
|
buf_ffname Full filename which can be used for priority.
|
|
user_data Custom data String, if stored in the tag
|
|
stack previously by tagfunc.
|
|
|
|
Note that "a:" needs to be prepended to the argument name when using it.
|
|
|
|
Currently up to three flags may be passed to the tag function:
|
|
'c' The function was invoked by a normal command being processed
|
|
(mnemonic: the tag function may use the context around the
|
|
cursor to perform a better job of generating the tag list.)
|
|
'i' In Insert mode, the user was completing a tag (with
|
|
|i_CTRL-X_CTRL-]| or 'completeopt' contains `t`).
|
|
'r' The first argument to tagfunc should be interpreted as a
|
|
|pattern| (see |tag-regexp|), such as when using: >
|
|
:tag /pat
|
|
< It is also given when completing in insert mode.
|
|
If this flag is not present, the argument is usually taken
|
|
literally as the full tag name.
|
|
|
|
Note that when 'tagfunc' is set, the priority of the tags described in
|
|
|tag-priority| does not apply. Instead, the priority is exactly as the
|
|
ordering of the elements in the list returned by the function.
|
|
*E987*
|
|
The function should return a List of Dict entries. Each Dict must at least
|
|
include the following entries and each value must be a string:
|
|
name Name of the tag.
|
|
filename Name of the file where the tag is defined. It is
|
|
either relative to the current directory or a full path.
|
|
cmd Ex command used to locate the tag in the file. This
|
|
can be either an Ex search pattern or a line number.
|
|
Note that the format is similar to that of |taglist()|, which makes it possible
|
|
to use its output to generate the result.
|
|
The following fields are optional:
|
|
kind Type of the tag.
|
|
user_data String of custom data stored in the tag stack which
|
|
can be used to disambiguate tags between operations.
|
|
|
|
If the function returns |v:null| instead of a List, a standard tag lookup will
|
|
be performed instead.
|
|
|
|
It is not allowed to change the tagstack from inside 'tagfunc'. *E986*
|
|
It is not allowed to close a window or change window from inside 'tagfunc'.
|
|
*E1299*
|
|
|
|
The following is a hypothetical example of a function used for 'tagfunc'. It
|
|
uses the output of |taglist()| to generate the result: a list of tags in the
|
|
inverse order of file names.
|
|
>
|
|
function TagFunc(pattern, flags, info)
|
|
function CompareFilenames(item1, item2)
|
|
let f1 = a:item1['filename']
|
|
let f2 = a:item2['filename']
|
|
return f1 >=# f2 ?
|
|
\ -1 : f1 <=# f2 ? 1 : 0
|
|
endfunction
|
|
|
|
let result = taglist(a:pattern)
|
|
call sort(result, "CompareFilenames")
|
|
|
|
return result
|
|
endfunc
|
|
set tagfunc=TagFunc
|
|
<
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|