summaryrefslogtreecommitdiffstats
path: root/runtime/doc/usr_29.txt
blob: a534c6f1cd620829dc1ca90298416f03e0e2db70 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
*usr_29.txt*	For Vim version 9.1.  Last change: 2022 Mar 13

		     VIM USER MANUAL - by Bram Moolenaar

			    Moving through programs


The creator of Vim is a computer programmer.  It's no surprise that Vim
contains many features to aid in writing programs.  Jump around to find where
identifiers are defined and used.  Preview declarations in a separate window.
There is more in the next chapter.

|29.1|	Using tags
|29.2|	The preview window
|29.3|	Moving through a program
|29.4|	Finding global identifiers
|29.5|	Finding local identifiers

     Next chapter: |usr_30.txt|  Editing programs
 Previous chapter: |usr_28.txt|  Folding
Table of contents: |usr_toc.txt|

==============================================================================
*29.1*	Using tags

What is a tag?  It is a location where an identifier is defined.  An example
is a function definition in a C or C++ program.  A list of tags is kept in a
tags file.  This can be used by Vim to directly jump from any place to the
tag, the place where an identifier is defined.
   To generate the tags file for all C files in the current directory, use the
following command: >

	ctags *.c

"ctags" is a separate program.  Most Unix systems already have it installed.
If you do not have it yet, you can find Universal/Exuberant ctags at:
	http://ctags.io ~
	http://ctags.sf.net ~

Universal ctags is preferred, Exuberant ctags is no longer being developed.

Now when you are in Vim and you want to go to a function definition, you can
jump to it by using the following command: >

	:tag startlist

This command will find the function "startlist" even if it is in another file.
   The CTRL-] command jumps to the tag of the word that is under the cursor.
This makes it easy to explore a tangle of C code.  Suppose, for example, that
you are in the function "write_block".  You can see that it calls
"write_line".  But what does "write_line" do?  By placing the cursor on the
call to "write_line" and pressing CTRL-], you jump to the definition of this
function.
   The "write_line" function calls "write_char".  You need to figure out what
it does.  So you position the cursor over the call to "write_char" and press
CTRL-].  Now you are at the definition of "write_char".

	+-------------------------------------+
	|void write_block(char **s; int cnt)  |
	|{				      |
	|   int i;			      |
	|   for (i = 0; i < cnt; ++i)	      |
	|      write_line(s[i]);	      |
	|}	    |			      |
	+-----------|-------------------------+
		    |
	     CTRL-] |
		    |	 +----------------------------+
		    +--> |void write_line(char *s)    |
			 |{			      |
			 |   while (*s != 0)	      |
			 |	write_char(*s++);     |
			 |}	  |		      |
			 +--------|-------------------+
				  |
			   CTRL-] |
				  |    +------------------------------------+
				  +--> |void write_char(char c)		    |
				       |{				    |
				       |    putchar((int)(unsigned char)c); |
				       |}				    |
				       +------------------------------------+

The ":tags" command shows the list of tags that you traversed through:

	:tags
	  # TO tag	   FROM line  in file/text ~
	  1  1 write_line	   8  write_block.c ~
	  2  1 write_char	   7  write_line.c ~
	> ~
>
Now to go back.  The CTRL-T command goes to the preceding tag.  In the example
above you get back to the "write_line" function, in the call to "write_char".
   This command takes a count argument that indicates how many tags to jump
back.  You have gone forward, and now back.  Let's go forward again.  The
following command goes to the tag on top of the list: >

	:tag

You can prefix it with a count and jump forward that many tags.  For example:
":3tag".  CTRL-T also can be preceded with a count.
   These commands thus allow you to go down a call tree with CTRL-] and back
up again with CTRL-T.  Use ":tags" to find out where you are.


SPLIT WINDOWS

The ":tag" command replaces the file in the current window with the one
containing the new function.  But suppose you want to see not only the old
function but also the new one?  You can split the window using the ":split"
command followed by the ":tag" command.  Vim has a shorthand command that does
both: >
	:stag tagname

To split the current window and jump to the tag under the cursor use this
command: >

	CTRL-W ]

If a count is specified, the new window will be that many lines high.


MORE TAGS FILES

When you have files in many directories, you can create a tags file in each of
them.  Vim will then only be able to jump to tags within that directory.
   To find more tags files, set the 'tags' option to include all the relevant
tags files.  Example: >

	:set tags=./tags,./../tags,./*/tags

This finds a tags file in the same directory as the current file, one
directory level higher and in all subdirectories.
   This is quite a number of tags files, but it may still not be enough.  For
example, when editing a file in "~/proj/src", you will not find the tags file
"~/proj/sub/tags".  For this situation Vim offers to search a whole directory
tree for tags files.  Example: >

	:set tags=~/proj/**/tags


ONE TAGS FILE

When Vim has to search many places for tags files, you can hear the disk
rattling.  It may get a bit slow.  In that case it's better to spend this
time while generating one big tags file.  You might do this overnight.
   This requires the Universal or Exuberant ctags program, mentioned above.
It offers an argument to search a whole directory tree: >

	cd ~/proj
	ctags -R .

The nice thing about this is that Universal/Exuberant ctags recognizes various
file types.  Thus this doesn't work just for C and C++ programs, also for
Eiffel and even Vim scripts.  See the ctags documentation to tune this.
   Now you only need to tell Vim where your big tags file is: >

	:set tags=~/proj/tags


MULTIPLE MATCHES

When a function is defined multiple times (or a method in several classes),
the ":tag" command will jump to the first one.  If there is a match in the
current file, that one is used first.
   You can now jump to other matches for the same tag with: >

	:tnext

Repeat this to find further matches.  If there are many, you can select which
one to jump to: >

	:tselect tagname

Vim will present you with a list of choices:

	  # pri kind tag	       file ~
	  1 F	f    mch_init	       os_amiga.c ~
		       mch_init() ~
	  2 F	f    mch_init	       os_mac.c ~
		       mch_init() ~
	  3 F	f    mch_init	       os_msdos.c ~
		       mch_init(void) ~
	  4 F	f    mch_init	       os_riscos.c ~
		       mch_init() ~
	Enter nr of choice (<CR> to abort):  ~

You can now enter the number (in the first column) of the match that you would
like to jump to.  The information in the other columns give you a good idea of
where the match is defined.

To move between the matching tags, these commands can be used:

	:tfirst			go to first match
	:[count]tprevious	go to [count] previous match
	:[count]tnext		go to [count] next match
	:tlast			go to last match

If [count] is omitted then one is used.


GUESSING TAG NAMES

Command line completion is a good way to avoid typing a long tag name.  Just
type the first bit and press <Tab>: >

	:tag write_<Tab>

You will get the first match.  If it's not the one you want, press <Tab> until
you find the right one.
   Sometimes you only know part of the name of a function.  Or you have many
tags that start with the same string, but end differently.  Then you can tell
Vim to use a pattern to find the tag.
   Suppose you want to jump to a tag that contains "block".  First type
this: >

	:tag /block

Now use command line completion: press <Tab>.  Vim will find all tags that
contain "block" and use the first match.
   The "/" before a tag name tells Vim that what follows is not a literal tag
name, but a pattern.  You can use all the items for search patterns here.  For
example, suppose you want to select a tag that starts with "write_": >

	:tselect /^write_

The "^" specifies that the tag starts with "write_".  Otherwise it would also
be found halfway a tag name.  Similarly "$" at the end makes sure the pattern
matches until the end of a tag.


A TAGS BROWSER

Since CTRL-] takes you to the definition of the identifier under the cursor,
you can use a list of identifier names as a table of contents.  Here is an
example.
   First create a list of identifiers (this requires Universal or Exuberant
ctags): >

	ctags --c-types=f -f functions *.c

Now start Vim without a file, and edit this file in Vim, in a vertically split
window: >

	vim
	:vsplit functions

The window contains a list of all the functions.  There is some more stuff,
but you can ignore that.  Do ":setlocal ts=99" to clean it up a bit.
   In this window, define a mapping: >

	:nnoremap <buffer> <CR> 0ye<C-W>w:tag <C-R>"<CR>

Move the cursor to the line that contains the function you want to go to.
Now press <Enter>.  Vim will go to the other window and jump to the selected
function.


RELATED ITEMS

To make case in tag names be ignored, you can set 'ignorecase' while leaving
'tagcase' as "followic", or set 'tagcase' to "ignore".

The 'tagbsearch' option tells if the tags file is sorted or not.  The default
is to assume a sorted tags file, which makes a tags search a lot faster, but
doesn't work if the tags file isn't sorted.

The 'taglength' option can be used to tell Vim the number of significant
characters in a tag.

Cscope is a free program.  It does not only find places where an identifier is
declared, but also where it is used.  See |cscope|.

==============================================================================
*29.2*	The preview window

When you edit code that contains a function call, you need to use the correct
arguments.  To know what values to pass you can look at how the function is
defined.  The tags mechanism works very well for this.  Preferably the
definition is displayed in another window.  For this the preview window can be
used.
   To open a preview window to display the function "write_char": >

	:ptag write_char

