diff options
Diffstat (limited to '')
-rw-r--r-- | runtime/doc/tagsrch.txt | 960 |
1 files changed, 960 insertions, 0 deletions
diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt new file mode 100644 index 0000000..f90632c --- /dev/null +++ b/runtime/doc/tagsrch.txt @@ -0,0 +1,960 @@ +*tagsrch.txt* For Vim version 9.0. Last change: 2023 Feb 13 + + + 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| +7. Using 'tagfunc' |tag-function| + +============================================================================== +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. +{not available when compiled without the |+quickfix| feature} + + *: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 +(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/ + +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'. + + *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. Non-Emacs tags file lines can be any length. + + *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 This is 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. + No new version since 2009. +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 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|. + +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. + + *]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* +]d like "[d", but start at the current cursor position. + + *: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* +]D like "[D", but start at the current cursor position. + + *: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. + + *:dsp* *:dsplit* +:[range]dsp[lit][!] [count] [/]string[/] + Like "CTRL-W d", but search in [range] lines + (default: whole file). + See |:search-args| for [/] and [!]. + + *:che* *:chec* *:check* *:checkpath* +:che[ckpath] List all the included files that could not be found. + +:che[ckpath]! 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 in a legacy function "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: |