home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / vim53os2.zip / vim-5.3 / doc / tagsearch.txt < prev    next >
Text File  |  1998-08-30  |  32KB  |  745 lines
  1. *tagsearch.txt* For Vim version 5.3.  Last modification: 1998 Aug 30
  2.  
  3.  
  4.           VIM REFERENCE MANUAL    by Bram Moolenaar
  5.  
  6.  
  7. Tags and special searches                *tags-and-searches*
  8.  
  9. 1. Jump to a tag        |tag-commands|
  10. 2. Tag stack            |tag-stack|
  11. 3. Tag match list        |tag-matchlist|
  12. 4. Tags details            |tag-details|
  13. 5. Tags file format        |tags-file-format|
  14. 6. Include file searches    |include-search|
  15. 7. 'Grep' and 'Lid'        |:grep|
  16.  
  17. ==============================================================================
  18. 1. Jump to a tag                    *tag-commands*
  19.  
  20.                             *tags*
  21. A tag is an identifier that appears in a "tags" file.  It is a sort of label
  22. that can be jumped to.  For example: In C programs each function name can be
  23. used as a tag.  The "tags" file has to be generated by a program like ctags,
  24. before the tag commands can be used.
  25.  
  26. With the ":tag" command the cursor will be positioned on the tag.  With the
  27. CTRL-] command, the keyword on which the cursor is standing is used as the
  28. tag.  If the cursor is not on a keyword, the first keyword to the right of the
  29. cursor is used.
  30.  
  31. The ":tag" command works very well for C programs.  If you see a call to a
  32. function and wonder what that function does, position the cursor inside of the
  33. function name and hit CTRL-].  This will bring you to the function definition.
  34. An easy way back is with the CTRL-T command.  Also read about the tag stack
  35. below.
  36.  
  37.                             *:ta* *:tag*
  38. :ta[g][!] {ident}    Jump to the definition of {ident}, using the
  39.             information in the tags file(s).  Put {ident} in the
  40.             tag stack.  See |tag-!| for [!].
  41.             {ident} can be a regexp pattern, see |tag-regexp|.
  42.             When there are several matching tags for {ident}, the
  43.             first one is jumped to. |:tnext|.
  44.  
  45. g<LeftMouse>                        *g<LeftMouse>*
  46. <C-LeftMouse>                    *<C-LeftMouse>* *CTRL-]*
  47. CTRL-]            Same as ":tag {ident}", where {ident} is the keyword
  48.             under or after cursor.  {Vi: identifier after the
  49.             cursor}
  50.  
  51.                             *v_CTRL-]*
  52. {Visual}CTRL-]        Same as ":tag {ident}", where {ident} is the text that
  53.             is highlighted.  {not in Vi}
  54.  
  55.                             *telnet-CTRL-]*
  56. CTRL-] is the the default telnet escape key.  When you type CTRL-] to jump to
  57. a tag, you will get the telnet prompt instead.  Most versions of telnet allow
  58. changing or disabling the default escape key.  See the telnet man page.  You
  59. can 'telnet -E <Hostname>' to disable the escape character, or 'telnet -e
  60. <EscapeCharacter> <Hostname>' to specify another escape character.  If
  61. possible, try to use "rsh" instead of "telnet" to avoid this problem.
  62.  
  63.                             *tag-priority*
  64. When there are multiple matches for a tag, this priority is used:
  65. 1. "FSC"  A full matching static tag for the current file.
  66. 2. "F C"  A full matching global tag for the current file.
  67. 3. "F  "  A full matching global tag for another file.
  68. 4. "FS "  A full matching static tag for another file.
  69. 5. " SC"  An ignore-case matching static tag for the current file.
  70. 6. "  C"  An ignore-case matching global tag for the current file.
  71. 7. "   "  An ignore-case matching global tag for another file.
  72. 8. " S "  An ignore-case matching static tag for another file.
  73.  
  74. Note that when the current file changes, the priority list is mostly not
  75. changed, to avoid confusion when using ":tnext".  It is changed when using
  76. ":tag {ident}".
  77.  
  78. ==============================================================================
  79. 2. Tag stack                        *tag-stack* *tagstack*
  80.  
  81. On the tag stack is remembered which tags you jumped to, and from where.
  82.  
  83. g<RightMouse>                        *g<RightMouse>*
  84. <C-RightMouse>                    *<C-RightMouse>* *CTRL-T*
  85. CTRL-T            Jump to [count] older entry in the tag stack
  86.             (default 1).  {not in Vi}
  87.  
  88.                             *:po* *:pop*
  89. :[count]po[p][!]    Jump to [count] older entry in tag stack (default 1).
  90.             See |tag-!| for [!].  {not in Vi}
  91.  
  92. :[count]ta[g][!]    Jump to [count] newer entry in tag stack (default 1).
  93.             See |tag-!| for [!].  {not in Vi}
  94.  
  95.                             *:tags*
  96. :tags            Show the contents of the tag stack.  The active
  97.             entry is marked with a '>'.  {not in Vi}
  98.  
  99. The output of ":tags" looks like this:
  100.  
  101.    # TO tag      FROM line in file
  102.    1  1 main         1  harddisk2:text/vim/test
  103.  > 2  2 FuncA        58  -current-
  104.    3  1 FuncC           357  harddisk2:text/vim/src/amiga.c
  105.  
  106. This list shows the tags that you jumped to and the cursor position before
  107. that jump.  The older tags are at the top, the newer at the bottom.
  108.  
  109. The '>' points to the active entry.  This is the tag that will be used by the
  110. next ":tag" command.  The CTRL-T and ":pop" command will use the position
  111. above the active entry.
  112.  
  113. Below the "TO" is the number of the current match in the match list.  Note
  114. that this doesn't change when using ":pop" or ":tag".
  115.  
  116. The line number and file name are remembered to be able to get back to where
  117. you were before the tag command.  The line number will be correct, also when
  118. deleting/inserting lines, unless this was done by another program (e.g.
  119. another instance of Vim).
  120.  
  121. You can jump to previously used tags with several commands.  Some examples:
  122.  
  123.     ":pop" or CTRL-T    to position before previous tag
  124.     {count}CTRL-T        to position before {count} older tag
  125.     ":tag"            to newer tag
  126.     ":0tag"            to last used tag
  127.  
  128. The most obvious way to use this is while browsing through the call graph of
  129. a program.  Consider the following call graph:
  130.  
  131.     main  --->  FuncA  --->  FuncC
  132.           --->  FuncB
  133.  
  134. (Explanation: main calls FuncA and FuncB; FuncA calls FuncC).
  135. You can get from main to FuncA by using CTRL-] on the call to FuncA.  Then
  136. you can CTRL-] to get to FuncC.  If you now want to go back to main you can
  137. use CTRL-T twice.  Then you can CTRL-] to FuncB.
  138.  
  139. If you issue a ":ta {ident}" or CTRL-] command, this tag is inserted at the
  140. current position in the stack.  If the stack was full (it can hold up to 20
  141. entries), the oldest entry is deleted and the older entries shift one
  142. position up (their index number is decremented by one).  If the last used
  143. entry was not at the bottom, the entries below the last used one are
  144. deleted.  This means that an old branch in the call graph is lost.  After the
  145. commands explained above the tag stack will look like this:
  146.  
  147.    # TO tag    FROM line in file
  148.    1 main           1  harddisk2:text/vim/test
  149.    2 FuncB          59  harddisk2:text/vim/src/main.c
  150.  >
  151.  
  152. ==============================================================================
  153. 3. Tag match list                    *tag-matchlist*
  154.  
  155. When there are several matching tags, these commands can be used to jump
  156. between them.  Note that these command don't change the tag stack, they keep
  157. the same entry.
  158.  
  159.                             *:ts* *:tselect*
  160. :ts[elect][!] [ident]    List the tags that match [ident], using the
  161.             information in the tags file(s).
  162.             When [ident] is not given, the last tag name from the
  163.             tag stack is used.
  164.             With a '>' in the first column is indicated which is
  165.             the current position in the list (if there is one).
  166.             [ident] can be a regexp pattern, see |tag-regexp|.
  167.             See |tag-priority| for the priorities used in the
  168.             listing.  {not in Vi}
  169.             Example output:
  170.  
  171.      nr pri kind tag        file ~
  172. >      1 F    f    mch_delay        os_amiga.c
  173. >            mch_delay(msec, ignoreinput)
  174. >    > 2 F    f    mch_delay        os_msdos.c
  175. >            mch_delay(msec, ignoreinput)
  176. >      3 F    f    mch_delay        os_unix.c
  177. >            mch_delay(msec, ignoreinput)
  178. >    Enter nr of choice (<CR> to abort):
  179.  
  180.             See |tag-priority| for the "pri" column.  Note that
  181.             this depends on the current file, thus using
  182.             ":tselect xxx" can produce different results.
  183.             The "kind" column gives the kind of tag, if this was
  184.             included in the tags file.
  185.             The "info" column shows information that could be
  186.             found in the tags file.  It depends on the program
  187.             that produced the tags file.
  188.             When the list is long, you may get the |more-prompt|.
  189.             If you already see the tag you want to use, you can
  190.             type 'q' and enter the number.
  191.  
  192.                             *:sts* *:stselect*
  193. :sts[elect][!] [ident]
  194.             Does ":tselect[!] [ident]" and splits the window for
  195.             the selected tag.  {not in Vi}
  196.  
  197.                             *g]*
  198. g]            Like CTRL-], but use ":tselect" instead of ":tag".
  199.             {not in Vi}
  200.  
  201.                             *:tj* *:tjump*
  202. :tj[ump][!] [ident]    Like ":tselect", but jump to the tag directly when
  203.             there is only one match.  {not in Vi}
  204.  
  205.                             *:stj* *:stjump*
  206. :stj[ump][!] [ident]    Does ":tjump[!] [ident]" and splits the window for the
  207.             selected tag.  {not in Vi}
  208.  
  209.                             *gCTRL-]*
  210. g CTRL-]        Like CTRL-], but use ":tjump" instead of ":tag".
  211.             {not in Vi}
  212.  
  213.                             *:tn* *:tnext*
  214. :[count]tn[ext][!]    Jump to [count] next matching tag (default 1).  See
  215.             |tag-!| for [!].  {not in Vi}
  216.  
  217.                             *:tp* *:tprevious*
  218. :[count]tp[revious][!]    Jump to [count] previous matching tag (default 1).
  219.             See |tag-!| for [!].  {not in Vi}
  220.  
  221.                             *:tN* *:tNext*
  222. :[count]tN[ext][!]    Same as ":tprevious".  {not in Vi}
  223.  
  224.                             *:tr* *:trewind*
  225. :[count]tr[ewind][!]    Jump to first matching tag.  If [count] is given, jump
  226.             to [count]th matching tag.  See |tag-!| for [!].  {not
  227.             in Vi}
  228.  
  229.                             *:tl* *:tlast*
  230. :tl[ast][!]        Jump to last matching tag.  See |tag-!| for [!].  {not
  231.             in Vi}
  232.  
  233. When there is no other message, Vim shows which matching tag has been jumped
  234. to, and the number of matching tags:
  235. >    tag 1 of 3 or more
  236. The " or more" is used to indicate that Vim didn't try all the tags files yet.
  237. When using ":tnext" a few times, or with ":tlast", more matches may be found.
  238.  
  239. When you didn't see this message because of some other message, or you just
  240. want to know where you are, this command will show it again (and jump to the
  241. same tag as last time):
  242. >    :0tn
  243.  
  244.                             *tag-skip-file*
  245. When a matching tag is found for which the file doesn't exist, this match is
  246. skipped and the next matching tag is used.  Vim reports this, to notify you of
  247. missing files.  When the end of the list of matches has been reached, an error
  248. message is given.
  249.  
  250. ==============================================================================
  251. 4. Tags details                        *tag-details*
  252.  
  253.                             *static-tag*
  254. A static tag is a tag that is defined for a specific file.  In a C program
  255. this could be a static function.
  256.  
  257. In Vi jumping to a tag sets the current search pattern.  This means that
  258. the "n" command after jumping to a tag does not search for the same pattern
  259. that it did before jumping to the tag.  Vim does not do this as we consider it
  260. to be a bug.  You can still find the tag search pattern in the search history.
  261. If you really want the old Vi behaviour, set the 't' flag in 'cpoptions'.
  262.  
  263.                             *tag-binary-search*
  264. Vim uses binary searching in the tags file to find the desired tag quickly
  265. (when enabled at compile time |+tag_binary|).  But this only works if the
  266. tags file was sorted on ASCII byte value.  Therefore, if no match was found,
  267. another try is done with a linear search.  If you only want the linear search,
  268. reset the 'tagbsearch' option.  Or better: Sort the tags file!
  269.  
  270.                             *tag-regexp*
  271. The ":tag" and "tselect" commands accept a regular expression argument.  See
  272. |pattern| for the special characters that can be used.
  273. When the argument starts with '/', it is used as a pattern.  If the argument
  274. does not start with '/', it is taken literally, as a full tag name.
  275. Examples:
  276. >    :tag main
  277.   jumps to the tag "main" that has the highest priority.
  278. >    :tag /^get
  279.   jumps to the tag that starts with "get" and has the highest priority.
  280. >    :tag /norm
  281.   lists all the tags that contain "norm", including "id_norm".
  282. When the argument both exists literally, and match when used as a regexp, a
  283. literal match has a higher priority.  For example, ":tag /open" matches "open"
  284. before "open_file" and "file_open".
  285.  
  286.                             *tag-!*
  287. If the tag is in the current file this will always work.  Otherwise the
  288. performed actions depend on whether the current file was changed, whether a !
  289. is added to the command and on the 'autowrite' option:
  290.  
  291.   tag in       file       autowrite            ~
  292. current file  changed    !   option      action    ~
  293. -----------------------------------------------------------------------------
  294.     yes         x    x     x      goto tag
  295.     no         no    x     x      read other file, goto tag
  296.     no        yes    yes    x   abandon current file, read other file, goto
  297.                   tag
  298.     no        yes    no    on  write current file, read other file, goto
  299.                   tag
  300.     no        yes    no   off  fail
  301. -----------------------------------------------------------------------------
  302.  
  303. - If the tag is in the current file, the command will always work.
  304. - If the tag is in another file and the current file was not changed, the
  305.   other file will be made the current file and read into the buffer.
  306. - If the tag is in another file, the current file was changed and a ! is
  307.   added to the command, the changes to the current file are lost, the other
  308.   file will be made the current file and read into the buffer.
  309. - If the tag is in another file, the current file was changed and the
  310.   'autowrite' option is on, the current file will be written, the other
  311.   file will be made the current file and read into the buffer.
  312. - If the tag is in another file, the current file was changed and the
  313.   'autowrite' option is off, the command will fail.  If you want to save
  314.   the changes, use the ":w" command and then use ":tag" without an argument.
  315.   This works because the tag is put on the stack anyway.  If you want to lose
  316.   the changes you can use the ":tag!" command.
  317.  
  318.                             *tag-security*
  319. Note that Vim forbids some commands, for security reasons.  This works like
  320. using the 'secure' option for exrc/vimrc files in the current directory.  See
  321. |trojan-horse|.
  322. When the {tagaddress} changes a buffer, you will get a warning message:
  323.     "WARNING: tag command changed a buffer!!!"
  324. In a future version changing the buffer will be impossible.  All this for
  325. security reasons: Somebody might hide a nasty command in the tags file, which
  326. would otherwise go unnoticed.  Example:
  327. >    :$d|/tag-function-name/
  328. {this security prevention is not present in Vi}.
  329.  
  330. In Vi the ":tag" command sets the last search pattern when the tag is searched
  331. for.  In Vim this is not done, the previous search pattern is still remembered,
  332. unless the 't' flag is present in 'cpoptions'.  The search pattern is always
  333. put in the search history, so you can modify it if searching fails.
  334.  
  335.                         *emacs-tags* *emacs_tags*
  336. Emacs style tag files are only supported if Vim was compiled with the
  337. |+emacs_tags| feature enabled.  Sorry, there is no explanation about Emacs tag
  338. files here, it is only supported for backwards compatibility :-).
  339.  
  340.                             *tags-option*
  341. The 'tags' option is a list of file names.  Each of these files is searched
  342. for the tag.  This can be used to use a different tags file than the default
  343. file "tags".  It can also be used to access a common tags file.
  344.  
  345. The next file in the list is not used when:
  346. - A matching static tag for the current buffer has been found.
  347. - A matching global tag has been found.
  348. This also depends on the 'ignorecase' option.  If it is off, and the tags file
  349. only has a match without matching case, the next tags file is searched for a
  350. match with matching case.  If no tag with matching case is found, the first
  351. match without matching case is used.  If 'ignorecase' is on, and a matching
  352. global tag with or without matching case is found, this one is used, no
  353. further tags files are searched.
  354.  
  355. When a tag file name starts with "./", the '.' is replaced with the path of
  356. the current file.  This makes it possible to use a tags file in the directory
  357. where the current file is (no matter what the current directory is).  The idea
  358. of using "./" is that you can define which tag file is searched first: In the
  359. current directory ("tags,./tags") or in the directory of the current file
  360. ("./tags,tags").
  361.  
  362. For example:
  363. >    :set tags=./tags,tags,/home/user/commontags
  364.  
  365. In this example the tag will first be searched for in the file "tags" in the
  366. directory where the current file is.  Next the "tags" file in the current
  367. directory.  If it is not found there, then the file "/home/user/commontags"
  368. will be searched for the tag.
  369.  
  370. This can be switched off by including the 'd' flag in 'cpoptions', to make
  371. it Vi compatible.  "./tags" will than be the tags file in the current
  372. directory, instead of the tags file in the directory where the current file
  373. is.
  374.  
  375. Instead of the comma a space may be used.  Then a backslash is required for
  376. the space to be included in the string option:
  377. >    :set tags=tags\ /home/user/commontags
  378.  
  379. To include a space in a file name use three backslashes.  To include a comma
  380. in a file name use two backslashes.  For example, use:
  381. >    :set tags=tag\\\ file,/home/user/common\\,tags
  382.  
  383. for the files "tag file" and "/home/user/common,tags".  The 'tags' option will
  384. have the value "tag\ file,/home/user/common\,tags".
  385.  
  386. If the 'tagrelative' option is on (which is the default) and using a tag file
  387. in another directory, file names in that tag file are relative to the
  388. directory where the tag file is.
  389.  
  390. ==============================================================================
  391. 5. Tags file format                    *tags-file-format*
  392.  
  393.                         *ctags* *jtags*
  394. A tags file can be created with the external command "ctags".  It will
  395. contain a tag for each function.  Some versions of "ctags" will also make a
  396. tag for each "#defined" macro, typedefs, enums, etc.  A very good one is
  397. exuberant ctags, which is included in the Vim distribution.  It works for C
  398. and C++.  For other languages other programs must be used to create the tags
  399. file.  For example, the "jtags" program can be used to create a tags file for
  400. Java <URL:http://www.fleiner.com/jtags/>
  401.  
  402. The lines in the tags file must have one of these three formats:
  403.  
  404. 1.  {tagname}        {TAB} {tagfile} {TAB} {tagaddress}
  405. 2.  {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress}
  406. 3.  {tagname}        {TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..
  407.  
  408. The first is a normal tag, which is completely compatible with Vi.  It is the
  409. only format produced by traditional ctags implementations.  This is often used
  410. for functions that are global, also referenced in other files.
  411.  
  412. The lines in the tags file can end in <LF> or <CR><LF>.  On the Macintosh <CR>
  413. probably also works (this depends on the fgets() function).  The <CR> and <NL>
  414. characters can never appear inside a line.
  415.  
  416.                             *tag-old-static*
  417. The second format is for a static tag only.  It is obsolete now, replaced by
  418. the third format.  It is only supported by Elvis 1.x and Vim and a few
  419. versions of ctags.  A static tag is often used for functions that are local,
  420. only referenced in the file {tagfile}.  Note that for the static tag, the two
  421. occurances of {tagfile} must be exactly the same.  Also see |tags-option|
  422. below, for how static tags are used.
  423.  
  424. The third format is new.  It includes additional information in optional
  425. fields at the end of each line.  It is backwards compatible with Vi.  It is
  426. only supported by new versions of ctags (like the one that comes with Vim).
  427.  
  428. {tagname}    The identifier.  Normally the name of a function, but it can
  429.         be any identifier.  It cannot contain a <Tab>.
  430. {TAB}        One <Tab> character.  Note: previous versions allowed any
  431.         white space here.  This has been abandoned to allow spaces in
  432.         {tagfile}.  It can be re-enabled by including the
  433.         |+tag_any_white| feature at compile time. *tag-any-white*
  434. {tagfile}    The file that contains the definition of {tagname}.  It can
  435.         have an absolute or relative path.  It may contain environment
  436.         variables and wildcards (although the use of wildcards is
  437.         doubtful).  It cannot contain a <Tab>.
  438. {tagaddress}    The Ex command that positions the cursor on the tag.  It can
  439.         be any Ex command, although restrictions apply (see
  440.         |tag-security|).  Posix only allows line numbers and search
  441.         commands, which are mostly used.
  442. {term}        ;" The two characters semicolon and double quote.  This is
  443.         interpreted by Vi as the start of a comment, which makes the
  444.         following be ignored.  This is only for backwards
  445.         compatibility with Vi.
  446. {field} ..    A list of optional fields.  Each field has the form:
  447.  
  448.             <Tab>{fieldname}:{value}
  449.  
  450.         The {fieldname} identifies the field, and can only contain
  451.         alphabetical characters [a-zA-Z].
  452.         The {value} is any string, but cannot contain a <Tab>.
  453.         These characters are special:
  454.             "\t" stands for a <Tab>
  455.             "\r" stands for a <CR>
  456.             "\n" stands for a <NL>
  457.             "\\" stands for a single '\' character
  458.  
  459.         There is one field that doesn't have a ':'.  This is the kind
  460.         of the tag.  It is handled like it was preceded with "kind:".
  461.         See the documentation of ctags for the kinds it produces.
  462.  
  463.         The only other field currently recognized by Vim is "file:"
  464.         (with an empty value).  It is used for a static tag.
  465.  
  466. The first lines in the tags file can contain lines that start with
  467.     !_TAG_
  468. These are sorted to the first lines, only rare tags that start with "!" can
  469. sort to before them.  Vim only recognizes the line that indicates if the file
  470. was sorted.  When this line is found, Vim uses binary searching for the tags
  471. file:
  472. >    !_TAG_FILE_SORTED<Tab>1
  473.  
  474.                             *tag-search*
  475. The command can be any Ex command, but often it is a search command.
  476. Examples:
  477. >    tag1    file1    /^main(argc, argv)/
  478. >    tag2    file2    108
  479.  
  480. The command is always executed with 'magic' not set.  The only special
  481. characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>).
  482. See |pattern|.  Note that you must put a backslash before each backslash in
  483. the search text.  This is for backwards compatibility with Vi.
  484.  
  485. If the command is a normal search command (it starts end ends with "/" or
  486. "?"), some special handling is done:
  487. - Searching starts on the current line of the current file, unless the tag is
  488.   in another file, in which case the search starts in line 1 of that file.
  489.   The direction of the search is forward for "/", backward for "?".
  490.   Note that when 'wrapscan' is not set, and the line with tag is not in the
  491.   search direction, it will not be found (this is Vi compatible).
  492.   {Vi starts searching in line 2 of another file.  It does not find a tag in
  493.   line 1 of another file when 'wrapscan' is not set}
  494. - If the search fails, another try is done ignoring case.  If that fails too,
  495.   a search is done for:
  496.     "^tagname[ \t]*("
  497.   (the tag with '^' prepended and "[ \t]*(" appended).  When using function
  498.   names, this will find the function name when it is in column 0.  This will
  499.   help when the arguments to the function have changed since the tags file was
  500.   made.  If this search also fails another search is done with:
  501.     "^[#a-zA-Z_].*tagname[ \t]*("
  502.   This means: A line starting with '#' or an identifier and containing the tag
  503.   followed by white space and a '('.  This will find macro names and function
  504.   names with a type prepended.  {the extra searches are not in Vi}.
  505.  
  506. ==============================================================================
  507. 6. Include file searches                *include-search*
  508.  
  509. These commands look for a string in the current file and in all encountered
  510. included files (recursively).  This can be used to find the definition of a
  511. variable, function or macro.  If you only want to search in the current
  512. buffer, use the commands listed at |pattern-searches|.
  513.  
  514. These commands are not available when the |+find_in_path| feature was disabled
  515. at compile time.
  516.  
  517. When a line is encountered that includes another file, that file is searched
  518. before continuing in the current buffer.  Files included by included files are
  519. also searched.  When an include file could not be found it is silently
  520. ignored.  Use the ":checkpath" command to discover which files could not be
  521. found, possibly your 'path' option is not set up correctly.  Note: the
  522. included file is searched, not a buffer that may be editing that file.  Only
  523. for the current file the lines in the buffer are used.
  524.  
  525. The string can be any keyword or a defined macro.  For the keyword any match
  526. will be found.  For defined macros only lines that match with the 'define'
  527. option will be found.  The default is "^#\s*define", which is for C programs.
  528. For other languages you probably want to change this.  See 'define' for an
  529. example for C++.
  530.  
  531. When a match is found for a defined macro, the displaying of lines continues
  532. with the next line when a line ends in a backslash.
  533.  
  534. The commands that start with "[" start searching from the start of the current
  535. file.  The commands that start with "]" start at the current cursor position.
  536.  
  537. The 'include' option is used to define a line that includes another file.  The
  538. default is "\^#\s*include", which is for C programs.  Note: Vim does not
  539. recognize C syntax, if the 'include' option matches a line inside
  540. "#ifdef/#endif" or inside a comment, it is searched anyway.  The 'isfname'
  541. option is used to recognize the file name that comes after the matched
  542. pattern.
  543.  
  544. The 'path' option is used to find the directory for the include files that
  545. do not have an absolute path.
  546.  
  547. The 'comments' option is used for the commands that display a single line or
  548. jump to a line.  It defines patterns that may start a comment.  Those lines
  549. are ignored for the search, unless [!] is used.  One exception: When the line
  550. matches the pattern "^# *define" it is not considered to be a comment.
  551.  
  552.                             *[i*
  553. [i            Display the first line that contains the keyword
  554.             under the cursor.  The search starts at the beginning
  555.             of the file.  Lines that look like a comment are
  556.             ignored (see 'comments' option).  If a count is given,
  557.             the count'th matching line is displayed, and comment
  558.             lines are not ignored.  {not in Vi}
  559.  
  560.                             *]i*
  561. ]i            like "[i", but start at the current cursor position.
  562.             {not in Vi}
  563.  
  564.                             *:is* *:isearch*
  565. :[range]is[earch][!] [count] [/]pattern[/]
  566.             Like "[i"  and "]i", but search in [range] lines
  567.             (default: whole file).
  568.             See |:search-args| for [/] and [!].  {not in Vi}
  569.  
  570.                             *[I*
  571. [I            Display all lines that contain the keyword under the
  572.             cursor.  Filenames and line numbers are displayed
  573.             for the found lines.  The search starts at the
  574.             beginning of the file.  {not in Vi}
  575.  
  576.                             *]I*
  577. ]I            like "[I", but start at the current cursor position.
  578.             {not in Vi}
  579.  
  580.                             *:il* *:ilist*
  581. :[range]il[ist][!] [/]pattern[/]
  582.             Like "[I" and "]I", but search in [range] lines
  583.             (default: whole file).
  584.             See |:search-args| for [/] and [!].  {not in Vi}
  585.  
  586.                             *[_CTRL-I*
  587. [ CTRL-I        Jump to the first line that contains the keyword
  588.             under the cursor.  The search starts at the beginning
  589.             of the file.  Lines that look like a comment are
  590.             ignored (see 'comments' option).  If a count is given,
  591.             the count'th matching line is jumped to, and comment
  592.             lines are not ignored.  {not in Vi}
  593.  
  594.                             *]_CTRL-I*
  595. ] CTRL-I        like "[ CTRL-I", but start at the current cursor
  596.             position.  {not in Vi}
  597.  
  598.                             *:ij* *:ijump*
  599. :[range]ij[ump][!] [count] [/]pattern[/]
  600.             Like "[ CTRL-I"  and "] CTRL-I", but search in
  601.             [range] lines (default: whole file).
  602.             See |:search-args| for [/] and [!].  {not in Vi}
  603.  
  604. CTRL-W CTRL-I                    *CTRL-W_CTRL-I* *CTRL-W_i*
  605. CTRL-W i        Open a new window, with the cursor on the first line
  606.             that contains the keyword under the cursor.  The
  607.             search starts at the beginning of the file.  Lines
  608.             that look like a comment line are ignored (see
  609.             'comments' option).  If a count is given, the count'th
  610.             matching line is jumped to, and comment lines are not
  611.             ignored.  {not in Vi}
  612.  
  613.                             *:isp* *:isplit*
  614. :[range]isp[lit][!] [count] [/]pattern[/]
  615.             Like "CTRL-W i"  and "CTRL-W i", but search in
  616.             [range] lines (default: whole file).
  617.             See |:search-args| for [/] and [!].  {not in Vi}
  618.  
  619.                             *[d*
  620. [d            Display the first macro definition that contains the
  621.             macro under the cursor.  The search starts from the
  622.             beginning of the file.  If a count is given, the
  623.             count'th matching line is displayed.  {not in Vi}
  624.  
  625.                             *]d*
  626. ]d            like "[d", but start at the current cursor position.
  627.             {not in Vi}
  628.  
  629.                             *:ds* *:dsearch*
  630. :[range]ds[earch][!] [count] [/]pattern[/]
  631.             Like "[d"  and "]d", but search in [range] lines
  632.             (default: whole file).
  633.             See |:search-args| for [/] and [!].  {not in Vi}
  634.  
  635.                             *[D*
  636. [D            Display all macro definitions that contain the macro
  637.             under the cursor.  Filenames and line numbers are
  638.             displayed for the found lines.  The search starts
  639.             from the beginning of the file.  {not in Vi}
  640.  
  641.                             *]D*
  642. ]D            like "[D", but start at the current cursor position.
  643.             {not in Vi}
  644.  
  645.                             *:dl* *:dlist*
  646. :[range]dl[ist][!] [/]pattern[/]
  647.             Like "[D"  and "]D", but search in [range] lines
  648.             (default: whole file).
  649.             See |:search-args| for [/] and [!].  {not in Vi}
  650.  
  651.                             *[_CTRL-D*
  652. [ CTRL-D        Jump to the first macro definition that contains the
  653.             keyword under the cursor.  The search starts from
  654.             the beginning of the file.  If a count is given, the
  655.             count'th matching line is jumped to.  {not in Vi}
  656.  
  657.                             *]_CTRL-D*
  658. ] CTRL-D        like "[ CTRL-D", but start at the current cursor
  659.             position.  {not in Vi}
  660.  
  661.                             *:dj* *:djump*
  662. :[range]dj[ump][!] [count] [/]pattern[/]
  663.             Like "[ CTRL-D"  and "] CTRL-D", but search  in
  664.             [range] lines (default: whole file).
  665.             See |:search-args| for [/] and [!].  {not in Vi}
  666.  
  667. CTRL-W CTRL-D                    *CTRL-W_CTRL-D* *CTRL-W_d*
  668. CTRL-W d        Open a new window, with the cursor on the first
  669.             macro definition line that contains the keyword
  670.             under the cursor.  The search starts from the
  671.             beginning of the file.  If a count is given, the
  672.             count'th matching line is jumped to.  {not in Vi}
  673.  
  674.                             *:dsp* *:dsplit*
  675. :[range]dsp[lit][!] [count] [/]pattern[/]
  676.             Like "CTRL-W d", but search in [range] lines
  677.             (default: whole file).
  678.             See |:search-args| for [/] and [!].  {not in Vi}
  679.  
  680.                             *:che* *:checkpath*
  681. :che[ckpath]        List all the included files that could not be found.
  682.             {not in Vi}
  683.  
  684. :che[ckpath]!        List all the included files.  {not in Vi}
  685.  
  686.                                 *:search-args*
  687. Common arguments for the commands above:
  688. [!]   When included, lines that are recognized as comments are skipped.
  689. [/]   A pattern can be surrounded by '/'.  Without '/' only whole words are
  690.       matched, using the pattern "\<pattern\>".  Only after the second '/' a
  691.       next command can be appended with '|'.  Examples:
  692. >   :isearch /string/ | echo "the last one"
  693.  
  694. ==============================================================================
  695. 7. 'Grep' and 'Lid'                    *grep* *lid*
  696.  
  697. Vim can interface with "grep" and grep-like programs (such as the GNU
  698. id-utils) in a similar way to its compiler integration. (see |:make| for more
  699. information on that.)
  700.  
  701. 7.1 Setting up grep
  702. If you have a standard "grep" program installed, the :grep command may well
  703. work first time with the defaults. The syntax is very similar to the standard
  704. command:
  705.  
  706. >    :grep foo *.c
  707.  
  708. Will search all files with the .c extension for the substring "foo". The
  709. arguments to :grep are passed straight to the "grep" program, so you can use
  710. whatever options your "grep" supports.
  711.  
  712. By default, :grep invokes grep with the -n option (show file and line
  713. numbers). You can change this with the 'grepprg' option. You will need to set
  714. 'grepprg' if:
  715.  
  716. a)    You are using a program that isn't called "grep"
  717. b)    You have to call grep with a full path
  718. c)    You want to pass other options automatically (e.g. case insensitive
  719.     search.)
  720.  
  721. Once "grep" has executed, Vim parses the results using the 'grepformat'
  722. option. This option works in the same way as the 'errorformat' option - see
  723. that for details. You may need to change 'grepformat' from the default if your
  724. grep outputs in a non-standard format, or you are using some other program
  725. with a special format.
  726.  
  727. Once the results are parsed, Vim loads the first file containing a match and
  728. jumps to the appropriate line, in the same way that it jumps to a compiler
  729. error in |quickfix| mode. You can then use the |:cnext|, |:clist|, etc.
  730. commands to see the other matches.
  731.  
  732. 7.2 Using :grep with id-utils
  733. You can set up :grep to work with the GNU id-utils like this:
  734.  
  735. >    set grepprg=lid\ -Rgrep\ -s
  736. >    set grepformat=%f:%l:%m
  737.  
  738. then
  739. >    :grep (regexp)
  740.  
  741. works just as you'd expect.
  742. (provided you remembered to mkid first :)
  743.  
  744.  vim:tw=78:ts=8:sw=8:
  745.