share/vim/vim72/doc/usr_29.txt

   1 *usr_29.txt*    For Vim version 7.2.  Last change: 2008 Jun 28
   2
   3                      VIM USER MANUAL - by Bram Moolenaar
   4
   5                             Moving through programs
   6
   7
   8 The creator of Vim is a computer programmer.  It's no surprise that Vim
   9 contains many features to aid in writing programs.  Jump around to find where
  10 identifiers are defined and used.  Preview declarations in a separate window.
  11 There is more in the next chapter.
  12
  13 |29.1|  Using tags
  14 |29.2|  The preview window
  15 |29.3|  Moving through a program
  16 |29.4|  Finding global identifiers
  17 |29.5|  Finding local identifiers
  18
  19      Next chapter: |usr_30.txt|  Editing programs
  20  Previous chapter: |usr_28.txt|  Folding
  21 Table of contents: |usr_toc.txt|
  22
  23 ==============================================================================
  24 *29.1*  Using tags
  25
  26 What is a tag?  It is a location where an identifier is defined.  An example
  27 is a function definition in a C or C++ program.  A list of tags is kept in a
  28 tags file.  This can be used by Vim to directly jump from any place to the
  29 tag, the place where an identifier is defined.
  30    To generate the tags file for all C files in the current directory, use the
  31 following command: >
  32
  33         ctags *.c
  34
  35 "ctags" is a separate program.  Most Unix systems already have it installed.
  36 If you do not have it yet, you can find Exuberant ctags here:
  37
  38         http://ctags.sf.net ~
  39
  40 Now when you are in Vim and you want to go to a function definition, you can
  41 jump to it by using the following command: >
  42
  43         :tag startlist
  44
  45 This command will find the function "startlist" even if it is in another file.
  46    The CTRL-] command jumps to the tag of the word that is under the cursor.
  47 This makes it easy to explore a tangle of C code.  Suppose, for example, that
  48 you are in the function "write_block".  You can see that it calls
  49 "write_line".  But what does "write_line" do?  By placing the cursor on the
  50 call to "write_line" and pressing CTRL-], you jump to the definition of this
  51 function.
  52    The "write_line" function calls "write_char".  You need to figure out what
  53 it does.  So you position the cursor over the call to "write_char" and press
  54 CTRL-].  Now you are at the definition of "write_char".
  55
  56         +-------------------------------------+
  57         |void write_block(char **s; int cnt)  |
  58         |{                                    |
  59         |   int i;                            |
  60         |   for (i = 0; i < cnt; ++i)         |
  61         |      write_line(s[i]);              |
  62         |}          |                         |
  63         +-----------|-------------------------+
  64                     |
  65              CTRL-] |
  66                     |    +----------------------------+
  67                     +--> |void write_line(char *s)    |
  68                          |{                           |
  69                          |   while (*s != 0)          |
  70                          |      write_char(*s++);     |
  71                          |}       |                   |
  72                          +--------|-------------------+
  73                                   |
  74                            CTRL-] |
  75                                   |    +------------------------------------+
  76                                   +--> |void write_char(char c)             |
  77                                        |{                                   |
  78                                        |    putchar((int)(unsigned char)c); |
  79                                        |}                                   |
  80                                        +------------------------------------+
  81
  82 The ":tags" command shows the list of tags that you traversed through:
  83
  84         :tags
  85           # TO tag         FROM line  in file/text ~
  86           1  1 write_line          8  write_block.c ~
  87           2  1 write_char          7  write_line.c ~
  88         > ~
  89 >
  90 Now to go back.  The CTRL-T command goes to the preceding tag.  In the example
  91 above you get back to the "write_line" function, in the call to "write_char".
  92    This command takes a count argument that indicates how many tags to jump
  93 back.  You have gone forward, and now back.  Let's go forward again.  The
  94 following command goes to the tag on top of the list: >
  95
  96         :tag
  97
  98 You can prefix it with a count and jump forward that many tags.  For example:
  99 ":3tag".  CTRL-T also can be preceded with a count.
 100    These commands thus allow you to go down a call tree with CTRL-] and back
 101 up again with CTRL-T.  Use ":tags" to find out where you are.
 102
 103
 104 SPLIT WINDOWS
 105
 106 The ":tag" command replaces the file in the current window with the one
 107 containing the new function.  But suppose you want to see not only the old
 108 function but also the new one?  You can split the window using the ":split"
 109 command followed by the ":tag" command.  Vim has a shorthand command that does
 110 both: >
 111         :stag tagname
 112
 113 To split the current window and jump to the tag under the cursor use this
 114 command: >
 115
 116         CTRL-W ]
 117
 118 If a count is specified, the new window will be that many lines high.
 119
 120
 121 MORE TAGS FILES
 122
 123 When you have files in many directories, you can create a tags file in each of
 124 them.  Vim will then only be able to jump to tags within that directory.
 125    To find more tags files, set the 'tags' option to include all the relevant
 126 tags files.  Example: >
 127
 128         :set tags=./tags,./../tags,./*/tags
 129
 130 This finds a tags file in the same directory as the current file, one
 131 directory level higher and in all subdirectories.
 132    This is quite a number of tags files, but it may still not be enough.  For
 133 example, when editing a file in "~/proj/src", you will not find the tags file
 134 "~/proj/sub/tags".  For this situation Vim offers to search a whole directory
 135 tree for tags files.  Example: >
 136
 137         :set tags=~/proj/**/tags
 138
 139
 140 ONE TAGS FILE
 141
 142 When Vim has to search many places for tags files, you can hear the disk
 143 rattling.  It may get a bit slow.  In that case it's better to spend this
 144 time while generating one big tags file.  You might do this overnight.
 145    This requires the Exuberant ctags program, mentioned above.  It offers an
 146 argument to search a whole directory tree: >
 147
 148         cd ~/proj
 149         ctags -R .
 150
 151 The nice thing about this is that Exuberant ctags recognizes various file
 152 types.  Thus this doesn't work just for C and C++ programs, also for Eiffel
 153 and even Vim scripts.  See the ctags documentation to tune this.
 154    Now you only need to tell Vim where your big tags file is: >
 155
 156         :set tags=~/proj/tags
 157
 158
 159 MULTIPLE MATCHES
 160
 161 When a function is defined multiple times (or a method in several classes),
 162 the ":tag" command will jump to the first one.  If there is a match in the
 163 current file, that one is used first.
 164    You can now jump to other matches for the same tag with: >
 165
 166         :tnext
 167
 168 Repeat this to find further matches.  If there are many, you can select which
 169 one to jump to: >
 170
 171         :tselect tagname
 172
 173 Vim will present you with a list of choices:
 174
 175           # pri kind tag               file ~
 176           1 F   f    mch_init          os_amiga.c ~
 177                        mch_init() ~
 178           2 F   f    mch_init          os_mac.c ~
 179                        mch_init() ~
 180           3 F   f    mch_init          os_msdos.c ~
 181                        mch_init(void) ~
 182           4 F   f    mch_init          os_riscos.c ~
 183                        mch_init() ~
 184         Enter nr of choice (<CR> to abort):  ~
 185
 186 You can now enter the number (in the first column) of the match that you would
 187 like to jump to.  The information in the other columns give you a good idea of
 188 where the match is defined.
 189
 190 To move between the matching tags, these commands can be used:
 191
 192         :tfirst                 go to first match
 193         :[count]tprevious       go to [count] previous match
 194         :[count]tnext           go to [count] next match
 195         :tlast                  go to last match
 196
 197 If [count] is omitted then one is used.
 198
 199
 200 GUESSING TAG NAMES
 201
 202 Command line completion is a good way to avoid typing a long tag name.  Just
 203 type the first bit and press <Tab>: >
 204
 205         :tag write_<Tab>
 206
 207 You will get the first match.  If it's not the one you want, press <Tab> until
 208 you find the right one.
 209    Sometimes you only know part of the name of a function.  Or you have many
 210 tags that start with the same string, but end differently.  Then you can tell
 211 Vim to use a pattern to find the tag.
 212    Suppose you want to jump to a tag that contains "block".  First type
 213 this: >
 214
 215         :tag /block
 216
 217 Now use command line completion: press <Tab>.  Vim will find all tags that
 218 contain "block" and use the first match.
 219    The "/" before a tag name tells Vim that what follows is not a literal tag
 220 name, but a pattern.  You can use all the items for search patterns here.  For
 221 example, suppose you want to select a tag that starts with "write_": >
 222
 223         :tselect /^write_
 224
 225 The "^" specifies that the tag starts with "write_".  Otherwise it would also
 226 be found halfway a tag name.  Similarly "$" at the end makes sure the pattern
 227 matches until the end of a tag.
 228
 229
 230 A TAGS BROWSER
 231
 232 Since CTRL-] takes you to the definition of the identifier under the cursor,
 233 you can use a list of identifier names as a table of contents.  Here is an
 234 example.
 235    First create a list of identifiers (this requires Exuberant ctags): >
 236
 237         ctags --c-types=f -f functions *.c
 238
 239 Now start Vim without a file, and edit this file in Vim, in a vertically split
 240 window: >
 241
 242         vim
 243         :vsplit functions
 244
 245 The window contains a list of all the functions.  There is some more stuff,
 246 but you can ignore that.  Do ":setlocal ts=99" to clean it up a bit.
 247    In this window, define a mapping: >
 248
 249         :nnoremap <buffer> <CR> 0ye<C-W>w:tag <C-R>"<CR>
 250
 251 Move the cursor to the line that contains the function you want to go to.
 252 Now press <Enter>.  Vim will go to the other window and jump to the selected
 253 function.
 254
 255
 256 RELATED ITEMS
 257
 258 You can set 'ignorecase' to make case in tag names be ignored.
 259
 260 The 'tagbsearch' option tells if the tags file is sorted or not.  The default
 261 is to assume a sorted tags file, which makes a tags search a lot faster, but
 262 doesn't work if the tags file isn't sorted.
 263
 264 The 'taglength' option can be used to tell Vim the number of significant
 265 characters in a tag.
 266
 267 When you use the SNiFF+ program, you can use the Vim interface to it |sniff|.
 268 SNiFF+ is a commercial program.
 269
 270 Cscope is a free program.  It does not only find places where an identifier is
 271 declared, but also where it is used.  See |cscope|.
 272
 273 ==============================================================================
 274 *29.2*  The preview window
 275
 276 When you edit code that contains a function call, you need to use the correct
 277 arguments.  To know what values to pass you can look at how the function is
 278 defined.  The tags mechanism works very well for this.  Preferably the
 279 definition is displayed in another window.  For this the preview window can be
 280 used.
 281    To open a preview window to display the function "write_char": >
 282
 283         :ptag write_char
 284
 285 Vim will open a window, and jumps to the tag "write_char".  Then it takes you
 286 back to the original position.  Thus you can continue typing without the need
 287 to use a CTRL-W command.
 288    If the name of a function appears in the text, you can get its definition
 289 in the preview window with: >
 290
 291         CTRL-W }
 292
 293 There is a script that automatically displays the text where the word under
 294 the cursor was defined.  See |CursorHold-example|.
 295
 296 To close the preview window use this command: >
 297
 298         :pclose
 299
 300 To edit a specific file in the preview window, use ":pedit".  This can be
 301 useful to edit a header file, for example: >
 302
 303         :pedit defs.h
 304
 305 Finally, ":psearch" can be used to find a word in the current file and any
 306 included files and display the match in the preview window.  This is
 307 especially useful when using library functions, for which you do not have a
 308 tags file.  Example: >
 309
 310         :psearch popen
 311
 312 This will show the "stdio.h" file in the preview window, with the function
 313 prototype for popen():
 314
 315         FILE    *popen __P((const char *, const char *)); ~
 316
 317 You can specify the height of the preview window, when it is opened, with the
 318 'previewheight' option.
 319
 320 ==============================================================================
 321 *29.3*  Moving through a program
 322
 323 Since a program is structured, Vim can recognize items in it.  Specific
 324 commands can be used to move around.
 325    C programs often contain constructs like this:
 326
 327         #ifdef USE_POPEN ~
 328             fd = popen("ls", "r") ~
 329         #else ~
 330             fd = fopen("tmp", "w") ~
 331         #endif ~
 332
 333 But then much longer, and possibly nested.  Position the cursor on the
 334 "#ifdef" and press %.  Vim will jump to the "#else".  Pressing % again takes
 335 you to the "#endif".  Another % takes you to the "#ifdef" again.
 336    When the construct is nested, Vim will find the matching items.  This is a
 337 good way to check if you didn't forget an "#endif".
 338    When you are somewhere inside a "#if" - "#endif", you can jump to the start
 339 of it with: >
 340
 341         [#
 342
 343 If you are not after a "#if" or "#ifdef" Vim will beep.  To jump forward to
 344 the next "#else" or "#endif" use: >
 345
 346         ]#
 347
 348 These two commands skip any "#if" - "#endif" blocks that they encounter.
 349 Example:
 350
 351         #if defined(HAS_INC_H) ~
 352             a = a + inc(); ~
 353         # ifdef USE_THEME ~
 354             a += 3; ~
 355         # endif ~
 356             set_width(a); ~
 357
 358 With the cursor in the last line, "[#" moves to the first line.  The "#ifdef"
 359 - "#endif" block in the middle is skipped.
 360
 361
 362 MOVING IN CODE BLOCKS
 363
 364 In C code blocks are enclosed in {}.  These can get pretty long.  To move to
 365 the start of the outer block use the "[[" command.  Use "][" to find the end.
 366 This assumes that the "{" and "}" are in the first column.
 367    The "[{" command moves to the start of the current block.  It skips over
 368 pairs of {} at the same level.  "]}" jumps to the end.
 369    An overview:
 370
 371                         function(int a)
 372            +->          {
 373            |                if (a)
 374            |       +->      {
 375         [[ |       |            for (;;)               --+
 376            |       |      +->   {                        |
 377            |    [{ |      |         foo(32);             |     --+
 378            |       |   [{ |         if (bar(a))  --+     | ]}    |
 379            +--     |      +--           break;     | ]}  |       |
 380                    |            }                <-+     |       | ][
 381                    +--          foobar(a)                |       |
 382                             }                          <-+       |
 383                         }                                      <-+
 384
 385 When writing C++ or Java, the outer {} block is for the class.  The next level
 386 of {} is for a method.  When somewhere inside a class use "[m" to find the
 387 previous start of a method.  "]m" finds the next start of a method.
 388
 389 Additionally, "[]" moves backward to the end of a function and "]]" moves
 390 forward to the start of the next function.  The end of a function is defined
 391 by a "}" in the first column.
 392
 393                                 int func1(void)
 394                                 {
 395                                         return 1;
 396                   +---------->  }
 397                   |
 398               []  |             int func2(void)
 399                   |        +->  {
 400                   |    [[  |            if (flag)
 401         start     +--      +--                  return flag;
 402                   |    ][  |            return 2;
 403                   |        +->  }
 404               ]]  |
 405                   |             int func3(void)
 406                   +---------->  {
 407                                         return 3;
 408                                 }
 409
 410 Don't forget you can also use "%" to move between matching (), {} and [].
 411 That also works when they are many lines apart.
 412
 413
 414 MOVING IN BRACES
 415
 416 The "[(" and "])" commands work similar to "[{" and "]}", except that they
 417 work on () pairs instead of {} pairs.
 418 >
 419                                   [(
 420 <                   <--------------------------------
 421                               <-------
 422                 if (a == b && (c == d || (e > f)) && x > y) ~
 423                                   -------------->
 424                           --------------------------------> >
 425                                        ])
 426
 427 MOVING IN COMMENTS
 428
 429 To move back to the start of a comment use "[/".  Move forward to the end of a
 430 comment with "]/".  This only works for /* - */ comments.
 431
 432           +->     +-> /*
 433           |    [/ |    * A comment about      --+
 434        [/ |       +--  * wonderful life.        | ]/
 435           |            */                     <-+
 436           |
 437           +--          foo = bar * 3;         --+
 438                                                 | ]/
 439                        /* a short comment */  <-+
 440
 441 ==============================================================================
 442 *29.4*  Finding global identifiers
 443
 444 You are editing a C program and wonder if a variable is declared as "int" or
 445 "unsigned".  A quick way to find this is with the "[I" command.
 446    Suppose the cursor is on the word "column".  Type: >
 447
 448         [I
 449
 450 Vim will list the matching lines it can find.  Not only in the current file,
 451 but also in all included files (and files included in them, etc.).  The result
 452 looks like this:
 453
 454         structs.h ~
 455          1:   29     unsigned     column;    /* column number */ ~
 456
 457 The advantage over using tags or the preview window is that included files are
 458 searched.  In most cases this results in the right declaration to be found.
 459 Also when the tags file is out of date.  Also when you don't have tags for the
 460 included files.
 461    However, a few things must be right for "[I" to do its work.  First of all,
 462 the 'include' option must specify how a file is included.  The default value
 463 works for C and C++.  For other languages you will have to change it.
 464
 465
 466 LOCATING INCLUDED FILES
 467
 468    Vim will find included files in the places specified with the 'path'
 469 option.  If a directory is missing, some include files will not be found.  You
 470 can discover this with this command: >
 471
 472         :checkpath
 473
 474 It will list the include files that could not be found.  Also files included
 475 by the files that could be found.  An example of the output:
 476
 477         --- Included files not found in path --- ~
 478         <io.h> ~
 479         vim.h --> ~
 480           <functions.h> ~
 481           <clib/exec_protos.h> ~
 482
 483 The "io.h" file is included by the current file and can't be found.  "vim.h"
 484 can be found, thus ":checkpath" goes into this file and checks what it
 485 includes.  The "functions.h" and "clib/exec_protos.h" files, included by
 486 "vim.h" are not found.
 487
 488         Note:
 489         Vim is not a compiler.  It does not recognize "#ifdef" statements.
 490         This means every "#include" statement is used, also when it comes
 491         after "#if NEVER".
 492
 493 To fix the files that could not be found, add a directory to the 'path'
 494 option.  A good place to find out about this is the Makefile.  Look out for
 495 lines that contain "-I" items, like "-I/usr/local/X11".  To add this directory
 496 use: >
 497
 498         :set path+=/usr/local/X11
 499
 500 When there are many subdirectories, you can use the "*" wildcard.  Example: >
 501
 502         :set path+=/usr/*/include
 503
 504 This would find files in "/usr/local/include" as well as "/usr/X11/include".
 505
 506 When working on a project with a whole nested tree of included files, the "**"
 507 items is useful.  This will search down in all subdirectories.  Example: >
 508
 509         :set path+=/projects/invent/**/include
 510
 511 This will find files in the directories:
 512
 513         /projects/invent/include ~
 514         /projects/invent/main/include ~
 515         /projects/invent/main/os/include ~
 516         etc.
 517
 518 There are even more possibilities.  Check out the 'path' option for info.
 519    If you want to see which included files are actually found, use this
 520 command: >
 521
 522         :checkpath!
 523
 524 You will get a (very long) list of included files, the files they include, and
 525 so on.  To shorten the list a bit, Vim shows "(Already listed)" for files that
 526 were found before and doesn't list the included files in there again.
 527
 528
 529 JUMPING TO A MATCH
 530
 531 "[I" produces a list with only one line of text.  When you want to have a
 532 closer look at the first item, you can jump to that line with the command: >
 533
 534         [<Tab>
 535
 536 You can also use "[ CTRL-I", since CTRL-I is the same as pressing <Tab>.
 537
 538 The list that "[I" produces has a number at the start of each line.  When you
 539 want to jump to another item than the first one, type the number first: >
 540
 541         3[<Tab>
 542
 543 Will jump to the third item in the list.  Remember that you can use CTRL-O to
 544 jump back to where you started from.
 545
 546
 547 RELATED COMMANDS
 548
 549         [i              only lists the first match
 550         ]I              only lists items below the cursor
 551         ]i              only lists the first item below the cursor
 552
 553
 554 FINDING DEFINED IDENTIFIERS
 555
 556 The "[I" command finds any identifier.  To find only macros, defined with
 557 "#define" use: >
 558
 559         [D
 560
 561 Again, this searches in included files.  The 'define' option specifies what a
 562 line looks like that defines the items for "[D".  You could change it to make
 563 it work with other languages than C or C++.
 564    The commands related to "[D" are:
 565
 566         [d              only lists the first match
 567         ]D              only lists items below the cursor
 568         ]d              only lists the first item below the cursor
 569
 570 ==============================================================================
 571 *29.5*  Finding local identifiers
 572
 573 The "[I" command searches included files.  To search in the current file only,
 574 and jump to the first place where the word under the cursor is used: >
 575
 576         gD
 577
 578 Hint: Goto Definition.  This command is very useful to find a variable or
 579 function that was declared locally ("static", in C terms).  Example (cursor on
 580 "counter"):
 581
 582            +->   static int counter = 0;
 583            |
 584            |     int get_counter(void)
 585         gD |     {
 586            |         ++counter;
 587            +--       return counter;
 588                  }
 589
 590 To restrict the search even further, and look only in the current function,
 591 use this command: >
 592
 593         gd
 594
 595 This will go back to the start of the current function and find the first
 596 occurrence of the word under the cursor.  Actually, it searches backwards to
 597 an empty line above a "{" in the first column.  From there it searches forward
 598 for the identifier.  Example (cursor on "idx"):
 599
 600                 int find_entry(char *name)
 601                 {
 602            +->      int idx;
 603            |
 604         gd |        for (idx = 0; idx < table_len; ++idx)
 605            |            if (strcmp(table[idx].name, name) == 0)
 606            +--              return idx;
 607                 }
 608
 609 ==============================================================================
 610
 611 Next chapter: |usr_30.txt|  Editing programs
 612
 613 Copyright: see |manual-copyright|  vim:tw=78:ts=8:ft=help:norl: