tagbar/doc/tagbar.txt

*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.4.1

==============================================================================
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|
         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 access/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.

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 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 |Command-line|, in the latter
case it will be displayed in a pop-up window. The prototype will also be
displayed when the cursor stays on a tag for 'updatetime' milliseconds.

------------------------------------------------------------------------------
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*
    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".

: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.

: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!

: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.
<CR>/<Enter>  Jump to the tag under the cursor. Doesn't work for pseudo-tags
              or generic headers.
p             Jump to the tag under the cursor, but stay in the Tagbar window.
<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.
<Space>       Display the prototype of the current tag (i.e. the line defining
              it) in the command line.
+/zo          Open the fold under the cursor.
-/zc          Close the fold under the cursor or the current one if there is
              no fold under the cursor.
o/za          Toggle the fold under the cursor or the current one if there is
              no fold under the cursor.
*/zR          Open all folds by setting foldlevel to 99.
=/zM          Close all folds by setting foldlevel to 0.
<C-N>         Go to the next top-level tag.
<C-P>         Go to the previous top-level tag.
s             Toggle sort order between name and file order.
x             Toggle zooming the window.
q             Close the Tagbar window.

==============================================================================
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_expand*
g:tagbar_expand~
Default: 0

If this option is set the Vim window will be expanded by the width of the
Tagbar window if using a GUI version of Vim.

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 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 not set then the folds won't be opened and the parent
tag will be highlighted instead. You can use the |:TagbarShowTag| command to
open the folds manually.

Example:
>
        let g:tagbar_autoshowtag = 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'
<

------------------------------------------------------------------------------
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.

TagbarAccessPublic
    The "public" visibility/access symbol.

TagbarAccessProtected
    The "protected" visibility/access symbol.

TagbarAccessPrivate
    The "private" visibility/access 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.

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.

    For example, if you put the following into your statusline: >
        %{tagbar#currenttag('[%s] ', '')}
<   then the function "myfunc" will be show as "[myfunc()] ".

==============================================================================
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/Support-for-additional-filetypes)
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 will be able to
use 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.


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
would first run ":TagbarGetTypeConfig cpp" in your vimrc and then change the
definition like this:
>
        let g:tagbar_type_cpp = {
            \ 'kinds' : [
                \ 'd:macros:1',
                \ 'g:enums',
                \ 't:typedefs:0:0',
                \ 'e:enumerators:0:0',
                \ 'n:namespaces',
                \ 'c:classes',
                \ 's:structs',
                \ 'u:unions',
                \ 'f:functions',
                \ 'm:members:0:0',
                \ 'v:variables:0:0'
            \ ]
        \ }
<
Compare with the complete example above to see the difference.

Adding a definition for a new language/file type~
In order to be able to add a new language to Tagbar you first have to create a
configuration for ctags that it can use to parse the files. This can be done
in two ways:

  1. Use the --regex argument for specifying regular expressions that are used
     to parse the files. An example of this is given below. A disadvantage of
     this approach is that you can't specify scopes.
  2. Write a parser plugin in C for ctags. This approach is much more powerful
     than the regex approach since you can make use of all of ctags'
     functionality but it also requires much more work. Read the ctags
     documentation for more information about how to do this.

For the first approach the only keys that are needed in the Tagbar definition
are "ctagstype" and "kinds". A definition that supports scopes has to define
those two and in addition "scopes", "sro" and at least one of "kind2scope" and
"scope2kind".

