]> git.r.bdr.sh - rbdr/dotfiles/blame_incremental - vim/doc/tagbar.txt
A whole bunch of new additions to the submodules
[rbdr/dotfiles] / vim / doc / tagbar.txt
... / ...
CommitLineData
1*tagbar.txt* Display tags of a file in their correct scope
2
3Author: Jan Larres <jan@majutsushi.net>
4Licence: Vim licence, see |license|
5Homepage: http://majutsushi.github.com/tagbar/
6Version: 2.3
7
8==============================================================================
9Contents *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==============================================================================
301. Intro *tagbar-intro*
31
32Tagbar is a plugin for browsing the tags of source code files. It provides a
33sidebar that displays the ctags-generated tags of the current file, ordered by
34their scope. This means that for example methods in C++ are displayed under
35the class they are defined in.
36
37Let'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<
52Then Tagbar would display the tag information like so:
53>
54 __anon1* : namespace
55 Foo : class
56 +Foo()
57 +~Foo()
58 -var
59 a
60<
61This example shows several important points. First, the tags are listed
62indented below the scope they are defined in. Second, the type of a scope is
63listed after its name and a colon. Third, tags for which the access/visibility
64information is known are prefixed with a symbol indicating that.
65
66------------------------------------------------------------------------------
67PSEUDO-TAGS *tagbar-pseudotags*
68
69The example also introduces the concept of "pseudo-tags". Pseudo-tags are tags
70that are not explicitly defined in the file but have children in it. In this
71example the namespace doesn't have a name and thus ctags doesn't generate a
72tag for it, but since it has children it still needs to be displayed using an
73auto-generated name.
74
75Another case where pseudo-tags appear is in C++ implementation files. Since
76classes are usually defined in a header file but the member methods and
77variables in the implementation file the class itself won't generate a tag
78in that file.
79
80Since pseudo-tags don't really exist they cannot be jumped to from the Tagbar
81window.
82
83Pseudo-tags are denoted with an asterisk ('*') at the end of their name.
84
85------------------------------------------------------------------------------
86SUPPORTED FEATURES *tagbar-features*
87
88The 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------------------------------------------------------------------------------
107OTHER CTAGS-COMPATIBLE PROGRAMS *tagbar-other*
108
109Tagbar theoretically also supports filetype-specific programs that can output
110tag information that is compatible with ctags. However due to potential
111incompatibilities this may not always completely work. Tagbar has been tested
112with doctorjs/jsctags and will use that if present, other programs require
113some configuration (see |tagbar-extend|). If a program does not work even with
114correct configuration please contact me.
115
116Note: Please check |tagbar-issues| for some possible issues with jsctags.
117
118==============================================================================
1192. Requirements *tagbar-requirements*
120
121The 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==============================================================================
1463. Installation *tagbar-installation*
147
148Use the normal Vimball install method for installing tagbar.vba:
149>
150 vim tagbar.vba
151 :so %
152 :q
153<
154Alternatively 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
156you're not using pathogen.
157
158If 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,
160see |g:tagbar_ctags_bin|.
161
162==============================================================================
1634. Usage *tagbar-usage*
164
165There 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
179Opening and closing the Tagbar window~
180Use |:TagbarOpen| or |:TagbarToggle| to open the Tagbar window if it is
181closed. 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
186It is probably a good idea to assign a key to these commands. For example, put
187this in your |vimrc|:
188>
189 nnoremap <silent> <F9> :TagbarToggle<CR>
190<
191You can then open and close Tagbar by simply pressing the <F9> key.
192
193You can also use |:TagbarOpenAutoClose| to open the Tagbar window, jump to it
194and have it close automatically on tag selection regardless of the
195|g:tagbar_autoclose| setting.
196
197Jumping to tags~
198When you're inside the Tagbar window you can jump to the definition of a tag
199by moving the cursor to a tag and pressing <Enter> or double-clicking on it
200with the mouse. The source file will then move to the definition and put the
201cursor in the corresponding line. This won't work for pseudo-tags.
202
203Sorting~
204You can sort the tags in the Tagbar window in two ways: by name or by file
205order. Sorting them by name simply displays the tags in their alphabetical
206order under their corresponding scope. Sorting by file order means that the
207tags keep the order they have in the source file, but are still associated
208with the correct scope. You can change the sort order by pressing the "s" key
209in the Tagbar window. The current sort order is displayed in the statusbar of
210the Tagbar window.
211
212Folding~
213The displayed scopes (and unscoped types) can be folded to hide uninteresting
214information. Mappings similar to Vim's built-in ones are provided. Folds can
215also be opened and closed by clicking on the fold icon with the mouse.
216
217Displaying the prototype of a tag~
218Tagbar can display the prototype of a tag. More precisely it can display the
219line in which the tag is defined. This can be done by either pressing <Space>
220when on a tag or hovering over a tag with the mouse. In the former case the
221prototype will be displayed in the command line |Command-line|, in the latter
222case it will be displayed in a pop-up window. The prototype will also be
223displayed when the cursor stays on a tag for 'updatetime' milliseconds.
224
225------------------------------------------------------------------------------
226COMMANDS *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------------------------------------------------------------------------------
272KEY MAPPINGS *tagbar-keys*
273
274The 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.
279p 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.
289o/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.
295s Toggle sort order between name and file order.
296x Toggle zooming the window.
297q Close the Tagbar window.
298
299==============================================================================
3005. Configuration *tagbar-configuration*
301
302 *g:tagbar_ctags_bin*
303g:tagbar_ctags_bin~
304Default: empty
305
306Use this option to specify the location of your ctags executable. Only needed
307if it is not in one of the directories in your $PATH environment variable.
308
309Example:
310>
311 let g:tagbar_ctags_bin = 'C:\Ctags5.8\ctags.exe'
312<
313
314 *g:tagbar_left*
315g:tagbar_left~
316Default: 0
317
318By default the Tagbar window will be opened on the right-hand side of vim. Set
319this option to open it on the left instead.
320
321Example:
322>
323 let g:tagbar_left = 1
324<
325
326 *g:tagbar_width*
327g:tagbar_width~
328Default: 40
329
330Width of the Tagbar window in characters.
331
332Example:
333>
334 let g:tagbar_width = 30
335<
336
337 *g:tagbar_autoclose*
338g:tagbar_autoclose~
339Default: 0
340
341If you set this option the Tagbar window will automatically close when you
342jump to a tag. This implies |g:tagbar_autofocus|.
343
344Example:
345>
346 let g:tagbar_autoclose = 1
347<
348
349 *g:tagbar_autofocus*
350g:tagbar_autofocus~
351Default: 0
352
353If you set this option the cursor will move to the Tagbar window when it is
354opened.
355
356Example:
357>
358 let g:tagbar_autofocus = 1
359<
360
361 *g:tagbar_sort*
362g:tagbar_sort~
363Default: 1
364
365If this option is set the tags are sorted according to their name. If it is
366unset they are sorted according to their order in the source file. Note that
367in the second case Pseudo-tags are always sorted before normal tags of the
368same kind since they don't have a real position in the file.
369
370Example:
371>
372 let g:tagbar_sort = 0
373<
374
375 *g:tagbar_compact*
376g:tagbar_compact~
377Default: 0
378
379Setting this option will result in Tagbar omitting the short help at the
380top of the window and the blank lines in between top-level scopes in order to
381save screen real estate.
382
383Example:
384>
385 let g:tagbar_compact = 1
386<
387
388 *g:tagbar_expand*
389g:tagbar_expand~
390Default: 0
391
392If this option is set the Vim window will be expanded by the width of the
393Tagbar window if using a GUI version of Vim.
394
395Example:
396>
397 let g:tagbar_expand = 1
398<
399
400 *g:tagbar_singleclick*
401g:tagbar_singleclick~
402Default: 0
403
404If this option is set then a single- instead of a double-click is used to jump
405to the tag definition.
406
407Example:
408>
409 let g:tagbar_singleclick = 1
410<
411
412 *g:tagbar_foldlevel*
413g:tagbar_foldlevel~
414Default: 99
415
416The initial foldlevel for folds in the Tagbar window. Fold with a level higher
417than this number will be closed.
418
419Example:
420>
421 let g:tagbar_foldlevel = 2
422<
423
424 *g:tagbar_iconchars*
425g:tagbar_iconchars~
426
427Since the display of the icons used to indicate open or closed folds depends
428on the actual font used, different characters may be optimal for different
429fonts. With this variable you can set the icons to characters of your liking.
430The first character in the list specifies the icon to use for a closed fold,
431and the second one for an open fold.
432
433Examples (don't worry if some the characters aren't displayed correctly, just
434choose 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*
443g:tagbar_autoshowtag~
444Default: 0
445
446If this variable is set and the current tag is inside of a closed fold then
447the folds will be opened as much as needed for the tag to be visible so it can
448be highlighted. If it is not set then the folds won't be opened and the parent
449tag will be highlighted instead. You can use the TagbarShowTag command to open
450the folds manually.
451
452Example:
453>
454 let g:tagbar_autoshowtag = 1
455<
456
457 *g:tagbar_updateonsave_maxlines*
458g:tagbar_updateonsave_maxlines~
459Default: 5000
460
461If the current file has fewer lines than the value of this variable, Tagbar
462will update immediately after saving the file. If it is longer then the update
463will only happen on the |CursorHold| event and when switching buffers (or
464windows). This is to prevent the time it takes to save a large file from
465becoming annoying in case you have a slow computer. If you have a fast
466computer you can set it to a higher value.
467
468Example:
469>
470 let g:tagbar_updateonsave_maxlines = 10000
471<
472
473 *g:tagbar_systemenc*
474g:tagbar_systemenc~
475Default: value of 'encoding'
476
477This variable is for cases where the character encoding of your operating
478system is different from the one set in Vim, i.e. the 'encoding' option. For
479example, if you use a Simplified Chinese Windows version that has a system
480encoding of "cp936", and you have set 'encoding' to "utf-8", then you would
481have to set this variable to "cp936".
482
483Example:
484>
485 let g:tagbar_systemenc = 'cp936'
486<
487
488------------------------------------------------------------------------------
489HIGHLIGHT COLOURS *tagbar-highlight*
490
491All of the colours used by Tagbar can be customized. Here is a list of the
492highlight groups that are defined by Tagbar:
493
494TagbarComment
495 The help at the top of the buffer.
496
497TagbarKind
498 The header of generic "kinds" like "functions" and "variables".
499
500TagbarNestedKind
501 The "kind" headers in square brackets inside of scopes.
502
503TagbarScope
504 Tags that define a scope like classes, structs etc.
505
506TagbarType
507 The type of a tag or scope if available.
508
509TagbarSignature
510 Function signatures.
511
512TagbarPseudoID
513 The asterisk (*) that signifies a pseudo-tag.
514
515TagbarFoldIcon
516 The fold icon on the left of foldable tags.
517
518TagbarHighlight
519 The colour that is used for automatically highlighting the current tag.
520
521TagbarAccessPublic
522 The "public" visibility/access symbol.
523
524TagbarAccessProtected
525 The "protected" visibility/access symbol.
526
527TagbarAccessPrivate
528 The "private" visibility/access symbol.
529
530If you want to change any of those colours put a line like the following in
531your vimrc:
532>
533 highlight TagbarScope guifg=Green ctermfg=Green
534<
535See |:highlight| for more information.
536
537------------------------------------------------------------------------------
538AUTOMATICALLY OPENING TAGBAR *tagbar-autoopen*
539
540Since there are several different situations in which you might want to open
541Tagbar automatically there is no single option to enable automatic opening.
542Instead, autocommands can be used together with a convenience function that
543opens Tagbar only if a supported file is open(ed).
544
545If you want to open Tagbar automatically on Vim startup no matter what put
546this into your vimrc:
547>
548 autocmd VimEnter * nested :TagbarOpen
549<
550If you want to open it only if you're opening Vim with a supported file/files
551use this instead:
552>
553 autocmd VimEnter * nested :call tagbar#autoopen()
554<
555For opening Tagbar also if you open a supported file in an already running
556Vim:
557>
558 autocmd FileType * nested :call tagbar#autoopen()
559<
560And if you only want to open Tagbar only for specific filetypes, not for all
561of the supported ones:
562>
563 autocmd FileType c,cpp nested :TagbarOpen
564<
565Check out |autocmd.txt| if you want it to open automatically in more
566complicated cases.
567
568==============================================================================
5696. Extending Tagbar *tagbar-extend*
570
571Tagbar has a flexible mechanism for extending the existing file type (i.e.
572language) definitions. This can be used both to change the settings of the
573existing types and to add completely new types. A complete configuration
574consists of a type definition for Tagbar in your |vimrc| and optionally a
575language definition for ctags in case you want to add a new language.
576
577Before writing your own extension have a look at the wiki
578(https://github.com/majutsushi/tagbar/wiki/Support-for-additional-filetypes)
579or try googling for existing ones. If you do end up creating your own
580extension please consider adding it to the wiki so that others will be able to
581use it, too.
582
583Every type definition in Tagbar is a dictionary with the following keys:
584
585ctagstype: 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.
589kinds: 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.
606sro: 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.
609kind2scope: 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.
631scope2kind: 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.
636replace: 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!
640sort: 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.
645deffile: 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<
660ctagsbin: 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).
666ctagsargs: 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
672You then have to assign this dictionary to a variable in your vimrc with the
673name
674>
675 g:tagbar_type_{vim filetype}
676<
677For example, for C++ the name would be "g:tagbar_type_cpp". If you don't know
678the vim file type then run the following command:
679>
680 :set filetype?
681<
682and vim will display the file type of the current buffer.
683
684Example: C++~
685Here is a complete example that shows the default configuration for C++ as
686used in Tagbar. This is just for illustration purposes since user
687configurations 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
723Which of the keys you have to specify depends on what you want to do.
724
725Changing an existing definition~
726If you want to change an existing definition you only need to specify the
727parts that you want to change. It probably only makes sense to change "kinds"
728and/or "scopes", which would be the case if you wanted to exclude certain
729kinds from appearing in Tagbar or if you want to change their order. As an
730example, if you didn't want Tagbar to show prototypes for C++ files and switch
731the 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<
749Compare with the complete example above to see the difference.
750
751Adding a definition for a new language/file type~
752In order to be able to add a new language to Tagbar you first have to create a
753configuration for ctags that it can use to parse the files. This can be done
754in 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
764For the first approach the only keys that are needed in the Tagbar definition
765are "ctagstype" and "kinds". A definition that supports scopes has to define
766those two and in addition "scopes", "sro" and at least one of "kind2scope" and
767"scope2kind".
768
769Let's assume we want to add support for LaTeX to Tagbar using the regex
770approach. First we put the following text into ~/.ctags or a file pointed to
771by 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<
796This will create a new language definition with the name "latex" and associate
797it with files with the extension ".tex". It will also define the kinds "s" for
798sections, chapters and the like, "g" for included graphics, "l" for labels,
799"r" for references and "p" for page references. See the ctags documentation
800for more information about the exact syntax.
801
802Now 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<
817The "deffile" field is of course only needed if the ctags definition actually
818is in that file and not in ~/.ctags.
819
820Sort has been disabled for LaTeX so that the sections appear in their correct
821order. They unfortunately can't be shown nested with their correct scopes
822since as already mentioned the regular expression approach doesn't support
823that.
824
825Tagbar should now be able to show the sections and other tags from LaTeX
826files.
827
828==============================================================================
8297. Troubleshooting & Known issues *tagbar-issues*
830
831As a general rule, if the tag information displayed by Tagbar is wrong (for
832example, a method doesn't show up or is in the wrong place) you should first
833try running ctags manually to see whether ctags reports the wrong information
834or whether that information is correct and Tagbar does something wrong. To run
835ctags manually execute the following command in a terminal:
836>
837 ctags -f - --format=2 --excmd=pattern --extra= --fields=nksaSmt myfile
838<
839If you set the |g:tagbar_ctags_bin| variable you probably have to use the same
840value here instead of simply "ctags".
841
842If Tagbar doesn't seem to work at all, but you don't get any error messages,
843you 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
845attention to the reported file type and the ctags command line in the log
846file.
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==============================================================================
8998. History *tagbar-history*
900
9012.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
9112.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
9282.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
9442.0.1 (2011-04-26)
945 - Fix sorting bug when 'ignorecase' is set
946
9472.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
9591.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
9711.2 (2011-02-28)
972 - Fix typo in Ruby definition
973
9741.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
9781.0 (2011-02-23)
979 - Initial release
980
981==============================================================================
9829. 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==============================================================================
99110. Credits *tagbar-credits*
992
993Tagbar 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
995Lakshmanan and uses a small amount of code from it.
996
997Original taglist copyright notice:
998Permission is hereby granted to use and distribute this code, with or without
999modifications, provided that this copyright notice is copied with it. Like
1000anything else that's free, taglist.vim is provided *as is* and comes with no
1001warranty of any kind, either expressed or implied. In no event will the
1002copyright holder be liable for any damamges resulting from the use of this
1003software.
1004
1005The folding technique was inspired by NERDTree by Martin Grenfell.
1006
1007Thanks to the following people for code contributions, feature suggestions etc:
1008Jan Christoph Ebersbach
1009Leandro Freitas
1010Seth Milliken
1011Kien N
1012pielgrzym
1013Taybin Rutkin
1014
1015==============================================================================
1016 vim: tw=78 ts=8 sw=8 sts=8 noet ft=help