]> git.r.bdr.sh - rbdr/dotfiles/blob - vim/doc/tagbar.txt
Add gitignore
[rbdr/dotfiles] / vim / doc / tagbar.txt
1 *tagbar.txt* Display tags of a file in their correct scope
2
3 Author: Jan Larres <jan@majutsushi.net>
4 Licence: Vim licence, see |license|
5 Homepage: http://majutsushi.github.com/tagbar/
6 Version: 2.3
7
8 ==============================================================================
9 Contents *tagbar* *tagbar-contents*
10
11 1. Intro ........................... |tagbar-intro|
12 Pseudo-tags ................... |tagbar-pseudotags|
13 Supported features ............ |tagbar-features|
14 Other ctags-compatible programs |tagbar-other|
15 2. Requirements .................... |tagbar-requirements|
16 3. Installation .................... |tagbar-installation|
17 4. Usage ........................... |tagbar-usage|
18 Commands ...................... |tagbar-commands|
19 Key mappings .................. |tagbar-keys|
20 5. Configuration ................... |tagbar-configuration|
21 Highlight colours ............. |tagbar-highlight|
22 Automatically opening Tagbar .. |tagbar-autoopen|
23 6. Extending Tagbar ................ |tagbar-extend|
24 7. Troubleshooting & Known issues .. |tagbar-issues|
25 8. History ......................... |tagbar-history|
26 9. Todo ............................ |tagbar-todo|
27 10. Credits ......................... |tagbar-credits|
28
29 ==============================================================================
30 1. Intro *tagbar-intro*
31
32 Tagbar is a plugin for browsing the tags of source code files. It provides a
33 sidebar that displays the ctags-generated tags of the current file, ordered by
34 their scope. This means that for example methods in C++ are displayed under
35 the class they are defined in.
36
37 Let's say we have the following code inside of a C++ file:
38 >
39 namespace {
40 char a;
41
42 class Foo
43 {
44 public:
45 Foo();
46 ~Foo();
47 private:
48 int var;
49 };
50 };
51 <
52 Then Tagbar would display the tag information like so:
53 >
54 __anon1* : namespace
55 Foo : class
56 +Foo()
57 +~Foo()
58 -var
59 a
60 <
61 This example shows several important points. First, the tags are listed
62 indented below the scope they are defined in. Second, the type of a scope is
63 listed after its name and a colon. Third, tags for which the access/visibility
64 information is known are prefixed with a symbol indicating that.
65
66 ------------------------------------------------------------------------------
67 PSEUDO-TAGS *tagbar-pseudotags*
68
69 The example also introduces the concept of "pseudo-tags". Pseudo-tags are tags
70 that are not explicitly defined in the file but have children in it. In this
71 example the namespace doesn't have a name and thus ctags doesn't generate a
72 tag for it, but since it has children it still needs to be displayed using an
73 auto-generated name.
74
75 Another case where pseudo-tags appear is in C++ implementation files. Since
76 classes are usually defined in a header file but the member methods and
77 variables in the implementation file the class itself won't generate a tag
78 in that file.
79
80 Since pseudo-tags don't really exist they cannot be jumped to from the Tagbar
81 window.
82
83 Pseudo-tags are denoted with an asterisk ('*') at the end of their name.
84
85 ------------------------------------------------------------------------------
86 SUPPORTED FEATURES *tagbar-features*
87
88 The following features are supported by Tagbar:
89
90 - Display tags under their correct scope.
91 - Automatically update the tags when switching between buffers and editing
92 files.
93 - Display visibility information of tags if available.
94 - Highlight the tag near the cursor while editing files.
95 - Jump to a tag from the Tagbar window.
96 - Display the complete prototype of a tag.
97 - Tags can be sorted either by name or order of appearance in the file.
98 - Scopes can be folded to hide uninteresting information.
99 - Supports all of the languages that ctags does, i.e. Ant, Assembler, ASP,
100 Awk, Basic, BETA, C, C++, C#, COBOL, DosBatch, Eiffel, Erlang, Flex,
101 Fortran, HTML, Java, JavaScript, Lisp, Lua, Make, MatLab, OCaml, Pascal,
102 Perl, PHP, Python, REXX, Ruby, Scheme, Shell script, SLang, SML, SQL, Tcl,
103 Tex, Vera, Verilog, VHDL, Vim and YACC.
104 - Can be extended to support arbitrary new types.
105
106 ------------------------------------------------------------------------------
107 OTHER CTAGS-COMPATIBLE PROGRAMS *tagbar-other*
108
109 Tagbar theoretically also supports filetype-specific programs that can output
110 tag information that is compatible with ctags. However due to potential
111 incompatibilities this may not always completely work. Tagbar has been tested
112 with doctorjs/jsctags and will use that if present, other programs require
113 some configuration (see |tagbar-extend|). If a program does not work even with
114 correct configuration please contact me.
115
116 Note: Please check |tagbar-issues| for some possible issues with jsctags.
117
118 ==============================================================================
119 2. Requirements *tagbar-requirements*
120
121 The following requirements have to be met in order to be able to use tagbar:
122
123 - Vim 7.0 or higher. Older versions will not work since Tagbar uses data
124 structures that were only introduced in Vim 7.
125 - Exuberant ctags 5.5 or higher. Ctags is the program that generates the
126 tag information that Tagbar uses. It is shipped with most Linux
127 distributions, otherwise it can be downloaded from the following
128 website:
129
130 http://ctags.sourceforge.net/
131
132 Tagbar will work on any platform that ctags runs on -- this includes
133 UNIX derivatives, Mac OS X and Windows. Note that other versions like
134 GNU ctags will not work.
135 Tagbar generates the tag information by itself and doesn't need (or use)
136 already existing tag files.
137 - File type detection must be turned on in vim. This can be done with the
138 following command in your vimrc:
139 >
140 filetype on
141 <
142 See |filetype| for more information.
143 - Tagbar will not work in |restricted-mode| or with 'compatible' set.
144
145 ==============================================================================
146 3. Installation *tagbar-installation*
147
148 Use the normal Vimball install method for installing tagbar.vba:
149 >
150 vim tagbar.vba
151 :so %
152 :q
153 <
154 Alternatively you can clone the git repository and then add the path to
155 'runtimepath' or use the pathogen plugin. Don't forget to run |:helptags| if
156 you're not using pathogen.
157
158 If the ctags executable is not installed in one of the directories in your
159 $PATH environment variable you have to set the g:tagbar_ctags_bin variable,
160 see |g:tagbar_ctags_bin|.
161
162 ==============================================================================
163 4. Usage *tagbar-usage*
164
165 There are essentially two ways to use Tagbar:
166
167 1. Have it running all the time in a window on the side of the screen. In
168 this case Tagbar will update its contents whenever the source file is
169 changed and highlight the tag the cursor is currently on in the file. If
170 a tag is selected in Tagbar the file window will jump to the tag and the
171 Tagbar window will stay open. |g:tagbar_autoclose| has to be unset for
172 this mode.
173 2. Only open Tagbar when you want to jump to a specific tag and have it
174 close automatically once you have selected one. This can be useful for
175 example for small screens where a permanent window would take up too much
176 space. You have to set the option |g:tagbar_autoclose| in this case. The
177 cursor will also automatically jump to the Tagbar window when opening it.
178
179 Opening and closing the Tagbar window~
180 Use |:TagbarOpen| or |:TagbarToggle| to open the Tagbar window if it is
181 closed. By default the window is opened on the right side, set the option
182 |g:tagbar_left| to open it on the left instead. If the window is already open,
183 |:TagbarOpen| will jump to it and |:TagbarToggle| will close it again.
184 |:TagbarClose| will simply close the window if it is open.
185
186 It is probably a good idea to assign a key to these commands. For example, put
187 this in your |vimrc|:
188 >
189 nnoremap <silent> <F9> :TagbarToggle<CR>
190 <
191 You can then open and close Tagbar by simply pressing the <F9> key.
192
193 You can also use |:TagbarOpenAutoClose| to open the Tagbar window, jump to it
194 and have it close automatically on tag selection regardless of the
195 |g:tagbar_autoclose| setting.
196
197 Jumping to tags~
198 When you're inside the Tagbar window you can jump to the definition of a tag
199 by moving the cursor to a tag and pressing <Enter> or double-clicking on it
200 with the mouse. The source file will then move to the definition and put the
201 cursor in the corresponding line. This won't work for pseudo-tags.
202
203 Sorting~
204 You can sort the tags in the Tagbar window in two ways: by name or by file
205 order. Sorting them by name simply displays the tags in their alphabetical
206 order under their corresponding scope. Sorting by file order means that the
207 tags keep the order they have in the source file, but are still associated
208 with the correct scope. You can change the sort order by pressing the "s" key
209 in the Tagbar window. The current sort order is displayed in the statusbar of
210 the Tagbar window.
211
212 Folding~
213 The displayed scopes (and unscoped types) can be folded to hide uninteresting
214 information. Mappings similar to Vim's built-in ones are provided. Folds can
215 also be opened and closed by clicking on the fold icon with the mouse.
216
217 Displaying the prototype of a tag~
218 Tagbar can display the prototype of a tag. More precisely it can display the
219 line in which the tag is defined. This can be done by either pressing <Space>
220 when on a tag or hovering over a tag with the mouse. In the former case the
221 prototype will be displayed in the command line |Command-line|, in the latter
222 case it will be displayed in a pop-up window. The prototype will also be
223 displayed when the cursor stays on a tag for 'updatetime' milliseconds.
224
225 ------------------------------------------------------------------------------
226 COMMANDS *tagbar-commands*
227
228 :TagbarOpen [{flags}]
229 Open the Tagbar window if it is closed.
230
231 Additional behaviour can be specified with the optional {flags} argument.
232 It is a string which can contain these character flags:
233 'f' Jump to Tagbar window when opening (just as if |g:tagbar_autofocus|
234 were set to 1)
235 'j' Jump to Tagbar window if already open
236 'c' Close Tagbar on tag selection (just as if |g:tagbar_autoclose| were
237 set to 1, but doesn't imply 'f')
238
239 For example, the following command would always jump to the Tagbar window,
240 opening it first if necessary, but keep it open after selecting a tag
241 (unless |g:tagbar_autoclose| is set): >
242 :TagbarOpen fj
243 <
244 :TagbarClose
245 Close the Tagbar window if it is open.
246
247 :TagbarToggle
248 Open the Tagbar window if it is closed or close it if it is open.
249
250 :TagbarOpenAutoClose
251 Open the Tagbar window, jump to it and close it on tag selection. This is
252 an alias for ":TagbarOpen fc".
253
254 :TagbarSetFoldlevel {number}
255 Set the foldlevel of the tags of the current file to {number}. The
256 foldlevel of tags in other files remains unaffected. Works in the same way
257 as 'foldlevel'.
258
259 :TagbarShowTag
260 Open the parent folds of the current tag in the file window as much as
261 needed for the tag to be visible in the Tagbar window.
262
263 :TagbarDebug [logfile]
264 Start debug mode. This will write debug messages to file [logfile] while
265 using Tagbar. If no argument is given "tagbardebug.log" in the current
266 directory is used. Note: an existing file will be overwritten!
267
268 :TagbarDebugEnd
269 End debug mode, debug messages will no longer be written to the logfile.
270
271 ------------------------------------------------------------------------------
272 KEY MAPPINGS *tagbar-keys*
273
274 The following mappings are valid in the Tagbar window:
275
276 <F1> Display key mapping help.
277 <CR>/<Enter> Jump to the tag under the cursor. Doesn't work for pseudo-tags
278 or generic headers.
279 p Jump to the tag under the cursor, but stay in the Tagbar window.
280 <LeftMouse> When on a fold icon, open or close the fold depending on the
281 current state.
282 <2-LeftMouse> Same as <CR>. See |g:tagbar_singleclick| if you want to use a
283 single- instead of a double-click.
284 <Space> Display the prototype of the current tag (i.e. the line defining
285 it) in the command line.
286 +/zo Open the fold under the cursor.
287 -/zc Close the fold under the cursor or the current one if there is
288 no fold under the cursor.
289 o/za Toggle the fold under the cursor or the current one if there is
290 no fold under the cursor.
291 */zR Open all folds by setting foldlevel to 99.
292 =/zM Close all folds by setting foldlevel to 0.
293 <C-N> Go to the next top-level tag.
294 <C-P> Go to the previous top-level tag.
295 s Toggle sort order between name and file order.
296 x Toggle zooming the window.
297 q Close the Tagbar window.
298
299 ==============================================================================
300 5. Configuration *tagbar-configuration*
301
302 *g:tagbar_ctags_bin*
303 g:tagbar_ctags_bin~
304 Default: empty
305
306 Use this option to specify the location of your ctags executable. Only needed
307 if it is not in one of the directories in your $PATH environment variable.
308
309 Example:
310 >
311 let g:tagbar_ctags_bin = 'C:\Ctags5.8\ctags.exe'
312 <
313
314 *g:tagbar_left*
315 g:tagbar_left~
316 Default: 0
317
318 By default the Tagbar window will be opened on the right-hand side of vim. Set
319 this option to open it on the left instead.
320
321 Example:
322 >
323 let g:tagbar_left = 1
324 <
325
326 *g:tagbar_width*
327 g:tagbar_width~
328 Default: 40
329
330 Width of the Tagbar window in characters.
331
332 Example:
333 >
334 let g:tagbar_width = 30
335 <
336
337 *g:tagbar_autoclose*
338 g:tagbar_autoclose~
339 Default: 0
340
341 If you set this option the Tagbar window will automatically close when you
342 jump to a tag. This implies |g:tagbar_autofocus|.
343
344 Example:
345 >
346 let g:tagbar_autoclose = 1
347 <
348
349 *g:tagbar_autofocus*
350 g:tagbar_autofocus~
351 Default: 0
352
353 If you set this option the cursor will move to the Tagbar window when it is
354 opened.
355
356 Example:
357 >
358 let g:tagbar_autofocus = 1
359 <
360
361 *g:tagbar_sort*
362 g:tagbar_sort~
363 Default: 1
364
365 If this option is set the tags are sorted according to their name. If it is
366 unset they are sorted according to their order in the source file. Note that
367 in the second case Pseudo-tags are always sorted before normal tags of the
368 same kind since they don't have a real position in the file.
369
370 Example:
371 >
372 let g:tagbar_sort = 0
373 <
374
375 *g:tagbar_compact*
376 g:tagbar_compact~
377 Default: 0
378
379 Setting this option will result in Tagbar omitting the short help at the
380 top of the window and the blank lines in between top-level scopes in order to
381 save screen real estate.
382
383 Example:
384 >
385 let g:tagbar_compact = 1
386 <
387
388 *g:tagbar_expand*
389 g:tagbar_expand~
390 Default: 0
391
392 If this option is set the Vim window will be expanded by the width of the
393 Tagbar window if using a GUI version of Vim.
394
395 Example:
396 >
397 let g:tagbar_expand = 1
398 <
399
400 *g:tagbar_singleclick*
401 g:tagbar_singleclick~
402 Default: 0
403
404 If this option is set then a single- instead of a double-click is used to jump
405 to the tag definition.
406
407 Example:
408 >
409 let g:tagbar_singleclick = 1
410 <
411
412 *g:tagbar_foldlevel*
413 g:tagbar_foldlevel~
414 Default: 99
415
416 The initial foldlevel for folds in the Tagbar window. Fold with a level higher
417 than this number will be closed.
418
419 Example:
420 >
421 let g:tagbar_foldlevel = 2
422 <
423
424 *g:tagbar_iconchars*
425 g:tagbar_iconchars~
426
427 Since the display of the icons used to indicate open or closed folds depends
428 on the actual font used, different characters may be optimal for different
429 fonts. With this variable you can set the icons to characters of your liking.
430 The first character in the list specifies the icon to use for a closed fold,
431 and the second one for an open fold.
432
433 Examples (don't worry if some the characters aren't displayed correctly, just
434 choose other characters in that case):
435 >
436 let g:tagbar_iconchars = ['â–¶', 'â–¼'] (default on Linux and Mac OS X)
437 let g:tagbar_iconchars = ['â–¾', 'â–¸']
438 let g:tagbar_iconchars = ['â–·', 'â—¢']
439 let g:tagbar_iconchars = ['+', '-'] (default on Windows)
440 <
441
442 *g:tagbar_autoshowtag*
443 g:tagbar_autoshowtag~
444 Default: 0
445
446 If this variable is set and the current tag is inside of a closed fold then
447 the folds will be opened as much as needed for the tag to be visible so it can
448 be highlighted. If it is not set then the folds won't be opened and the parent
449 tag will be highlighted instead. You can use the TagbarShowTag command to open
450 the folds manually.
451
452 Example:
453 >
454 let g:tagbar_autoshowtag = 1
455 <
456
457 *g:tagbar_updateonsave_maxlines*
458 g:tagbar_updateonsave_maxlines~
459 Default: 5000
460
461 If the current file has fewer lines than the value of this variable, Tagbar
462 will update immediately after saving the file. If it is longer then the update
463 will only happen on the |CursorHold| event and when switching buffers (or
464 windows). This is to prevent the time it takes to save a large file from
465 becoming annoying in case you have a slow computer. If you have a fast
466 computer you can set it to a higher value.
467
468 Example:
469 >
470 let g:tagbar_updateonsave_maxlines = 10000
471 <
472
473 *g:tagbar_systemenc*
474 g:tagbar_systemenc~
475 Default: value of 'encoding'
476
477 This variable is for cases where the character encoding of your operating
478 system is different from the one set in Vim, i.e. the 'encoding' option. For
479 example, if you use a Simplified Chinese Windows version that has a system
480 encoding of "cp936", and you have set 'encoding' to "utf-8", then you would
481 have to set this variable to "cp936".
482
483 Example:
484 >
485 let g:tagbar_systemenc = 'cp936'
486 <
487
488 ------------------------------------------------------------------------------
489 HIGHLIGHT COLOURS *tagbar-highlight*
490
491 All of the colours used by Tagbar can be customized. Here is a list of the
492 highlight groups that are defined by Tagbar:
493
494 TagbarComment
495 The help at the top of the buffer.
496
497 TagbarKind
498 The header of generic "kinds" like "functions" and "variables".
499
500 TagbarNestedKind
501 The "kind" headers in square brackets inside of scopes.
502
503 TagbarScope
504 Tags that define a scope like classes, structs etc.
505
506 TagbarType
507 The type of a tag or scope if available.
508
509 TagbarSignature
510 Function signatures.
511
512 TagbarPseudoID
513 The asterisk (*) that signifies a pseudo-tag.
514
515 TagbarFoldIcon
516 The fold icon on the left of foldable tags.
517
518 TagbarHighlight
519 The colour that is used for automatically highlighting the current tag.
520
521 TagbarAccessPublic
522 The "public" visibility/access symbol.
523
524 TagbarAccessProtected
525 The "protected" visibility/access symbol.
526
527 TagbarAccessPrivate
528 The "private" visibility/access symbol.
529
530 If you want to change any of those colours put a line like the following in
531 your vimrc:
532 >
533 highlight TagbarScope guifg=Green ctermfg=Green
534 <
535 See |:highlight| for more information.
536
537 ------------------------------------------------------------------------------
538 AUTOMATICALLY OPENING TAGBAR *tagbar-autoopen*
539
540 Since there are several different situations in which you might want to open
541 Tagbar automatically there is no single option to enable automatic opening.
542 Instead, autocommands can be used together with a convenience function that
543 opens Tagbar only if a supported file is open(ed).
544
545 If you want to open Tagbar automatically on Vim startup no matter what put
546 this into your vimrc:
547 >
548 autocmd VimEnter * nested :TagbarOpen
549 <
550 If you want to open it only if you're opening Vim with a supported file/files
551 use this instead:
552 >
553 autocmd VimEnter * nested :call tagbar#autoopen()
554 <
555 For opening Tagbar also if you open a supported file in an already running
556 Vim:
557 >
558 autocmd FileType * nested :call tagbar#autoopen()
559 <
560 And if you only want to open Tagbar only for specific filetypes, not for all
561 of the supported ones:
562 >
563 autocmd FileType c,cpp nested :TagbarOpen
564 <
565 Check out |autocmd.txt| if you want it to open automatically in more
566 complicated cases.
567
568 ==============================================================================
569 6. Extending Tagbar *tagbar-extend*
570
571 Tagbar has a flexible mechanism for extending the existing file type (i.e.
572 language) definitions. This can be used both to change the settings of the
573 existing types and to add completely new types. A complete configuration
574 consists of a type definition for Tagbar in your |vimrc| and optionally a
575 language definition for ctags in case you want to add a new language.
576
577 Before writing your own extension have a look at the wiki
578 (https://github.com/majutsushi/tagbar/wiki/Support-for-additional-filetypes)
579 or try googling for existing ones. If you do end up creating your own
580 extension please consider adding it to the wiki so that others will be able to
581 use it, too.
582
583 Every type definition in Tagbar is a dictionary with the following keys:
584
585 ctagstype: The name of the language as recognized by ctags. Use the command >
586 ctags --list-languages
587 < to get a list of the languages ctags supports. The case doesn't
588 matter.
589 kinds: A list of the "language kinds" that should be listed in Tagbar,
590 ordered by the order they should appear in in the Tagbar window.
591 Use the command >
592 ctags --list-kinds={language name}
593 < to get a list of the kinds ctags supports for a given language. An
594 entry in this list is a string with two or three parts separated
595 by a colon: the first part is the one-character abbreviation that
596 ctags uses, and the second part is an arbitrary string that will
597 be used in Tagbar as the header for the tags of this kind that are
598 not listed under a specific scope. The optional third part
599 determines whether tags of this kind should be folded by default,
600 with 1 meaning they should be folded and 0 they should not. If
601 this part is omitted the tags will not be folded by default. For
602 example, the string >
603 "f:functions:1"
604 < would list all the function definitions in a file under the header
605 "functions" and fold them.
606 sro: The scope resolution operator. For example, in C++ it is "::" and
607 in Java it is ".". If in doubt run ctags as shown below and check
608 the output.
609 kind2scope: A dictionary describing the mapping of tag kinds (in their
610 one-character representation) to the scopes their children will
611 appear in, for example classes, structs etc.
612 Unfortunately there is no ctags option to list the scopes, you
613 have to look at the tags ctags generates manually. For example,
614 let's say we have a C++ file "test.cpp" with the following
615 contents: >
616 class Foo
617 {
618 public:
619 Foo();
620 ~Foo();
621 private:
622 int var;
623 };
624 < We then run ctags in the following way: >
625 ctags -f - --format=2 --excmd=pattern --extra= --fields=nksaSmt test.cpp
626 < Then the output for the variable "var" would look like this: >
627 var tmp.cpp /^ int var;$/;" kind:m line:11 class:Foo access:private
628 < This shows that the scope name for an entry in a C++ class is
629 simply "class". So this would be the word that the "kind"
630 character of a class has to be mapped to.
631 scope2kind: The opposite of the above, mapping scopes to the kinds of their
632 parents. Most of the time it is the exact inverse of the above,
633 but in some cases it can be different, for example when more than
634 one kind maps to the same scope. If it is the exact inverse for
635 your language you only need to specify one of the two keys.
636 replace: If you set this entry to 1 your definition will completely replace
637 {optional} an existing default definition. This is useful if you want to
638 disable scopes for a file type for some reason. Note that in this
639 case you have to provide all the needed entries yourself!
640 sort: This entry can be used to override the global sort setting for
641 {optional} this specific file type. The meaning of the value is the same as
642 with the global setting, that is if you want to sort tags by name
643 set it to 1 and if you want to sort them according to their order
644 in the file set it to 0.
645 deffile: The path to a file with additional ctags definitions (see the
646 {optional} section below on adding a new definition for what exactly that
647 means). This is especially useful for ftplugins since they can
648 provide a complete type definition with ctags and Tagbar
649 configurations without requiring user intervention.
650 Let's say you have an ftplugin that adds support for the language
651 "mylang", and your directory structure looks like this: >
652 ctags/mylang.cnf
653 ftplugin/mylang.vim
654 < Then the "deffile" entry would look like this to allow for the
655 plugin to be installed in an arbitray location (for example
656 with pathogen): >
657
658 'deffile' : expand('<sfile>:p:h:h') . '/ctags/mylang.cnf'
659 <
660 ctagsbin: The path to a filetype-specific ctags-compatible program like
661 {optional} jsctags. Set it in the same way as |g:tagbar_ctags_bin|. jsctags is
662 used automatically if found in your $PATH and does not have to be
663 set in that case. If it is not in your path you have to set this
664 key, the rest of the configuration should not be necessary (unless
665 you want to change something, of course).
666 ctagsargs: The arguments to be passed to the filetype-specific ctags program
667 {optional} (without the filename). Make sure you set an option that makes the
668 program output its data on stdout. Not used for the normal ctags
669 program.
670
671
672 You then have to assign this dictionary to a variable in your vimrc with the
673 name
674 >
675 g:tagbar_type_{vim filetype}
676 <
677 For example, for C++ the name would be "g:tagbar_type_cpp". If you don't know
678 the vim file type then run the following command:
679 >
680 :set filetype?
681 <
682 and vim will display the file type of the current buffer.
683
684 Example: C++~
685 Here is a complete example that shows the default configuration for C++ as
686 used in Tagbar. This is just for illustration purposes since user
687 configurations will usually be less complicated.
688 >
689 let g:tagbar_type_cpp = {
690 \ 'ctagstype' : 'c++',
691 \ 'kinds' : [
692 \ 'd:macros:1',
693 \ 'p:prototypes:1',
694 \ 'g:enums',
695 \ 'e:enumerators',
696 \ 't:typedefs',
697 \ 'n:namespaces',
698 \ 'c:classes',
699 \ 's:structs',
700 \ 'u:unions',
701 \ 'f:functions',
702 \ 'm:members',
703 \ 'v:variables'
704 \ ],
705 \ 'sro' : '::',
706 \ 'kind2scope' : {
707 \ 'g' : 'enum',
708 \ 'n' : 'namespace',
709 \ 'c' : 'class',
710 \ 's' : 'struct',
711 \ 'u' : 'union'
712 \ },
713 \ 'scope2kind' : {
714 \ 'enum' : 'g',
715 \ 'namespace' : 'n',
716 \ 'class' : 'c',
717 \ 'struct' : 's',
718 \ 'union' : 'u'
719 \ }
720 \ }
721 <
722
723 Which of the keys you have to specify depends on what you want to do.
724
725 Changing an existing definition~
726 If you want to change an existing definition you only need to specify the
727 parts that you want to change. It probably only makes sense to change "kinds"
728 and/or "scopes", which would be the case if you wanted to exclude certain
729 kinds from appearing in Tagbar or if you want to change their order. As an
730 example, if you didn't want Tagbar to show prototypes for C++ files and switch
731 the order of enums and typedefs, you would do it like this:
732 >
733 let g:tagbar_type_cpp = {
734 \ 'kinds' : [
735 \ 'd:macros:1',
736 \ 'g:enums',
737 \ 't:typedefs',
738 \ 'e:enumerators',
739 \ 'n:namespaces',
740 \ 'c:classes',
741 \ 's:structs',
742 \ 'u:unions',
743 \ 'f:functions',
744 \ 'm:members',
745 \ 'v:variables'
746 \ ]
747 \ }
748 <
749 Compare with the complete example above to see the difference.
750
751 Adding a definition for a new language/file type~
752 In order to be able to add a new language to Tagbar you first have to create a
753 configuration for ctags that it can use to parse the files. This can be done
754 in two ways:
755
756 1. Use the --regex argument for specifying regular expressions that are used
757 to parse the files. An example of this is given below. A disadvantage of
758 this approach is that you can't specify scopes.
759 2. Write a parser plugin in C for ctags. This approach is much more powerful
760 than the regex approach since you can make use of all of ctags'
761 functionality but it also requires much more work. Read the ctags
762 documentation for more information about how to do this.
763
764 For the first approach the only keys that are needed in the Tagbar definition
765 are "ctagstype" and "kinds". A definition that supports scopes has to define
766 those two and in addition "scopes", "sro" and at least one of "kind2scope" and
767 "scope2kind".
768
769 Let's assume we want to add support for LaTeX to Tagbar using the regex
770 approach. First we put the following text into ~/.ctags or a file pointed to
771 by the "deffile" definition entry:
772 >
773 --langdef=latex
774 --langmap=latex:.tex
775 --regex-latex=/^\\tableofcontents/TABLE OF CONTENTS/s,toc/
776 --regex-latex=/^\\frontmatter/FRONTMATTER/s,frontmatter/
777 --regex-latex=/^\\mainmatter/MAINMATTER/s,mainmatter/
778 --regex-latex=/^\\backmatter/BACKMATTER/s,backmatter/
779 --regex-latex=/^\\bibliography\{/BIBLIOGRAPHY/s,bibliography/
780 --regex-latex=/^\\part[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/PART \2/s,part/
781 --regex-latex=/^\\part[[:space:]]*\*[[:space:]]*\{([^}]+)\}/PART \1/s,part/
782 --regex-latex=/^\\chapter[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/CHAP \2/s,chapter/
783 --regex-latex=/^\\chapter[[:space:]]*\*[[:space:]]*\{([^}]+)\}/CHAP \1/s,chapter/
784 --regex-latex=/^\\section[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\. \2/s,section/
785 --regex-latex=/^\\section[[:space:]]*\*[[:space:]]*\{([^}]+)\}/\. \1/s,section/
786 --regex-latex=/^\\subsection[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\.\. \2/s,subsection/
787 --regex-latex=/^\\subsection[[:space:]]*\*[[:space:]]*\{([^}]+)\}/\.\. \1/s,subsection/
788 --regex-latex=/^\\subsubsection[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\.\.\. \2/s,subsubsection/
789 --regex-latex=/^\\subsubsection[[:space:]]*\*[[:space:]]*\{([^}]+)\}/\.\.\. \1/s,subsubsection/
790 --regex-latex=/^\\includegraphics[[:space:]]*(\[[^]]*\])?[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\3/g,graphic+listing/
791 --regex-latex=/^\\lstinputlisting[[:space:]]*(\[[^]]*\])?[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\3/g,graphic+listing/
792 --regex-latex=/\\label[[:space:]]*\{([^}]+)\}/\1/l,label/
793 --regex-latex=/\\ref[[:space:]]*\{([^}]+)\}/\1/r,ref/
794 --regex-latex=/\\pageref[[:space:]]*\{([^}]+)\}/\1/p,pageref/
795 <
796 This will create a new language definition with the name "latex" and associate
797 it with files with the extension ".tex". It will also define the kinds "s" for
798 sections, chapters and the like, "g" for included graphics, "l" for labels,
799 "r" for references and "p" for page references. See the ctags documentation
800 for more information about the exact syntax.
801
802 Now we have to create the Tagbar language definition in our vimrc:
803 >
804 let g:tagbar_type_tex = {
805 \ 'ctagstype' : 'latex',
806 \ 'kinds' : [
807 \ 's:sections',
808 \ 'g:graphics',
809 \ 'l:labels',
810 \ 'r:refs:1',
811 \ 'p:pagerefs:1'
812 \ ],
813 \ 'sort' : 0,
814 \ 'deffile' : expand('<sfile>:p:h:h') . '/ctags/latex.cnf'
815 \ }
816 <
817 The "deffile" field is of course only needed if the ctags definition actually
818 is in that file and not in ~/.ctags.
819
820 Sort has been disabled for LaTeX so that the sections appear in their correct
821 order. They unfortunately can't be shown nested with their correct scopes
822 since as already mentioned the regular expression approach doesn't support
823 that.
824
825 Tagbar should now be able to show the sections and other tags from LaTeX
826 files.
827
828 ==============================================================================
829 7. Troubleshooting & Known issues *tagbar-issues*
830
831 As a general rule, if the tag information displayed by Tagbar is wrong (for
832 example, a method doesn't show up or is in the wrong place) you should first
833 try running ctags manually to see whether ctags reports the wrong information
834 or whether that information is correct and Tagbar does something wrong. To run
835 ctags manually execute the following command in a terminal:
836 >
837 ctags -f - --format=2 --excmd=pattern --extra= --fields=nksaSmt myfile
838 <
839 If you set the |g:tagbar_ctags_bin| variable you probably have to use the same
840 value here instead of simply "ctags".
841
842 If Tagbar doesn't seem to work at all, but you don't get any error messages,
843 you can use Tagbar's debug mode to try to find the source of the problem (see
844 |tagbar-commands| on how to invoke it). In that case you should especially pay
845 attention to the reported file type and the ctags command line in the log
846 file.
847
848
849 - jsctags has to be newer than 2011-01-06 since it needs the "-f" option to
850 work. Also, the output of jsctags seems to be a bit unreliable at the
851 moment (especially regarding line numbers), so if you notice some strange
852 behaviour with it please run it manually in a terminal to check whether
853 the bug is in jsctags or Tagbar.
854
855 - Nested pseudo-tags cannot be properly parsed since only the direct parent
856 scope of a tag gets assigned a type, the type of the grandparents is not
857 reported by ctags (assuming the grandparents don't have direct, real
858 children).
859
860 For example, if we have a C++ file with the following content:
861 >
862 foo::Bar::init()
863 {
864 // ...
865 }
866 foo::Baz::method()
867 {
868 // ...
869 }
870 <
871 In this case the type of "foo" is not known. Is it a namespace? A class?
872 For this reason the methods are displayed in Tagbar like this:
873 >
874 foo::Bar* : class
875 init()
876 foo::Baz* : class
877 method()
878 <
879 - Scope-defining tags at the top level that have the same name but a
880 different kind/scope type can lead to an incorrect display. For example,
881 the following Python code will incorrectly insert a pseudo-tag "Inner2"
882 into the "test" class:
883 >
884 class test:
885 class Inner:
886 def foo(self):
887 pass
888
889 def test():
890 class Inner2:
891 def bar(self):
892 pass
893 <
894 I haven't found a clean way around this yet, but it shouldn't be much of a
895 problem in practice anyway. Tags with the same name at any other level are
896 no problem, though.
897
898 ==============================================================================
899 8. History *tagbar-history*
900
901 2.3 (2011-12-24)
902 - Add a convenience function that allows more flexible ways to
903 automatically open Tagbar.
904 - Replace option tagbar_usearrows with tagbar_iconchars to allow custom
905 characters to be specified. This helps with fonts that don't display the
906 default characters properly.
907 - Remove the need to provide the complete jsctags configuration if jsctags
908 is not found in $PATH, now only the concrete path has to be specified.
909 - Add debugging functionality.
910
911 2.2 (2011-11-26)
912 - Small incompatible change: TagbarOpen now doesn't jump to the Tagbar
913 window anymore if it is already open. Use "TagbarOpen j" instead or see
914 its documentation for more options.
915 - Tags inside of scopes now have a header displaying their "kind".
916 - The Tagbar contents are now immediately updated on save for files
917 smaller than a configurable size.
918 - Tagbar can now be configured to jump to a tag with only a single-click
919 instead of a double-click.
920 - Most of the script has been moved to the |autoload| directory, so Vim
921 startup should be faster (thanks to Kien N).
922 - Jumping to tags should work most of the time even if the file has been
923 modified and not saved.
924 - If Ctags has been installed into the default location using Homebrew or
925 MacPorts it should now be found automatically.
926 - Several bugfixes.
927
928 2.1 (2011-05-29)
929 - Make Tagbar work in (hopefully) all cases under Windows
930 - Handle cases where 'encoding' is different from system encoding, for
931 example on a Chinese Windows with 'encoding' set to "utf-8" (see manual
932 for details in case it doesn't work out-of-the-box)
933 - Fixed a bug with the handling of subtypes like "python.django"
934 - If a session got saved with Tagbar open it now gets restored properly
935 - Locally reset foldmethod/foldexpr in case foldexpr got set to something
936 expensive globally
937 - Tagbar now tries hard to go to the correct window when jumping to a tag
938 - Explain some possible issues with the current jsctags version in the
939 manual
940 - Explicitly check for some possible configuration problems to be able to
941 give better feedback
942 - A few other small fixes
943
944 2.0.1 (2011-04-26)
945 - Fix sorting bug when 'ignorecase' is set
946
947 2.0 (2011-04-26)
948 - Folding now works correctly. Folds will be preserved when leaving the
949 Tagbar window and when switching between files. Also tag types can be
950 configured to be folded by default, which is useful for things like
951 includes and imports.
952 - DoctorJS/jsctags and other compatible programs are now supported.
953 - All of the highlight groups can now be overridden.
954 - Added keybinding to quickly jump to next/previous top-level tag.
955 - Added Taglist's "p" keybinding for jumping to a tag without leaving the
956 Tagbar window.
957 - Several bugfixes and other small improvements.
958
959 1.5 (2011-03-06)
960 - Type definitions can now include a path to a file with the ctags
961 definition. This is especially useful for ftplugins that can now ship
962 with a complete ctags and Tagbar configuration without requiring user
963 intervention. Thanks to Jan Christoph Ebersbach for the suggestion.
964 - Added autofocus setting by Taybin Rutkin. This will put the cursor in
965 the Tagbar window when it is opened.
966 - The "scopes" field is no longer needed in type definitions, the
967 information is already there in "scope2kind". Existing definitions will
968 be ignored.
969 - Some fixes and improvements related to redrawing and window switching.
970
971 1.2 (2011-02-28)
972 - Fix typo in Ruby definition
973
974 1.1 (2011-02-26)
975 - Don't lose syntax highlighting when ':syntax enable' is called
976 - Allow expanding the Vim window when Tagbar is opened
977
978 1.0 (2011-02-23)
979 - Initial release
980
981 ==============================================================================
982 9. Todo *tagbar-todo*
983
984 - Allow filtering the Tagbar content by some criteria like tag name,
985 visibility, kind ...
986 - Integrate Tagbar with the FSwitch plugin to provide header file
987 information in C/C++.
988 - Allow jumping to a tag in the preview window, a split window or a new tab.
989
990 ==============================================================================
991 10. Credits *tagbar-credits*
992
993 Tagbar was written by Jan Larres and is released under the Vim licence, see
994 |license|. It was heavily inspired by the Taglist plugin by Yegappan
995 Lakshmanan and uses a small amount of code from it.
996
997 Original taglist copyright notice:
998 Permission is hereby granted to use and distribute this code, with or without
999 modifications, provided that this copyright notice is copied with it. Like
1000 anything else that's free, taglist.vim is provided *as is* and comes with no
1001 warranty of any kind, either expressed or implied. In no event will the
1002 copyright holder be liable for any damamges resulting from the use of this
1003 software.
1004
1005 The folding technique was inspired by NERDTree by Martin Grenfell.
1006
1007 Thanks to the following people for code contributions, feature suggestions etc:
1008 Jan Christoph Ebersbach
1009 Leandro Freitas
1010 Seth Milliken
1011 Kien N
1012 pielgrzym
1013 Taybin Rutkin
1014
1015 ==============================================================================
1016 vim: tw=78 ts=8 sw=8 sts=8 noet ft=help