Let's assume we want to add support for LaTeX to Tagbar using the regex
approach. First we put the following text into ~/.ctags or a file pointed to
by the "deffile" definition entry:
>
        --langdef=latex
        --langmap=latex:.tex
        --regex-latex=/^\\tableofcontents/TABLE OF CONTENTS/s,toc/
        --regex-latex=/^\\frontmatter/FRONTMATTER/s,frontmatter/
        --regex-latex=/^\\mainmatter/MAINMATTER/s,mainmatter/
        --regex-latex=/^\\backmatter/BACKMATTER/s,backmatter/
        --regex-latex=/^\\bibliography\{/BIBLIOGRAPHY/s,bibliography/
        --regex-latex=/^\\part[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/PART \2/s,part/
        --regex-latex=/^\\part[[:space:]]*\*[[:space:]]*\{([^}]+)\}/PART \1/s,part/
        --regex-latex=/^\\chapter[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/CHAP \2/s,chapter/
        --regex-latex=/^\\chapter[[:space:]]*\*[[:space:]]*\{([^}]+)\}/CHAP \1/s,chapter/
        --regex-latex=/^\\section[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\. \2/s,section/
        --regex-latex=/^\\section[[:space:]]*\*[[:space:]]*\{([^}]+)\}/\. \1/s,section/
        --regex-latex=/^\\subsection[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\.\. \2/s,subsection/
        --regex-latex=/^\\subsection[[:space:]]*\*[[:space:]]*\{([^}]+)\}/\.\. \1/s,subsection/
        --regex-latex=/^\\subsubsection[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\.\.\. \2/s,subsubsection/
        --regex-latex=/^\\subsubsection[[:space:]]*\*[[:space:]]*\{([^}]+)\}/\.\.\. \1/s,subsubsection/
        --regex-latex=/^\\includegraphics[[:space:]]*(\[[^]]*\])?[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\3/g,graphic+listing/
        --regex-latex=/^\\lstinputlisting[[:space:]]*(\[[^]]*\])?[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\3/g,graphic+listing/
        --regex-latex=/\\label[[:space:]]*\{([^}]+)\}/\1/l,label/
        --regex-latex=/\\ref[[:space:]]*\{([^}]+)\}/\1/r,ref/
        --regex-latex=/\\pageref[[:space:]]*\{([^}]+)\}/\1/p,pageref/
<
This will create a new language definition with the name "latex" and associate
it with files with the extension ".tex". It will also define the kinds "s" for
sections, chapters and the like, "g" for included graphics, "l" for labels,
"r" for references and "p" for page references. See the ctags documentation
for more information about the exact syntax.

Now we have to create the Tagbar language definition in our vimrc:
>
        let g:tagbar_type_tex = {
            \ 'ctagstype' : 'latex',
            \ 'kinds'     : [
                \ 's:sections',
                \ 'g:graphics:0:0',
                \ 'l:labels',
                \ 'r:refs:1:0',
                \ 'p:pagerefs:1:0'
            \ ],
            \ 'sort'    : 0,
            \ 'deffile' : expand('<sfile>:p:h:h') . '/ctags/latex.cnf'
        \ }
<
The "deffile" field is of course only needed if the ctags definition actually
is in that file and not in ~/.ctags.

Sort has been disabled for LaTeX so that the sections appear in their correct
order. They unfortunately can't be shown nested with their correct scopes
since as already mentioned the regular expression approach doesn't support
that.

Tagbar should now be able to show the sections and other tags from LaTeX
files.

Note: As of 2012-05-05 the ctags development version contains an improved
LaTeX parser that works better than the example configuration presented here.
So if you are using a development build newer than that or a stable version
newer than 5.8 you should use the built-in support instead of this example.

Writing your own tag-generating program~
If you want to write your own program for generating tags then here are some
imporant tips to get it to integrate well with Tagbar:

  - Tagbar supports the same tag format as Vim itself. The format is described
    in |tags-file-format|, the third format mentioned there is the relevant
    one. Note that the {tagaddress} part should be a search pattern since the
    line number can be specified in a field (see below).
  - Tagbar reads the tag information from a program's standard output
    (stdout), it doesn't generate files and reads them in after that. So make
    sure that your program has an option to output the tags on stdout.
  - Some fields are supported for providing additional information about a
    tag. One field is required: the "kind" field as a single letter without
    a "kind:" fieldname. This field has to be the first one in the list. All
    other fields need to have a fieldname in order to determine what they are.
    The following fields are supported for all filetypes:

        * line:      The line number of the tag.
        * column:    The column number of the tag.
        * signature: The signature of a function.
        * access:    Visibility/access information of a tag; the values
                     "public", "protected" and "private" will be denoted with
                     a special symbol in Tagbar.

    In addition fields that describe the surrounding scope of the tag are
    supported if they are specified in the type configuration as explained at
    the beginning of this section. For example, for a tag in class "Foo" this
    could look like "class:Foo".
    Important: the value of such a scope-specifying field should be the entire
    hierarchy of scopes that the tag is in, so if for example in C++ you have
    a member in class "Foo" which is in namespace "Bar" then the scope field
    should be "class:Bar::Foo".

==============================================================================
7. Troubleshooting & Known issues                              *tagbar-issues*

As a general rule, if the tag information displayed by Tagbar is wrong (for
example, a method doesn't show up or is in the wrong place) you should first
try running ctags manually to see whether ctags reports the wrong information
or whether that information is correct and Tagbar does something wrong. To run
ctags manually execute the following command in a terminal:
>
        ctags -f - --format=2 --excmd=pattern --extra= --fields=nksaSmt myfile
<
If you set the |g:tagbar_ctags_bin| variable you probably have to use the same
value here instead of simply "ctags".

If Tagbar doesn't seem to work at all, but you don't get any error messages,
you can use Tagbar's debug mode to try to find the source of the problem (see
|tagbar-commands| on how to invoke it). In that case you should especially pay
attention to the reported file type and the ctags command line in the log
file.


  - jsctags has to be newer than 2011-01-06 since it needs the "-f" option to
    work. Also, the output of jsctags seems to be a bit unreliable at the
    moment (especially regarding line numbers), so if you notice some strange
    behaviour with it please run it manually in a terminal to check whether
    the bug is in jsctags or Tagbar.

  - Nested pseudo-tags cannot be properly parsed since only the direct parent
    scope of a tag gets assigned a type, the type of the grandparents is not
    reported by ctags (assuming the grandparents don't have direct, real
    children).

    For example, if we have a C++ file with the following content:
>
        foo::Bar::init()
        {
            // ...
        }
        foo::Baz::method()
        {
            // ...
        }
<
    In this case the type of "foo" is not known. Is it a namespace? A class?
    For this reason the methods are displayed in Tagbar like this:
>
        foo::Bar* : class
          init()
        foo::Baz* : class
          method()
<
  - Scope-defining tags at the top level that have the same name but a
    different kind/scope type can lead to an incorrect display. For example,
    the following Python code will incorrectly insert a pseudo-tag "Inner2"
    into the "test" class:
>
        class test:
            class Inner:
                def foo(self):
                    pass

        def test():
            class Inner2:
                def bar(self):
                    pass
<
    I haven't found a proper way around this yet, but it shouldn't be much of
    a problem in practice anyway. Tags with the same name at any other level
    are no problem, though.

==============================================================================
8. History                                                    *tagbar-history*

2.4.1 (2012-07-16)
    - Fixed some bugs related to the currenttag() function when it was called
      before the rest of the plugin was loaded. Also fail silently in case
      something goes wrong so the statusline doesn't get messed up.
    - In certain cases highlighting tags in deeply nested folds could cause an
      error message.
    - Spellchecking is now correctly getting disabled in the Tagbar window.

2.4 (2012-06-17)
    - New function tagbar#currenttag() that reports the current tag, for
      example for putting it into the statusline.
    - New command TagbarGetTypeConfig for easy customization of an existing
      type.
    - Type definitions now can be loaded from ftplugins.
    - The autoopen() function is now a bit more flexible.
    - Vala is now supported if Anjuta is installed.
    - Various other small improvements and bugfixes.

2.3 (2011-12-24)
    - Add a convenience function that allows more flexible ways to
      automatically open Tagbar.
    - Replace option tagbar_usearrows with tagbar_iconchars to allow custom
      characters to be specified. This helps with fonts that don't display the
      default characters properly.
    - Remove the need to provide the complete jsctags configuration if jsctags
      is not found in $PATH, now only the concrete path has to be specified.
    - Add debugging functionality.

