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