-
-
Notifications
You must be signed in to change notification settings - Fork 485
/
tagbar.txt
1399 lines (1187 loc) · 59.9 KB
/
tagbar.txt
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
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*tagbar.txt* Display tags of a file ordered by scope
Author: Jan Larres <jan@majutsushi.net>
Licence: Vim licence, see |license|
Homepage: http://majutsushi.github.com/tagbar/
Version: 2.5
==============================================================================
Contents *tagbar* *tagbar-contents*
1. Intro ........................... |tagbar-intro|
Pseudo-tags ................... |tagbar-pseudotags|
Supported features ............ |tagbar-features|
Other ctags-compatible programs |tagbar-other|
2. Requirements .................... |tagbar-requirements|
3. Installation .................... |tagbar-installation|
4. Usage ........................... |tagbar-usage|
Commands ...................... |tagbar-commands|
Key mappings .................. |tagbar-keys|
5. Configuration ................... |tagbar-configuration|
Highlight colours ............. |tagbar-highlight|
Automatically opening Tagbar .. |tagbar-autoopen|
Show current tag in statusline |tagbar-statusline|
Ignoring specific files ....... |tagbar-ignore|
6. Extending Tagbar ................ |tagbar-extend|
7. Troubleshooting & Known issues .. |tagbar-issues|
8. History ......................... |tagbar-history|
9. Todo ............................ |tagbar-todo|
10. Credits ......................... |tagbar-credits|
==============================================================================
1. Intro *tagbar-intro*
Tagbar is a plugin for browsing the tags of source code files. It provides a
sidebar that displays the ctags-generated tags of the current file, ordered by
their scope. This means that for example methods in C++ are displayed under
the class they are defined in.
Let's say we have the following code inside of a C++ file:
>
namespace {
char a;
class Foo
{
public:
Foo();
~Foo();
private:
int var;
};
};
<
Then Tagbar would display the tag information like so:
>
__anon1* : namespace
Foo : class
+Foo()
+~Foo()
-var
a
<
This example shows several important points. First, the tags are listed
indented below the scope they are defined in. Second, the type of a scope is
listed after its name and a colon. Third, tags for which the visibility
information is known are prefixed with a symbol indicating that.
------------------------------------------------------------------------------
PSEUDO-TAGS *tagbar-pseudotags*
The example also introduces the concept of "pseudo-tags". Pseudo-tags are tags
that are not explicitly defined in the file but have children in it. In this
example the namespace doesn't have a name and thus ctags doesn't generate a
tag for it, but since it has children it still needs to be displayed using an
auto-generated name.
Another case where pseudo-tags appear is in C++ implementation files. Since
classes are usually defined in a header file but the member methods and
variables in the implementation file the class itself won't generate a tag
in that file.
Since pseudo-tags don't really exist they cannot be jumped to from the Tagbar
window.
Pseudo-tags are denoted with an asterisk ('*') at the end of their name.
------------------------------------------------------------------------------
SUPPORTED FEATURES *tagbar-features*
The following features are supported by Tagbar:
- Display tags under their correct scope.
- Automatically update the tags when switching between buffers and editing
files.
- Display visibility information of tags if available.
- Highlight the tag near the cursor while editing files.
- Jump to a tag from the Tagbar window.
- Display the complete prototype of a tag.
- Tags can be sorted either by name or order of appearance in the file.
- Scopes can be folded to hide uninteresting information.
- Supports all of the languages that ctags does, i.e. Ant, Assembler, ASP,
Awk, Basic, BETA, C, C++, C#, COBOL, DosBatch, Eiffel, Erlang, Flex,
Fortran, HTML, Java, JavaScript, Lisp, Lua, Make, MatLab, OCaml, Pascal,
Perl, PHP, Python, REXX, Ruby, Scheme, Shell script, SLang, SML, SQL, Tcl,
Tex, Vera, Verilog, VHDL, Vim and YACC.
- Can be extended to support arbitrary new types.
------------------------------------------------------------------------------
OTHER CTAGS-COMPATIBLE PROGRAMS *tagbar-other*
Tagbar theoretically also supports filetype-specific programs that can output
tag information that is compatible with ctags. However due to potential
incompatibilities this may not always completely work. Tagbar has been tested
with doctorjs/jsctags and will use that if present, other programs require
some configuration (see |tagbar-extend|). If a program does not work even with
correct configuration please contact me.
Note: Please check |tagbar-issues| for some possible issues with jsctags.
==============================================================================
2. Requirements *tagbar-requirements*
The following requirements have to be met in order to be able to use tagbar:
- Vim 7.0 or higher. Older versions will not work since Tagbar uses data
structures that were only introduced in Vim 7.
- Exuberant ctags 5.5 or higher. Ctags is the program that generates the
tag information that Tagbar uses. It is shipped with most Linux
distributions, otherwise it can be downloaded from the following
website:
http://ctags.sourceforge.net/
Tagbar will work on any platform that ctags runs on -- this includes
UNIX derivatives, Mac OS X and Windows. Note that other versions like
GNU ctags will not work.
Tagbar generates the tag information by itself and doesn't need (or use)
already existing tag files.
- File type detection must be turned on in vim. This can be done with the
following command in your vimrc:
>
filetype on
<
See |filetype| for more information.
- Tagbar will not work in |restricted-mode| or with 'compatible' set.
==============================================================================
3. Installation *tagbar-installation*
Use the normal Vimball install method for installing tagbar.vba:
>
vim tagbar.vba
:so %
:q
<
Alternatively you can clone the git repository and then add the path to
'runtimepath' or use the pathogen plugin. Don't forget to run |:helptags|.
If the ctags executable is not installed in one of the directories in your
$PATH environment variable you have to set the g:tagbar_ctags_bin variable,
see |g:tagbar_ctags_bin|.
==============================================================================
4. Usage *tagbar-usage*
There are essentially two ways to use Tagbar:
1. Have it running all the time in a window on the side of the screen. In
this case Tagbar will update its contents whenever the source file is
changed and highlight the tag the cursor is currently on in the file. If
a tag is selected in Tagbar the file window will jump to the tag and the
Tagbar window will stay open. |g:tagbar_autoclose| has to be unset for
this mode.
2. Only open Tagbar when you want to jump to a specific tag and have it
close automatically once you have selected one. This can be useful for
example for small screens where a permanent window would take up too much
space. You have to set the option |g:tagbar_autoclose| in this case. The
cursor will also automatically jump to the Tagbar window when opening it.
Opening and closing the Tagbar window~
Use |:TagbarOpen| or |:TagbarToggle| to open the Tagbar window if it is
closed. By default the window is opened on the right side, set the option
|g:tagbar_left| to open it on the left instead. If the window is already open,
|:TagbarOpen| will jump to it and |:TagbarToggle| will close it again.
|:TagbarClose| will simply close the window if it is open.
It is probably a good idea to assign a key to these commands. For example, put
this into your |vimrc|:
>
nnoremap <silent> <F9> :TagbarToggle<CR>
<
You can then open and close Tagbar by simply pressing the <F9> key.
You can also use |:TagbarOpenAutoClose| to open the Tagbar window, jump to it
and have it close automatically on tag selection regardless of the
|g:tagbar_autoclose| setting.
Pausing the Tagbar window~
Use |:TagbarTogglePause| to toggle freezing the Tagbar window on its currently
displayed file. Freezing the window stops the Tagbar contents from changing
when switching to a different source file. All Tagbar functionality continues
to work as expected. Unfreezing the window will cause it to load the current
source file.
Jumping to tags~
When you're inside the Tagbar window you can jump to the definition of a tag
by moving the cursor to a tag and pressing <Enter> or double-clicking on it
with the mouse. The source file will then move to the definition and put the
cursor in the corresponding line. This won't work for pseudo-tags.
Sorting~
You can sort the tags in the Tagbar window in two ways: by name or by file
order. Sorting them by name simply displays the tags in their alphabetical
order under their corresponding scope. Sorting by file order means that the
tags keep the order they have in the source file, but are still associated
with the correct scope. You can change the sort order by pressing the "s" key
in the Tagbar window. The current sort order is displayed in the statusline of
the Tagbar window.
Folding~
The displayed scopes (and unscoped types) can be folded to hide uninteresting
information. Mappings similar to Vim's built-in ones are provided. Folds can
also be opened and closed by clicking on the fold icon with the mouse.
Highlighting the current tag~
When the Tagbar window is open the current tag will automatically be
highlighted in it after a short pause if the cursor is not moving. The length
of this pause is determined by the 'updatetime' option. If you want to make
that pause shorter you can change the option, but don't set it too low or
strange things will happen. This is unfortunately unavoidable.
Displaying the prototype of a tag~
Tagbar can display the prototype of a tag. More precisely it can display the
line(s) in which the tag is defined. This can be done by either pressing
<Space> when on a tag or hovering over a tag with the mouse. In the former
case the prototype will be displayed in the |Command-line|, in the latter case
it will be displayed in a pop-up window. The prototype will also be displayed
if the cursor stays on a tag for 'updatetime' milliseconds. In that case the
prototype may be abbreviated in order to avoid |hit-enter| prompts.
------------------------------------------------------------------------------
COMMANDS *tagbar-commands*
:TagbarOpen [{flags}] *:TagbarOpen*
Open the Tagbar window if it is closed.
Additional behaviour can be specified with the optional {flags} argument.
It is a string which can contain these character flags:
'f' Jump to Tagbar window when opening (just as if |g:tagbar_autofocus|
were set to 1)
'j' Jump to Tagbar window if already open
'c' Close Tagbar on tag selection (just as if |g:tagbar_autoclose| were
set to 1, but doesn't imply 'f'), but only if the Tagbar window was
opened using this command.
For example, the following command would always jump to the Tagbar window,
opening it first if necessary, but keep it open after selecting a tag
(unless |g:tagbar_autoclose| is set): >
:TagbarOpen fj
<
:TagbarClose *:TagbarClose*
Close the Tagbar window if it is open.
:TagbarToggle *:TagbarToggle*
:Tagbar
Open the Tagbar window if it is closed, or close it if it is open.
:TagbarOpenAutoClose *:TagbarOpenAutoClose*
Open the Tagbar window, jump to it and close it on tag selection. This is
an alias for ":TagbarOpen fjc".
:TagbarTogglePause *:TagbarTogglePause*
Freezes/Unfreezes the Tagbar window. Stops the contents of the window
from changing when a different source file is selected.
:TagbarSetFoldlevel[!] {number} *:TagbarSetFoldlevel*
Set the foldlevel of the tags of the current file to {number}. The
foldlevel of tags in other files remains unaffected. Works in the same way
as 'foldlevel'. Folds that are specified to be closed by default in the
type configuration will not be opened, use a "!" to force applying the new
foldlevel to those folds as well.
:TagbarShowTag *:TagbarShowTag*
Open the parent folds of the current tag in the file window as much as
needed for the tag to be visible in the Tagbar window.
:TagbarCurrentTag [{flags}] *:TagbarCurrentTag*
Echo the current tag in the command line. For {flags} see
|tagbar-statusline|.
:TagbarGetTypeConfig {filetype} *:TagbarGetTypeConfig*
Paste the Tagbar configuration of the vim filetype {filetype} at the
current cursor position (provided that filetype is supported by Tagbar)
for easy customization. The configuration will be ready to use as is but
will only contain the "kinds" entry as that is the only one that really
makes sense to customize. See |tagbar-extend| for more information about
type configurations.
:TagbarDebug [logfile] *:TagbarDebug*
Start debug mode. This will write debug messages to file [logfile] while
using Tagbar. If no argument is given "tagbardebug.log" in the current
directory is used. Note: an existing file will be overwritten!
Note also that it is usually necessary to call this command before loading
a file that creates problems in order to get all of the needed data.
:TagbarDebugEnd *:TagbarDebugEnd*
End debug mode, debug messages will no longer be written to the logfile.
------------------------------------------------------------------------------
KEY MAPPINGS *tagbar-keys*
The following mappings are valid in the Tagbar window:
<F1> Display key mapping help.
Map option: tagbar_map_help
<CR>/<Enter> Jump to the tag under the cursor. Doesn't work for pseudo-tags
or generic headers.
Map option: tagbar_map_jump
p Jump to the tag under the cursor, but stay in the Tagbar window.
Map option: tagbar_map_preview
P Open the tag in a |preview-window|.
Map option: tagbar_map_previewwin
<LeftMouse> When on a fold icon, open or close the fold depending on the
current state.
<2-LeftMouse> Same as <CR>. See |g:tagbar_singleclick| if you want to use a
single- instead of a double-click.
<C-N> Go to the next top-level tag.
Map option: tagbar_map_nexttag
<C-P> Go to the previous top-level tag.
Map option: tagbar_map_prevtag
<Space> Display the prototype of the current tag (i.e. the line defining
it) in the command line.
Map option: tagbar_map_showproto
+/zo Open the fold under the cursor.
Map option: tagbar_map_openfold
-/zc Close the fold under the cursor or the current one if there is
no fold under the cursor.
Map option: tagbar_map_closefold
o/za Toggle the fold under the cursor or the current one if there is
no fold under the cursor.
Map option: tagbar_map_togglefold
*/zR Open all folds by setting foldlevel to 99.
Map option: tagbar_map_openallfolds
=/zM Close all folds by setting foldlevel to 0.
Map option: tagbar_map_closeallfolds
s Toggle sort order between name and file order.
Map option: tagbar_map_togglesort
x Toggle zooming the window.
Map option: tagbar_map_zoomwin
q Close the Tagbar window.
Map option: tagbar_map_close
These mappings can be redefined with the given map options. The argument can
be either a string or a |List| of strings. In the latter case the
functionality will be assigned to all of the keys in the list. For example, if
you want to remap the sort toggling functionality to "r":
>
let g:tagbar_map_togglesort = "r"
<
See |key-notation| for how to write special keys like <Space> or the keypad
keys.
==============================================================================
5. Configuration *tagbar-configuration*
*g:tagbar_ctags_bin*
g:tagbar_ctags_bin~
Default: empty
Use this option to specify the location of your ctags executable. Only needed
if it is not in one of the directories in your $PATH environment variable.
Example:
>
let g:tagbar_ctags_bin = 'C:\Ctags5.8\ctags.exe'
<
*g:tagbar_left*
g:tagbar_left~
Default: 0
By default the Tagbar window will be opened on the right-hand side of vim. Set
this option to open it on the left instead.
Example:
>
let g:tagbar_left = 1
<
*g:tagbar_width*
g:tagbar_width~
Default: 40
Width of the Tagbar window in characters.
Example:
>
let g:tagbar_width = 30
<
*g:tagbar_autoclose*
g:tagbar_autoclose~
Default: 0
If you set this option the Tagbar window will automatically close when you
jump to a tag. This implies |g:tagbar_autofocus|.
Example:
>
let g:tagbar_autoclose = 1
<
*g:tagbar_autofocus*
g:tagbar_autofocus~
Default: 0
If you set this option the cursor will move to the Tagbar window when it is
opened.
Example:
>
let g:tagbar_autofocus = 1
<
*g:tagbar_sort*
g:tagbar_sort~
Default: 1
If this option is set the tags are sorted according to their name. If it is
unset they are sorted according to their order in the source file. Note that
in the second case Pseudo-tags are always sorted before normal tags of the
same kind since they don't have a real position in the file.
Example:
>
let g:tagbar_sort = 0
<
*g:tagbar_compact*
g:tagbar_compact~
Default: 0
Setting this option will result in Tagbar omitting the short help at the
top of the window and the blank lines in between top-level scopes in order to
save screen real estate.
Example:
>
let g:tagbar_compact = 1
<
*g:tagbar_indent*
g:tagbar_indent~
Default: 2
The number of spaces by which each level is indented. This allows making the
display more compact or more spacious.
Example:
>
let g:tagbar_indent = 1
<
*g:tagbar_show_visibility*
g:tagbar_show_visibility~
Default: 1
Show the visibility symbols (public/protected/private) to the left of the tag
name.
Example:
>
let g:tagbar_show_visibility = 0
<
*g:tagbar_show_linenumbers*
g:tagbar_show_linenumbers~
Default: 0
Whether line numbers should be shown in the Tagbar window.
Possible values are:
0: Don't show any line numbers.
1: Show absolute line numbers.
2: Show relative line numbers.
-1: Use the global line number settings.
Example:
>
let g:tagbar_show_linenumbers = 2
<
*g:tagbar_expand*
g:tagbar_expand~
Default: 0
If this option is set to 1 the Vim window will be expanded by the width of the
Tagbar window if using a GUI version of Vim. Setting it to 2 will also try
expanding a terminal, but note that this is not supported by all terminals.
See also |xterm-resize|.
Example:
>
let g:tagbar_expand = 1
<
*g:tagbar_singleclick*
g:tagbar_singleclick~
Default: 0
If this option is set then a single- instead of a double-click is used to jump
to the tag definition.
Example:
>
let g:tagbar_singleclick = 1
<
*g:tagbar_foldlevel*
g:tagbar_foldlevel~
Default: 99
The initial foldlevel for folds in the Tagbar window. Folds with a level
higher than this number will be closed.
Example:
>
let g:tagbar_foldlevel = 2
<
*g:tagbar_iconchars*
g:tagbar_iconchars~
Since the display of the icons used to indicate open or closed folds depends
on the actual font used, different characters may be optimal for different
fonts. With this variable you can set the icons to characters of your liking.
The first character in the list specifies the icon to use for a closed fold,
and the second one for an open fold.
Examples (don't worry if some of the characters aren't displayed correctly,
just choose other characters in that case):
>
let g:tagbar_iconchars = ['▶', '▼'] (default on Linux and Mac OS X)
let g:tagbar_iconchars = ['▸', '▾']
let g:tagbar_iconchars = ['▷', '◢']
let g:tagbar_iconchars = ['+', '-'] (default on Windows)
<
*g:tagbar_autoshowtag*
g:tagbar_autoshowtag~
Default: 0
If this variable is set to 1 and the current tag is inside of a closed fold
then the folds will be opened as much as needed for the tag to be visible so
it can be highlighted. If it is set to 0 then the folds will only be opened
when opening the Tagbar window and the current tag is insided a closed fold,
otherwise the folds won't be opened and the parent tag will be highlighted
instead. If it is set to 2 then the folds will never be opened automatically.
You can use the |:TagbarShowTag| command to open the folds manually.
Example:
>
let g:tagbar_autoshowtag = 1
<
*g:tagbar_previewwin_pos*
g:tagbar_previewwin_pos~
Default: topleft
The position of the preview window. Valid values are the window splitting
commands that are described starting from |:vertical|. Set it to an empty
string to use the options 'splitbelow' and 'splitright'.
Example:
>
let g:tagbar_previewwin_pos = "aboveleft"
<
If you want to disable line numbers in the preview window put something like
this into your vimrc:
>
autocmd BufWinEnter * if &previewwindow | setlocal nonumber | endif
<
*g:tagbar_autopreview*
g:tagbar_autopreview~
Default: 0
If this variable is set to 1 then moving the cursor in the Tagbar window will
automatically show the current tag in the preview window.
Example:
>
let g:tagbar_autopreview = 1
<
*g:tagbar_updateonsave_maxlines*
g:tagbar_updateonsave_maxlines~
Deprecated. Tagbar will now always get updated when the file is being saved.
*g:tagbar_systemenc*
g:tagbar_systemenc~
Default: value of 'encoding'
This variable is for cases where the character encoding of your operating
system is different from the one set in Vim, i.e. the 'encoding' option. For
example, if you use a Simplified Chinese Windows version that has a system
encoding of "cp936", and you have set 'encoding' to "utf-8", then you would
have to set this variable to "cp936".
Note that this requires Vim to be compiled with the |+multi_byte| and (unless
your encoding is latin1) |+iconv| features to work.
Example:
>
let g:tagbar_systemenc = 'cp936'
<
*g:tagbar_status_func*
g:tagbar_status_func~
Default: undefined
This is the name of a function whose return value will be used to draw the
statusline of the Tagbar window.
The function has to take three arguments:
1. current: Whether Tagbar is the current window; 0 or 1.
2. sort: The sort order of the tags; 'Name' if they are sorted by name and
'Order' if they are sorted by their order of appearance in the file.
3. fname: The name of the file that the tags belong to.
In order to avoid possible future additions to the arguments resulting in an
error it is recommended to add an additional vararg to the signature (see
|a:0|).
Here is an example that, when put into your vimrc, will emulate Tagbar's
default statusline:
>
function! TagbarStatusFunc(current, sort, fname, ...) abort
let colour = a:current ? '%#StatusLine#' : '%#StatusLineNC#'
return colour . '[' . a:sort . '] ' . a:fname
endfunction
let g:tagbar_status_func = 'TagbarStatusFunc'
<
------------------------------------------------------------------------------
HIGHLIGHT COLOURS *tagbar-highlight*
All of the colours used by Tagbar can be customized. Here is a list of the
highlight groups that are defined by Tagbar:
TagbarComment
The help at the top of the buffer.
TagbarKind
The header of generic "kinds" like "functions" and "variables".
TagbarNestedKind
The "kind" headers in square brackets inside of scopes.
TagbarScope
Tags that define a scope like classes, structs etc.
TagbarType
The type of a tag or scope if available.
TagbarSignature
Function signatures.
TagbarPseudoID
The asterisk (*) that signifies a pseudo-tag.
TagbarFoldIcon
The fold icon on the left of foldable tags.
TagbarHighlight
The colour that is used for automatically highlighting the current tag.
TagbarVisibilityPublic
The "public" visibility symbol.
TagbarVisibilityProtected
The "protected" visibility symbol.
TagbarVisibilityPrivate
The "private" visibility symbol.
If you want to change any of those colours put a line like the following in
your vimrc:
>
highlight TagbarScope guifg=Green ctermfg=Green
<
See |:highlight| for more information.
------------------------------------------------------------------------------
AUTOMATICALLY OPENING TAGBAR *tagbar-autoopen*
Since there are several different situations in which you might want to open
Tagbar automatically there is no single option to enable automatic opening.
Instead, autocommands can be used together with a convenience function that
opens Tagbar only if a supported file is open(ed). It has a boolean parameter
that specifies whether Tagbar should be opened if any loaded buffer is
supported (in case the parameter is set to true) or only if a supported
file/buffer is currently being shown in a window. This can be useful if you
use multiple tabs and don't edit supported files in all of them.
If you want to open Tagbar automatically on Vim startup no matter what put
this into your vimrc:
>
autocmd VimEnter * nested :TagbarOpen
<
If you want to open it only if you're opening Vim with a supported file/files
use this instead:
>
autocmd VimEnter * nested :call tagbar#autoopen(1)
<
The above is exactly what the Taglist plugin does if you set the
Tlist_Auto_Open option, in case you want to emulate this behaviour.
For opening Tagbar also if you open a supported file in an already running
Vim:
>
autocmd FileType * nested :call tagbar#autoopen(0)
<
If you use multiple tabs and want Tagbar to also open in the current tab when
you switch to an already loaded, supported buffer:
>
autocmd BufEnter * nested :call tagbar#autoopen(0)
<
And if you want to open Tagbar only for specific filetypes, not for all of the
supported ones:
>
autocmd FileType c,cpp nested :TagbarOpen
<
Check out |autocmd.txt| if you want it to open automatically in more
complicated cases.
------------------------------------------------------------------------------
SHOWING THE CURRENT TAG IN THE STATUSLINE *tagbar-statusline*
You can show the current tag in the 'statusline', or in any other place that
you want to, by calling the tagbar#currenttag() function. The current tag is
exactly the same as would be highlighted in the Tagbar window if it is open.
It is defined as the nearest tag upwards in the file starting from the cursor
position. This means that for example in a function it should usually be the
name of the function. You can define which tags will be shown in this manner,
read |tagbar-extend| (especially the "kinds" entry) on how to do that.
The function has the following signature:
tagbar#currenttag({format}, {default} [, {flags}])
{format} is a |printf()|-compatible format string where "%s" will be
replaced by the name of the tag. {default} will be displayed instead of
the format string if no tag can be found.
The optional {flags} argument specifies some additional properties of the
displayed tags. It is a string which can contain these character flags:
'f' Display the full hierarchy of the tag, not just the tag itself.
's' If the tag is a function, the complete signature will be shown,
otherwise just "()" will be appended to distinguish functions from
other tags.
'p' Display the raw prototype instead of the parsed tag. This can be
useful in cases where ctags doesn't report some information, like
the signature. Note that this can get quite long.
For example, if you put the following into your statusline: >
%{tagbar#currenttag('[%s] ','')}
< then the function "myfunc" will be shown as "[myfunc()] ".
Note that if there is an error when processing the current file no error
message will be shown in order to not disrupt the statusline. If the function
doesn't seem to work right open the Tagbar window to see any error messages.
------------------------------------------------------------------------------
IGNORING SPECIFIC FILES *tagbar-ignore*
You can ignore specific files by setting the |buffer-variable|
"b:tagbar_ignore" to 1. This is best done with an |autocommand|:
>
autocmd BufNewFile,BufReadPost foo.cpp let b:tagbar_ignore = 1
<
Note that autocommands are order-sensitive, so make sure that this autocommand
gets defined before the ones that Tagbar defines so the variable will get
found at the right time.
==============================================================================
6. Extending Tagbar *tagbar-extend*
Tagbar has a flexible mechanism for extending the existing file type (i.e.
language) definitions. This can be used both to change the settings of the
existing types and to add completely new types. For Tagbar to support a
filetype two things are needed: a program that generates the tag information,
usually Exuberant Ctags, and a Tagbar type definition in your |vimrc| or an
|ftplugin| that tells Tagbar how to interpret the generated tags.
Note: if you only want to customize an existing definition (like changing the
order in which tag kinds are displayed) see "Changing an existing definition"
below.
There are two ways to generate the tag information for new filetypes: add a
definition to Exuberant Ctags or create a specialized program for your
language that generates ctags-compatible tag information (see
|tags-file-format| for information about how a "tags" file is structured). The
former allows simple regular expression-based parsing that is easy to get
started with, but doesn't support scopes unless you instead want to write a
C-based parser module for Exuberant Ctags. The regex approach is described in
more detail below.
Writing your own program is the approach used by for example jsctags and can
be useful if your language can best be parsed by a program written in the
language itself, or if you want to provide the program as part of a complete
support package for the language. Some tips on how to write such a program are
given at the end of this section.
Before writing your own extension have a look at the wiki
(https://github.com/majutsushi/tagbar/wiki) or try googling for existing ones.
If you do end up creating your own extension please consider adding it to the
wiki so that others can benefit from it, too.
Every type definition in Tagbar is a dictionary with the following keys:
ctagstype: The name of the language as recognized by ctags. Use the command >
ctags --list-languages
< to get a list of the languages ctags supports. The case doesn't
matter.
kinds: A list of the "language kinds" that should be listed in Tagbar,
ordered by the order they should appear in in the Tagbar window.
Use the command >
ctags --list-kinds={language name}
< to get a list of the kinds ctags supports for a given language. An
entry in this list is a colon-separated string with the following
syntax: >
{short}:{long}[:{fold}[:{stl}]]
< {short} is the one-character abbreviation that ctags uses, and
{long} is an arbitrary string that will be used in Tagbar as the
header for the the tags of this kind that are not listed under a
specific scope. {fold} determines whether tags of this kind should
be folded by default, with 1 meaning they should be folded and 0
they should not. If this part is omitted the tags will not be
folded by default. {stl} is used by the tagbar#currenttag()
function (see |tagbar-statusline|) to decide whether tags of this
kind should be shown in the statusline or not, with 1 meaning they
will be shown and 0 meaning they will be ignored. Omitting this
part means that the tags will be shown. Note that you have to
specify {fold} too if you want to specify {stl}.
For example, the string >
"f:functions:1"
< would list all the function definitions in a file under the header
"functions", fold them, and implicitly show them in the statusline
if tagbar#currenttag() is used.
sro: The scope resolution operator. For example, in C++ it is "::" and
in Java it is ".". If in doubt run ctags as shown below and check
the output.
kind2scope: A dictionary describing the mapping of tag kinds (in their
one-character representation) to the scopes their children will
appear in, for example classes, structs etc.
Unfortunately there is no ctags option to list the scopes, you
have to look at the tags ctags generates manually. For example,
let's say we have a C++ file "test.cpp" with the following
contents: >
class Foo
{
public:
Foo();
~Foo();
private:
int var;
};
< We then run ctags in the following way: >
ctags -f - --format=2 --excmd=pattern --extra= --fields=nksaSmt test.cpp
< Then the output for the variable "var" would look like this: >
var tmp.cpp /^ int var;$/;" kind:m line:11 class:Foo access:private
< This shows that the scope name for an entry in a C++ class is
simply "class". So this would be the word that the "kind"
character of a class has to be mapped to.
scope2kind: The opposite of the above, mapping scopes to the kinds of their
parents. Most of the time it is the exact inverse of the above,
but in some cases it can be different, for example when more than
one kind maps to the same scope. If it is the exact inverse for
your language you only need to specify one of the two keys.
replace: If you set this entry to 1 your definition will completely replace
{optional} an existing default definition. This is useful if you want to
disable scopes for a file type for some reason. Note that in this
case you have to provide all the needed entries yourself!
sort: This entry can be used to override the global sort setting for
{optional} this specific file type. The meaning of the value is the same as
with the global setting, that is if you want to sort tags by name
set it to 1 and if you want to sort them according to their order
in the file set it to 0.
deffile: The path to a file with additional ctags definitions (see the
{optional} section below on adding a new definition for what exactly that
means). This is especially useful for ftplugins since they can
provide a complete type definition with ctags and Tagbar
configurations without requiring user intervention.
Let's say you have an ftplugin that adds support for the language
"mylang", and your directory structure looks like this: >
ctags/mylang.cnf
ftplugin/mylang.vim
< Then the "deffile" entry would look like this to allow for the
plugin to be installed in an arbitray location (for example
with pathogen): >
'deffile' : expand('<sfile>:p:h:h') . '/ctags/mylang.cnf'
<
ctagsbin: The path to a filetype-specific ctags-compatible program like
{optional} jsctags. Set it in the same way as |g:tagbar_ctags_bin|. jsctags is
used automatically if found in your $PATH and does not have to be
set in that case. If it is not in your path you have to set this
key, the rest of the configuration should not be necessary (unless
you want to change something, of course). Note: if you use this
then the "ctagstype" key is not needed.
ctagsargs: The arguments to be passed to the filetype-specific ctags program
{optional} (without the filename). Make sure you set an option that makes the
program output its data on stdout. Not used for the normal ctags
program.
The value of ctagsargs may be a |List| of strings (a string for
each argument), or a single string (|expr-string|) of all the
arguments.
When the value of ctagsargs is a list, tagbar.vim takes care of
escaping each argument in the list as required for the current
'shell' type.
When the value of ctagsargs is a string, it must be properly
escaped (if required by the current shell type). The reason
tagbar.vim does not attempt to escape the string in this case is
because if there is a space, it is ambiguous as to whether the
space is delimiting an argument or included in the argument. To
avoid this amiguity, tagbar.vim expects the string to be already
escaped as required.
If special escaping is required for different OS shell types or if
in doubt, then it is recommended to define ctagsargs with a List.
You then have to assign this dictionary to a variable in your vimrc with the
name
>
g:tagbar_type_{vim filetype}
<
For example, for C++ the name would be "g:tagbar_type_cpp". If you don't know
the vim file type then run the following command:
>
:set filetype?
<
and vim will display the file type of the current buffer.
Example: C++~
Here is a complete example that shows the default configuration for C++ as
used in Tagbar. This is just for illustration purposes since user
configurations will usually be less complicated.
>
let g:tagbar_type_cpp = {
\ 'ctagstype' : 'c++',
\ 'kinds' : [
\ 'd:macros:1:0',
\ 'p:prototypes:1:0',
\ 'g:enums',
\ 'e:enumerators:0:0',
\ 't:typedefs:0:0',
\ 'n:namespaces',
\ 'c:classes',
\ 's:structs',
\ 'u:unions',
\ 'f:functions',
\ 'm:members:0:0',
\ 'v:variables:0:0'
\ ],
\ 'sro' : '::',
\ 'kind2scope' : {
\ 'g' : 'enum',
\ 'n' : 'namespace',
\ 'c' : 'class',
\ 's' : 'struct',
\ 'u' : 'union'
\ },
\ 'scope2kind' : {
\ 'enum' : 'g',
\ 'namespace' : 'n',
\ 'class' : 'c',
\ 'struct' : 's',
\ 'union' : 'u'
\ }
\ }
<
Which of the keys you have to specify depends on what you want to do.
Changing an existing definition~
If you want to change an existing definition you only need to specify the
parts that you want to change. It probably only makes sense to change "kinds",
which would be the case if you wanted to for example change the order of
certain kinds, change their default fold state or exclude them from appearing
in Tagbar. The easiest way to do that is to use the |:TagbarGetTypeConfig|
command, which will paste a ready-to-use configuration with the "kinds" entry
for the specified type at the current cursor position.
As an example, if you didn't want Tagbar to show prototypes for C++ files,
switch the order of enums and typedefs, and show macros in the statusline, you