| *tagsrch.txt* For Vim version 7.4. Last change: 2013 Oct 01 |
| |
| |
| 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" or when 'tagcase' is |
| "match". They are found when a pattern is used (starting with a "/") and for |
| ":tselect", also when 'ignorecase' is off and 'tagcase' is "followic" or when |
| 'tagcase' is "match". 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. |
| 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 |
| 'ignorecase' is set and 'tagcase' is "followic", or when 'tagcase' is |
| "ignore". 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: |