#$@%#$%!

Ngiler SH3LL 360
: / usr / share / vim / vim80 / doc /

Information Server
MySQL : OFF Perl : OFF CURL : ON WGET : OFF PKEXEC : OFF

Directive	Local Value
IP Address	63.250.38.10
System	Linux premium90.web-hosting.com 4.18.0-553.44.1.lve.el8.x86_64 #1 SMP Thu Mar 13 14:29:12 UTC 2025 x86_64
User	likhxapw
PHP Version	8.3.30
Software	LiteSpeed
Doc root	Writable

Edit File : tagsrch.txt \| Size : 35.78 KB
tagsrch.txt For Vim version 8.0. Last change: 2017 Oct 20 VIM REFERENCE MANUAL by Bram Moolenaar Tags and special searches tags-and-searches See section \|29.1\| of the user manual for an introduction. 1. Jump to a tag \|tag-commands\| 2. Tag stack \|tag-stack\| 3. Tag match list \|tag-matchlist\| 4. Tags details \|tag-details\| 5. Tags file format \|tags-file-format\| 6. Include file searches \|include-search\| ============================================================================== 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][!] {ident} Jump to the definition of {ident}, using the information in the tags file(s). Put {ident} in the tag stack. See \|tag-!\| for [!]. {ident} can be a regexp pattern, see \|tag-regexp\|. When there are several matching tags for {ident}, 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 {ident}", where {ident} is the keyword under or after cursor. When there are several matching tags for {ident}, 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. {Vi: identifier after the cursor} v_CTRL-] {Visual}CTRL-] Same as ":tag {ident}", where {ident} is the text that is highlighted. {not in Vi} 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 {ident}". The ignore-case matches are not found for a ":tag" command when: - the 'ignorecase' option is off and 'tagcase' is "followic" - 'tagcase' is "match" - 'tagcase' is "smart" and the pattern contains an upper case character. - 'tagcase' is "followscs" and 'smartcase' option is on 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 off - when 'tagcase' is "match" - when 'tagcase' is "followscs" and the 'smartcase' option is off 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). {not in Vi} :po :pop E555 E556 :[count]po[p][!] Jump to [count] older entry in tag stack (default 1). See \|tag-!\| for [!]. {not in Vi} :[count]ta[g][!] Jump to [count] newer entry in tag stack (default 1). See \|tag-!\| for [!]. {not in Vi} :tags :tags Show the contents of the tag stack. The active entry is marked with a '>'. {not in Vi} 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 {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/text 1 1 main 1 harddisk2:text/vim/test 2 1 FuncB 59 harddisk2:text/vim/src/main.c 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][!] [ident] List the tags that match [ident], using the information in the tags file(s). When [ident] 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). [ident] can be a regexp pattern, see \|tag-regexp\|. See \|tag-priority\| for the priorities used in the listing. {not in Vi} Example output: > nr 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) Enter nr of choice (<CR> to abort): < 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][!] [ident] Does ":tselect[!] [ident]" and splits the window for the selected tag. {not in Vi} g] g] Like CTRL-], but use ":tselect" instead of ":tag". {not in Vi} v_g] {Visual}g] Same as "g]", but use the highlighted text as the identifier. {not in Vi} :tj :tjump :tj[ump][!] [ident] Like ":tselect", but jump to the tag directly when there is only one match. {not in Vi} :stj :stjump :stj[ump][!] [ident] Does ":tjump[!] [ident]" and splits the window for the selected tag. {not in Vi} g_CTRL-] g CTRL-] Like CTRL-], but use ":tjump" instead of ":tag". {not in Vi} v_g_CTRL-] {Visual}g CTRL-] Same as "g CTRL-]", but use the highlighted text as the identifier. {not in Vi} :tn :tnext :[count]tn[ext][!] Jump to [count] next matching tag (default 1). See \|tag-!\| for [!]. {not in Vi} :tp :tprevious :[count]tp[revious][!] Jump to [count] previous matching tag (default 1). See \|tag-!\| for [!]. {not in Vi} :tN :tNext :[count]tN[ext][!] Same as ":tprevious". {not in Vi} :tr :trewind :[count]tr[ewind][!] Jump to first matching tag. If [count] is given, jump to [count]th matching tag. See \|tag-!\| for [!]. {not in Vi} :tf :tfirst :[count]tf[irst][!] Same as ":trewind". {not in Vi} :tl :tlast :tl[ast][!] Jump to last matching tag. See \|tag-!\| for [!]. {not in Vi} :lt :ltag :lt[ag][!] [ident] Jump to tag [ident] and add the matching tags to a new location list for the current window. [ident] can be a regexp pattern, see \|tag-regexp\|. When [ident] 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 [!]. {not in Vi} 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. {not available when compiled without the \|+quickfix\| feature} :pts :ptselect :pts[elect][!] [ident] Does ":tselect[!] [ident]" and shows the new tag in a "Preview" window. See \|:ptag\| for more info. {not in Vi} :ptj :ptjump :ptj[ump][!] [ident] Does ":tjump[!] [ident]" and shows the new tag in a "Preview" window. See \|:ptag\| for more info. {not in Vi} :ptn :ptnext :[count]ptn[ext][!] ":tnext" in the preview window. See \|:ptag\|. {not in Vi} :ptp :ptprevious :[count]ptp[revious][!] ":tprevious" in the preview window. See \|:ptag\|. {not in Vi} :ptN :ptNext :[count]ptN[ext][!] Same as ":ptprevious". {not in Vi} :ptr :ptrewind :[count]ptr[ewind][!] ":trewind" in the preview window. See \|:ptag\|. {not in Vi} :ptf :ptfirst :[count]ptf[irst][!] Same as ":ptrewind". {not in Vi} :ptl :ptlast :ptl[ast][!] ":tlast" in the preview window. See \|:ptag\|. {not in Vi} ============================================================================== 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. You can still find the tag search pattern in the search history. 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 (when enabled at compile time \|+tag_binary\|). 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' 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. 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/ {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_tags E430 Emacs style tag files are only supported if Vim was compiled with the \|+emacs_tags\| feature enabled. Sorry, there is no explanation about Emacs tag files here, it is only supported for backwards compatibility :-). Lines in Emacs tags files can be very long. Vim only deals with lines of up to about 510 bytes. To see whether lines are ignored set 'verbose' to 5 or higher. 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. Exuberant_ctags exuberant ctags This a very good one. It works for C, C++, Java, Fortran, Eiffel and others. It can generate tags for many items. See http://ctags.sourceforge.net. etags Connected to Emacs. Supports many languages. JTags For Java, in Java. It can be found at http://www.fleiner.com/jtags/. ptags.py For Python, in Python. Found in your Python source directory at Tools/scripts/ptags.py. ptags For Perl, in Perl. It can be found at http://www.eleves.ens.fr:8080/home/nthiery/Tags/. gnatxref For Ada. See http://www.gnuada.org/. gnatxref is part of the gnat package. The lines in the tags file must have one of these three formats: 1. {tagname} {TAB} {tagfile} {TAB} {tagaddress} 2. {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress} 3. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} .. The first 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 <LF> or <CR><LF>. On the Macintosh <CR> also works. The <CR> and <NL> characters can never appear inside a line. tag-old-static The second format is for a static tag only. It is obsolete now, replaced by the third format. It is only supported by Elvis 1.x and Vim 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 third 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 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}. It can be re-enabled by including the \|+tag_any_white\| feature at compile time. tag-any-white {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. {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, but only when compiled with the \|+multi_byte\| feature, 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. (Vi does use 'wrapscan', which caused tags sometimes not be found.) {Vi starts searching in line 2 of another file. It does not find a tag in line 1 of another file when 'wrapscan' is not set} - 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} ============================================================================== 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\|. These commands are not available when the \|+find_in_path\| feature was disabled at compile time. 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 "^#\sdefine", 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 "\^#\sinclude", 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. {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). See \|:search-args\| for [/] and [!]. {not in Vi} [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. {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). See \|:search-args\| for [/] and [!]. {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). See \|:search-args\| for [/] and [!]. {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). See \|:search-args\| for [/] and [!]. {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] [/]string[/] Like "[d" and "]d", but search in [range] lines (default: whole file). See \|:search-args\| for [/] and [!]. {not in Vi} [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. {not in Vi} ]D ]D like "[D", but start at the current cursor position. {not in Vi} :dli :dlist :[range]dli[st][!] [/]string[/] Like `[D` and `]D`, but search in [range] lines (default: whole file). See \|:search-args\| for [/] and [!]. {not in Vi} 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. {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] [/]string[/] Like "[ CTRL-D" and "] CTRL-D", but search in [range] lines (default: whole file). See \|:search-args\| for [/] and [!]. {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] [/]string[/] Like "CTRL-W d", but search in [range] lines (default: whole file). See \|:search-args\| for [/] and [!]. {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} :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. vim:tw=78:ts=8:ft=help:norl: Back