Vim will open a window, and jumps to the tag "write_char".  Then it takes you
back to the original position.  Thus you can continue typing without the need
to use a CTRL-W command.
   If the name of a function appears in the text, you can get its definition
in the preview window with: >

	CTRL-W }

There is a script that automatically displays the text where the word under
the cursor was defined.  See |CursorHold-example|.

To close the preview window use this command: >

	:pclose

To edit a specific file in the preview window, use ":pedit".  This can be
useful to edit a header file, for example: >

	:pedit defs.h

Finally, ":psearch" can be used to find a word in the current file and any
included files and display the match in the preview window.  This is
especially useful when using library functions, for which you do not have a
tags file.  Example: >

	:psearch popen

This will show the "stdio.h" file in the preview window, with the function
prototype for popen():

	FILE	*popen __P((const char *, const char *)); ~

You can specify the height of the preview window, when it is opened, with the
'previewheight' option.

==============================================================================
*29.3*	Moving through a program

Since a program is structured, Vim can recognize items in it.  Specific
commands can be used to move around.
   C programs often contain constructs like this:

	#ifdef USE_POPEN ~
	    fd = popen("ls", "r") ~
	#else ~
	    fd = fopen("tmp", "w") ~
	#endif ~

But then much longer, and possibly nested.  Position the cursor on the
"#ifdef" and press %.  Vim will jump to the "#else".  Pressing % again takes
you to the "#endif".  Another % takes you to the "#ifdef" again.
   When the construct is nested, Vim will find the matching items.  This is a
good way to check if you didn't forget an "#endif".
   When you are somewhere inside a "#if" - "#endif", you can jump to the start
of it with: >

	[#

If you are not after a "#if" or "#ifdef" Vim will beep.  To jump forward to
the next "#else" or "#endif" use: >

	]#

These two commands skip any "#if" - "#endif" blocks that they encounter.
Example:

	#if defined(HAS_INC_H) ~
	    a = a + inc(); ~
	# ifdef USE_THEME ~
	    a += 3; ~
	# endif ~
	    set_width(a); ~

With the cursor in the last line, "[#" moves to the first line.  The "#ifdef"
- "#endif" block in the middle is skipped.


MOVING IN CODE BLOCKS

In C code blocks are enclosed in {}.  These can get pretty long.  To move to
the start of the outer block use the "[[" command.  Use "][" to find the end.
This assumes that the "{" and "}" are in the first column.
   The "[{" command moves to the start of the current block.  It skips over
