This is tagsearch.txt in view mode; [Download] [Up]
*tagsearch.txt* For Vim version 5.0f. Last modification: 1997 Apr 13
VIM REFERENCE MANUAL by Bram Moolenaar
Tags and special searches *tags_and_searches*
1. Tags |tag_commands|
2. Include file searches |include_search|
==============================================================================
1. Tags *tag_commands*
*:ta* *:tag*
:ta[g][!] {ident} Jump to the definition of {ident}, using the
information in the tags file. Put {ident} in the tag
stack. See below for [!].
g<LeftMouse> *g<LeftMouse>*
<C-LeftMouse> *<C-LeftMouse>* *CTRL-]*
CTRL-] ":ta" to the keyword under or after cursor. Put the
keyword in the tag stack. {Vi: identifier after the
cursor}
*v_CTRL-]*
{Visual}CTRL-] ":ta" to the text that is highlighted. {not in Vi}
g<RightMouse> *g<RightMouse>*
<C-RightMouse> *<C-RightMouse>* *CTRL-T*
CTRL-T Jump to [count] older entry in the tag stack
(default 1). {not in Vi}
*:po* *:pop*
:[count]po[p][!] Jump to [count] older entry in tag stack (default 1).
See below for [!]. {not in Vi}
:[count]ta[g][!] Jump to [count] newer entry in tag stack (default 1).
See below for [!]. {not in Vi}
*:tags*
:tags Show the contents of the tag stack. The active
entry is marked with a '>'. {not in Vi}
*tags*
A tag is an identifier that appears in the "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.
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.
*telnet-CTRL-]*
CTRL-] is the 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 "rsh" instead of "telnet" to avoid this problem.
*tag_priority*
When there are multiple matches for a tag, this priority is used:
1. The first matching static tag with a full matching tag for the current
file.
2. The first matching global tag with a full matching tag.
3. The first matching static tag with a full matching tag for another file.
4. The first matching static tag with an ignore-case matching tag for the
current file.
5. The first matching global tag with an ignore-case matching tag.
6. The first matching static tag with an ignore-case matching tag for another
file.
*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. You can still find the tag search pattern in the search history.
If you really want the old Vi behaviour, set the 't' flag in 'cpoptions'.
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' option:
tag in file autowrite
current file changed ! option action
-----------------------------------------------------------------------------
yes x x x goto tag
no no x x read other file, goto tag
no yes yes x abandon current file, read other file, goto
tag
no yes no on write current file, read other file, goto
tag
no yes no 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.
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.
A tags file can be created with the external command "ctags". It will
contain a tag for each function. Some versions of "ctags" will also make a
tag for each "#defined" macro.
The lines in the tags file must have one of these two formats:
{tag}{separator}{filename}{separator}{command}
{filename}:{tag}{separator}{filename}{separator}{command}
The first is a normal tag, the second is a static tag. A normal tag is often
used for functions that are global, also referenced in other files. A static
tag is often used for functions that are local, only referenced in the file
{filename}. Note that for the static tag, the two occurances of {filename}
must be exactly the same. Also see |tags_option| below, for how static tags
are used.
{tag} The identifier. Normally the name of a function, but it can
be any identifier. It cannot contain white space.
{separator} One or more <Tab> or space characters.
{filename} The file that contains the definition of {tag}. It may
contain environment variables and wildcards (although the use
of wildcards is doubtful).
{command} The Ex command that positions the cursor on the tag.
*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 "$" (end-of-line).
See |search_pattern|. Note that you must put a backslash before each
backslash in the search text. This is for backwards compatibility with Vi.
If the command is a normal search command (it starts end ends with "/" or
"?"), some special handling is done:
- Searching starts on the current line of the current file, unless the tag is
in another file, in which case the search starts in line 1 of that file.
The direction of the search is forward for "/", backward for "?".
- 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. {the extra searches are not in Vi}.
*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|.
When the {command} 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/".
{this security prevention is not present in Vi}.
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'. The search pattern is always
put in the search history, so you can modify it if searching fails.
*emacs_tags*
Emacs style tag files are supported if Vim was compiled with EMACS_TAGS
defined. Check the output of ":version", if it contains "+emacs_tags" then it
was. Sorry, there is no explanation about Emacs tag files here, it is only
supported for backwards compatibility :-).
*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 the 'ignorecase' option. If it is off, 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 'ignorecase' is on, 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 than 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.
*tagstack*
The tags that you use are remembered in the tag stack. You can print this
stack with the ":tags" command. The result looks like this:
# TO tag FROM line in file
1 main 1 harddisk2:text/vim/test
> 2 FuncA 58 -current-
3 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.
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).
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 {ident}" 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
1 main 1 harddisk2:text/vim/test
2 FuncB 59 harddisk2:text/vim/src/main.c
>
==============================================================================
2. Include file searches *include_search*
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 "\^#[ \t]*define", which is for C
programs. Also, 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 "\^#[ \t]*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.
*[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. {not in Vi}
*]i*
]i like "[i", but start at the current cursor position.
{not in Vi}
*:is* *:isearch*
:[range]is[earch][!] [count] [/]pattern[/]
Like "[i" and "]i", but search in [range] lines
(default: whole file). Without [!] lines that are
recognized as comments are skipped. Without [/] only
whole words are matched, using the pattern
"\<pattern\>". {not in Vi}
*[I*
[I Display all lines that contain the keyword under the
cursor. File names and line numbers are displayed
for the found lines. The search starts at the
beginning of the file. {not in Vi}
*]I*
]I like "[I", but start at the current cursor position.
{not in Vi}
*:il* *:ilist*
:[range]il[ist][!] [/]pattern[/]
Like "[I" and "]I", but search in [range] lines
(default: whole file). Without [!] lines that are
recognized as comments are skipped. Without [/] only
whole words are matched, using the pattern
"\<pattern\>". {not in Vi}
*[_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. {not in Vi}
*]_CTRL-I*
] CTRL-I like "[ CTRL-I", but start at the current cursor
position. {not in Vi}
*:ij* *:ijump*
:[range]ij[ump][!] [count] [/]pattern[/]
Like "[ CTRL-I" and "] CTRL-I", but search in
[range] lines (default: whole file). Without [!]
lines that are recognized as comments are skipped.
Without [/] only whole words are matched, using the
pattern "\<pattern\>". {not in Vi}
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. {not in Vi}
*:isp* *:isplit*
:[range]isp[lit][!] [count] [/]pattern[/]
Like "CTRL-W i" and "CTRL-W i", but search in
[range] lines (default: whole file). Without [!]
lines that are recognized as comments are skipped.
Without [/] only whole words are matched, using the
pattern "\<pattern\>". {not in Vi}
*[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. {not in Vi}
*]d*
]d like "[d", but start at the current cursor position.
{not in Vi}
*:ds* *:dsearch*
:[range]ds[earch][!] [count] [/]pattern[/]
Like "[d" and "]d", but search in [range] lines
(default: whole file). Without [!] lines that are
recognized as comments are skipped. Without [/] only
whole words are matched, using the pattern
"\<pattern\>". {not in Vi}
*[D*
[D Display all macro definitions that contain the macro
under the cursor. File names and line numbers are
displayed for the found lines. The search starts
from the beginning of the file. {not in Vi}
*]D*
]D like "[D", but start at the current cursor position.
{not in Vi}
*:dl* *:dlist*
:[range]dl[ist][!] [/]pattern[/]
Like "[D" and "]D", but search in [range] lines
(default: whole file). Without [!] lines that are
recognized as comments are skipped. Without [/] only
whole words are matched, using the pattern
"\<pattern\>". {not in Vi}
*[_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. {not in Vi}
*]_CTRL-D*
] CTRL-D like "[ CTRL-D", but start at the current cursor
position. {not in Vi}
*:dj* *:djump*
:[range]dj[ump][!] [count] [/]pattern[/]
Like "[ CTRL-D" and "] CTRL-D", but search in
[range] lines (default: whole file). Without [!]
lines that are recognized as comments are skipped.
Without [/] only whole words are matched, using the
pattern "\<pattern\>". {not in Vi}
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. {not in Vi}
*:dsp* *:dsplit*
:[range]dsp[lit][!] [count] [/]pattern[/]
Like "CTRL-W d", but search in [range] lines
(default: whole file). Without [!] lines that are
recognized as comments are skipped. Without [/] only
whole words are matched, using the pattern
"\<pattern\>". {not in Vi}
*:che* *:checkpath*
:che[ckpath] List all the included files that could not be found.
{not in Vi}
:che[ckpath]! List all the included files. {not in Vi}
vim:tw=78:ts=8:sw=8:
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.