Edit File : tagsrch.txt | Size : 35.78 KB

*tagsrch.txt*   For Vim version 8.0.  Last change: 2017 Oct 20

VIM REFERENCE MANUAL    by Bram Moolenaar

Tags and special searches				*tags-and-searches*

See section |29.1| of the user manual for an introduction.

==============================================================================
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][!] {ident}
			Jump to the definition of {ident}, using the
			information in the tags file(s).  Put {ident} in the
			tag stack.  See |tag-!| for [!].
			{ident} can be a regexp pattern, see |tag-regexp|.
			When there are several matching tags for {ident}, 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 {ident}", where {ident} is the
			keyword under or after cursor.
			When there are several matching tags for {ident}, 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.
			{Vi: identifier after the cursor}

*v_CTRL-]*
{Visual}CTRL-]		Same as ":tag {ident}", where {ident} is the text that
			is highlighted.  {not in Vi}

*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 {ident}".

The ignore-case matches are not found for a ":tag" command when:
- the 'ignorecase' option is off and 'tagcase' is "followic"
- 'tagcase' is "match"
- 'tagcase' is "smart" and the pattern contains an upper case character.
- 'tagcase' is "followscs" and 'smartcase' option is on 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 off
- when 'tagcase' is "match"
- when 'tagcase' is "followscs" and the 'smartcase' option is off

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).  {not in Vi}

*:po* *:pop* *E555* *E556*
:[count]po[p][!]	Jump to [count] older entry in tag stack (default 1).
			See |tag-!| for [!].  {not in Vi}

:[count]ta[g][!]	Jump to [count] newer entry in tag stack (default 1).
			See |tag-!| for [!].  {not in Vi}

*:tags*
:tags			Show the contents of the tag stack.  The active
			entry is marked with a '>'.  {not in Vi}

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 {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/text
   1  1 main		1  harddisk2:text/vim/test
   2  1 FuncB	       59  harddisk2:text/vim/src/main.c

*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][!] [ident]	List the tags that match [ident], using the
			information in the tags file(s).
			When [ident] 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).
			[ident] can be a regexp pattern, see |tag-regexp|.
			See |tag-priority| for the priorities used in the
			listing.  {not in Vi}
			Example output:

>
	 nr 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)
	Enter nr of choice (<CR> to abort):
<
			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][!] [ident]	Does ":tselect[!] [ident]" and splits the window for
			the selected tag.  {not in Vi}

*g]*
g]			Like CTRL-], but use ":tselect" instead of ":tag".
			{not in Vi}

*v_g]*
{Visual}g]		Same as "g]", but use the highlighted text as the
			identifier.  {not in Vi}

*:tj* *:tjump*
:tj[ump][!] [ident]	Like ":tselect", but jump to the tag directly when
			there is only one match.  {not in Vi}

*:stj* *:stjump*
:stj[ump][!] [ident]	Does ":tjump[!] [ident]" and splits the window for the
			selected tag.  {not in Vi}

*g_CTRL-]*
g CTRL-]		Like CTRL-], but use ":tjump" instead of ":tag".
			{not in Vi}

*v_g_CTRL-]*
{Visual}g CTRL-]	Same as "g CTRL-]", but use the highlighted text as
			the identifier.  {not in Vi}

*:tn* *:tnext*
:[count]tn[ext][!]	Jump to [count] next matching tag (default 1).  See
			|tag-!| for [!].  {not in Vi}

*:tp* *:tprevious*
:[count]tp[revious][!]	Jump to [count] previous matching tag (default 1).
			See |tag-!| for [!].  {not in Vi}

*:tN* *:tNext*
:[count]tN[ext][!]	Same as ":tprevious".  {not in Vi}

*:tr* *:trewind*
:[count]tr[ewind][!]	Jump to first matching tag.  If [count] is given, jump
			to [count]th matching tag.  See |tag-!| for [!].  {not
			in Vi}

*:tf* *:tfirst*
:[count]tf[irst][!]	Same as ":trewind".  {not in Vi}

*:tl* *:tlast*
:tl[ast][!]		Jump to last matching tag.  See |tag-!| for [!].  {not
			in Vi}

*:lt* *:ltag*
:lt[ag][!] [ident]	Jump to tag [ident] and add the matching tags to a new
			location list for the current window.  [ident] can be
			a regexp pattern, see |tag-regexp|.  When [ident] 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 [!].
			{not in Vi}

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.
{not available when compiled without the |+quickfix| feature}

*:pts* *:ptselect*
:pts[elect][!] [ident]	Does ":tselect[!] [ident]" and shows the new tag in a
			"Preview" window.  See |:ptag| for more info.
			{not in Vi}

*:ptj* *:ptjump*
:ptj[ump][!] [ident]	Does ":tjump[!] [ident]" and shows the new tag in a
			"Preview" window.  See |:ptag| for more info.
			{not in Vi}

*:ptn* *:ptnext*
:[count]ptn[ext][!]	":tnext" in the preview window.  See |:ptag|.
			{not in Vi}

*:ptp* *:ptprevious*
:[count]ptp[revious][!]	":tprevious" in the preview window.  See |:ptag|.
			{not in Vi}

*:ptN* *:ptNext*
:[count]ptN[ext][!]	Same as ":ptprevious".  {not in Vi}

*:ptr* *:ptrewind*
:[count]ptr[ewind][!]	":trewind" in the preview window.  See |:ptag|.
			{not in Vi}

*:ptf* *:ptfirst*
:[count]ptf[irst][!]	Same as ":ptrewind".  {not in Vi}

*:ptl* *:ptlast*
:ptl[ast][!]		":tlast" in the preview window.  See |:ptag|.
			{not in Vi}

==============================================================================
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.  You can still find the tag search pattern in the search history.
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
(when enabled at compile time |+tag_binary|).  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' 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.

*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/
{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_tags* *E430*
Emacs style tag files are only supported if Vim was compiled with the
|+emacs_tags| feature enabled.  Sorry, there is no explanation about Emacs tag
files here, it is only supported for backwards compatibility :-).

Lines in Emacs tags files can be very long.  Vim only deals with lines of up
to about 510 bytes.  To see whether lines are ignored set 'verbose' to 5 or
higher.

*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.
							*Exuberant_ctags*
exuberant ctags		This a very good one.  It works for C, C++, Java,
			Fortran, Eiffel and others.  It can generate tags for
			many items.  See http://ctags.sourceforge.net.
etags			Connected to Emacs.  Supports many languages.
JTags			For Java, in Java.  It can be found at
			http://www.fleiner.com/jtags/.
ptags.py		For Python, in Python.  Found in your Python source
			directory at Tools/scripts/ptags.py.
ptags			For Perl, in Perl.  It can be found at
			http://www.eleves.ens.fr:8080/home/nthiery/Tags/.
gnatxref		For Ada.  See http://www.gnuada.org/.  gnatxref is
			part of the gnat package.

The lines in the tags file must have one of these three formats:

1.  {tagname}		{TAB} {tagfile} {TAB} {tagaddress}
2.  {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress}
3.  {tagname}		{TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..

The first 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 <LF> or <CR><LF>.  On the Macintosh <CR>
also works.  The <CR> and <NL> characters can never appear inside a line.

*tag-old-static*
The second format is for a static tag only.  It is obsolete now, replaced by
the third format.  It is only supported by Elvis 1.x and Vim 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 third 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 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}.  It can be re-enabled by including the
		|+tag_any_white| feature at compile time. *tag-any-white*
{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.
{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, but only when compiled with the
|+multi_byte| feature, 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.  (Vi
  does use 'wrapscan', which caused tags sometimes not be found.)  {Vi starts
  searching in line 2 of another file.  It does not find a tag in line 1 of
  another file when 'wrapscan' is not set}
- 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}

==============================================================================
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|.

These commands are not available when the |+find_in_path| feature was disabled
at compile time.

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.  {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).
			See |:search-args| for [/] and [!].  {not in Vi}

*[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.  {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).
			See |:search-args| for [/] and [!].  {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).
			See |:search-args| for [/] and [!].  {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).
			See |:search-args| for [/] and [!].  {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] [/]string[/]
			Like "[d"  and "]d", but search in [range] lines
			(default: whole file).
			See |:search-args| for [/] and [!].  {not in Vi}

*[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.  {not in Vi}

*]D*
]D			like "[D", but start at the current cursor position.
			{not in Vi}

*:dli* *:dlist*
:[range]dli[st][!] [/]string[/]
			Like `[D`  and `]D`, but search in [range] lines
			(default: whole file).
			See |:search-args| for [/] and [!].  {not in Vi}
			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.  {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] [/]string[/]
			Like "[ CTRL-D"  and "] CTRL-D", but search  in
			[range] lines (default: whole file).
			See |:search-args| for [/] and [!].  {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] [/]string[/]
			Like "CTRL-W d", but search in [range] lines
			(default: whole file).
			See |:search-args| for [/] and [!].  {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}

*: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.

vim:tw=78:ts=8:ft=help:norl:

Back