2.2 (2011-11-26)
    - Small incompatible change: TagbarOpen now doesn't jump to the Tagbar
      window anymore if it is already open. Use "TagbarOpen j" instead or see
      its documentation for more options.
    - Tags inside of scopes now have a header displaying their "kind".
    - The Tagbar contents are now immediately updated on save for files
      smaller than a configurable size.
    - Tagbar can now be configured to jump to a tag with only a single-click
      instead of a double-click.
    - Most of the script has been moved to the |autoload| directory, so Vim
      startup should be faster (thanks to Kien N).
    - Jumping to tags should work most of the time even if the file has been
      modified and not saved.
    - If Ctags has been installed into the default location using Homebrew or
      MacPorts it should now be found automatically.
    - Several bugfixes.

2.1 (2011-05-29)
    - Make Tagbar work in (hopefully) all cases under Windows
    - Handle cases where 'encoding' is different from system encoding, for
      example on a Chinese Windows with 'encoding' set to "utf-8" (see manual
      for details in case it doesn't work out-of-the-box)
    - Fixed a bug with the handling of subtypes like "python.django"
    - If a session got saved with Tagbar open it now gets restored properly
    - Locally reset foldmethod/foldexpr in case foldexpr got set to something
      expensive globally
    - Tagbar now tries hard to go to the correct window when jumping to a tag
    - Explain some possible issues with the current jsctags version in the
      manual
    - Explicitly check for some possible configuration problems to be able to
      give better feedback
    - A few other small fixes

2.0.1 (2011-04-26)
    - Fix sorting bug when 'ignorecase' is set

2.0 (2011-04-26)
    - Folding now works correctly. Folds will be preserved when leaving the
      Tagbar window and when switching between files. Also tag types can be
      configured to be folded by default, which is useful for things like
      includes and imports.
    - DoctorJS/jsctags and other compatible programs are now supported.
    - All of the highlight groups can now be overridden.
    - Added keybinding to quickly jump to next/previous top-level tag.
    - Added Taglist's "p" keybinding for jumping to a tag without leaving the
      Tagbar window.
    - Several bugfixes and other small improvements.

1.5 (2011-03-06)
    - Type definitions can now include a path to a file with the ctags
      definition. This is especially useful for ftplugins that can now ship
      with a complete ctags and Tagbar configuration without requiring user
      intervention. Thanks to Jan Christoph Ebersbach for the suggestion.
    - Added autofocus setting by Taybin Rutkin. This will put the cursor in
      the Tagbar window when it is opened.
    - The "scopes" field is no longer needed in type definitions, the
      information is already there in "scope2kind". Existing definitions will
      be ignored.
    - Some fixes and improvements related to redrawing and window switching.

1.2 (2011-02-28)
    - Fix typo in Ruby definition

1.1 (2011-02-26)
    - Don't lose syntax highlighting when ':syntax enable' is called
    - Allow expanding the Vim window when Tagbar is opened

1.0 (2011-02-23)
    - Initial release

==============================================================================
9. Todo                                                          *tagbar-todo*

  - Allow filtering the Tagbar content by some criteria like tag name,
    visibility, kind ...
  - Integrate Tagbar with the FSwitch plugin to provide header file
    information in C/C++.
  - Allow jumping to a tag in the preview window, a split window or a new tab.

==============================================================================
10. Credits                                                   *tagbar-credits*

Tagbar was written by Jan Larres and is released under the Vim licence, see
|license|. It was heavily inspired by the Taglist plugin by Yegappan
Lakshmanan and uses a small amount of code from it.

Original taglist copyright notice:
Permission is hereby granted to use and distribute this code, with or without
modifications, provided that this copyright notice is copied with it. Like
anything else that's free, taglist.vim is provided *as is* and comes with no
warranty of any kind, either expressed or implied. In no event will the
copyright holder be liable for any damamges resulting from the use of this
software.

The folding technique was inspired by NERDTree by Martin Grenfell.

Thanks to the following people for code contributions, feature suggestions etc:
Jan Christoph Ebersbach
Vadim Fint
Leandro Freitas
Seth Milliken
Kien N
pielgrzym
Taybin Rutkin
Ville Valkonen

==============================================================================
 vim: tw=78 ts=8 sw=4 sts=4 et ft=help