pairs of {} at the same level.  "]}" jumps to the end.
   An overview:

			function(int a)
	   +->		{
	   |		    if (a)
	   |	   +->	    {
	[[ |	   |		for (;;)	       --+
	   |	   |	  +->	{			 |
	   |	[{ |	  |	    foo(32);		 |     --+
	   |	   |   [{ |	    if (bar(a))  --+	 | ]}	 |
	   +--	   |	  +--		break;	   | ]}  |	 |
		   |		}		 <-+	 |	 | ][
		   +--		foobar(a)		 |	 |
			    }			       <-+	 |
			}				       <-+

When writing C++ or Java, the outer {} block is for the class.  The next level
of {} is for a method.  When somewhere inside a class use "[m" to find the
previous start of a method.  "]m" finds the next start of a method.

Additionally, "[]" moves backward to the end of a function and "]]" moves
forward to the start of the next function.  The end of a function is defined
by a "}" in the first column.

				int func1(void)
				{
					return 1;
		  +---------->  }
		  |
	      []  |		int func2(void)
		  |	   +->	{
		  |    [[  |		if (flag)
	start	  +--	   +--			return flag;
		  |    ][  |		return 2;
		  |	   +->	}
	      ]]  |
		  |		int func3(void)
		  +---------->	{
					return 3;
				}

Don't forget you can also use "%" to move between matching (), {} and [].
That also works when they are many lines apart.


MOVING IN BRACES

The "[(" and "])" commands work similar to "[{" and "]}", except that they
work on () pairs instead of {} pairs.
>
				  [(
<		    <--------------------------------
			      <-------
		if (a == b && (c == d || (e > f)) && x > y) ~
				  -------------->
			  --------------------------------> >
				       ])

MOVING IN COMMENTS

To move back to the start of a comment use "[/".  Move forward to the end of a
comment with "]/".  This only works for /* - */ comments.

	  +->	  +-> /*
	  |    [/ |    * A comment about      --+
       [/ |	  +--  * wonderful life.	| ]/
	  |	       */		      <-+
	  |
	  +--	       foo = bar * 3;	      --+
						| ]/
		       /* a short comment */  <-+

==============================================================================
*29.4*	Finding global identifiers

You are editing a C program and wonder if a variable is declared as "int" or
"unsigned".  A quick way to find this is with the "[I" command.
   Suppose the cursor is on the word "column".  Type: >

	[I

Vim will list the matching lines it can find.  Not only in the current file,
but also in all included files (and files included in them, etc.).  The result
looks like this:

	structs.h ~
	 1:   29     unsigned     column;    /* column number */ ~

The advantage over using tags or the preview window is that included files are
searched.  In most cases this results in the right declaration to be found.
Also when the tags file is out of date.  Also when you don't have tags for the
included files.
   However, a few things must be right for "[I" to do its work.  First of all,
the 'include' option must specify how a file is included.  The default value
works for C and C++.  For other languages you will have to change it.


LOCATING INCLUDED FILES

   Vim will find included files in the places specified with the 'path'
option.  If a directory is missing, some include files will not be found.  You
can discover this with this command: >

	:checkpath

It will list the include files that could not be found.  Also files included
by the files that could be found.  An example of the output:

	--- Included files not found in path --- ~
	<io.h> ~
	vim.h --> ~
	  <functions.h> ~
	  <clib/exec_protos.h> ~

The "io.h" file is included by the current file and can't be found.  "vim.h"
can be found, thus ":checkpath" goes into this file and checks what it
includes.  The "functions.h" and "clib/exec_protos.h" files, included by
"vim.h" are not found.

	Note:
	Vim is not a compiler.  It does not recognize "#ifdef" statements.
	This means every "#include" statement is used, also when it comes
	after "#if NEVER".

To fix the files that could not be found, add a directory to the 'path'
option.  A good place to find out about this is the Makefile.  Look out for
lines that contain "-I" items, like "-I/usr/local/X11".  To add this directory
use: >

	:set path+=/usr/local/X11

When there are many subdirectories, you can use the "*" wildcard.  Example: >

	:set path+=/usr/*/include

This would find files in "/usr/local/include" as well as "/usr/X11/include".

When working on a project with a whole nested tree of included files, the "**"
items is useful.  This will search down in all subdirectories.  Example: >

	:set path+=/projects/invent/**/include

This will find files in the directories:

	/projects/invent/include ~
	/projects/invent/main/include ~
	/projects/invent/main/os/include ~
	etc.

There are even more possibilities.  Check out the 'path' option for info.
   If you want to see which included files are actually found, use this
command: >

	:checkpath!

You will get a (very long) list of included files, the files they include, and
so on.  To shorten the list a bit, Vim shows "(Already listed)" for files that
were found before and doesn't list the included files in there again.


JUMPING TO A MATCH

"[I" produces a list with only one line of text.  When you want to have a
closer look at the first item, you can jump to that line with the command: >

	[<Tab>

You can also use "[ CTRL-I", since CTRL-I is the same as pressing <Tab>.

The list that "[I" produces has a number at the start of each line.  When you
want to jump to another item than the first one, type the number first: >

	3[<Tab>

Will jump to the third item in the list.  Remember that you can use CTRL-O to
jump back to where you started from.


RELATED COMMANDS

	[i		only lists the first match
	]I		only lists items below the cursor
	]i		only lists the first item below the cursor


FINDING DEFINED IDENTIFIERS

The "[I" command finds any identifier.  To find only macros, defined with
"#define" use: >

	[D

Again, this searches in included files.  The 'define' option specifies what a
line looks like that defines the items for "[D".  You could change it to make
it work with other languages than C or C++.
   The commands related to "[D" are:

	[d		only lists the first match
	]D		only lists items below the cursor
	]d		only lists the first item below the cursor

==============================================================================
*29.5*	Finding local identifiers

The "[I" command searches included files.  To search in the current file only,
and jump to the first place where the word under the cursor is used: >

	gD

Hint: Goto Definition.  This command is very useful to find a variable or
function that was declared locally ("static", in C terms).  Example (cursor on
"counter"):

	   +->   static int counter = 0;
	   |
	   |     int get_counter(void)
	gD |     {
	   |	     ++counter;
	   +--	     return counter;
		 }

To restrict the search even further, and look only in the current function,
use this command: >

	gd

This will go back to the start of the current function and find the first
occurrence of the word under the cursor.  Actually, it searches backwards to
an empty line above a "{" in the first column.  From there it searches forward
for the identifier.  Example (cursor on "idx"):

		int find_entry(char *name)
		{
	   +->	    int idx;
	   |
	gd |	    for (idx = 0; idx < table_len; ++idx)
	   |		if (strcmp(table[idx].name, name) == 0)
	   +--		    return idx;
		}

==============================================================================

Next chapter: |usr_30.txt|  Editing programs

Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: