ylib/tagbar
1
0
Fork 0
mirror of https://github.com/preservim/tagbar.git synced 2024-11-30 13:36:01 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
d27c8b96bb
tagbar/doc/tagbar.txt
Jan Larres d27c8b96bb Document new folding features
2011-04-23 22:51:45 +12:00

726 lines
28 KiB
Plaintext
Raw Blame History

*tagbar.txt* Display tags of a file in their correct scope
Author: Jan Larres <jan@majutsushi.net>
Licence: Vim licence, see |license|
Homepage: http://majutsushi.github.com/tagbar/
Version: 1.5
==============================================================================
Contents *tagbar* *tagbar-contents*
1. Intro ........................... |tagbar-intro|
Pseudo-tags ................... |tagbar-pseudotags|
Supported features ............ |tagbar-features|
2. Requirements .................... |tagbar-requirements|
3. Installation .................... |tagbar-installation|
4. Usage ........................... |tagbar-usage|
Commands ...................... |tagbar-commands|
Key mappings .................. |tagbar-keys|
5. Configuration ................... |tagbar-configuration|
6. Extending Tagbar ................ |tagbar-extend|
7. Bugs and limitations ............ |tagbar-bugs|
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.
==============================================================================
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 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
you're not using pathogen.
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 in 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 statusbar 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.
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
Open the Tagbar if it is closed. In case it is already open jump to it.
:TagbarClose
Close the Tagbar window if it is open.
:TagbarToggle
Open the Tagbar window if it is closed or close it if it is open.
:TagbarOpenAutoClose
Open the Tagbar window and close it on tag selection, regardless of the
setting of |g:tagbar_autoclose|. If it was already open jump to it.
:TagbarSetFoldlevel
Set the foldlevel of the tags that are currently displayed. The foldlevel
of tags in other files remains unaffected. Works in the same way as
'foldlevel'.
------------------------------------------------------------------------------
KEY MAPPINGS *tagbar-keys*
These 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.
<LeftMouse> When on a fold icon, open or close the fold depending on the
current state.
<2-LeftMouse> Same as <CR>.
<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.
=/zM Close all folds.
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.
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.
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_foldlevel*
g:tagbar_foldlevel~
Default: 99
The initial foldlevel for folds in the Tagbar window. Fold with a level higher
than this number will be closed.
Example:
>
let g:tagbar_foldlevel = 2
<
*g:tagbar_usearrows*
g:tagbar_usearrows~
{Windows only}
Default: 0
Tagbar can display nice Unicode arrows instead of +/- characters as fold icons.
However, Windows doesn't seem to be able to substitute in characters from
other fonts if the current font doesn't support them. This means that you have
to use a font that supports those arrows. Unfortunately there is no way to
detect whether specific characters are supported in the current font. So if
your font supports those arrows you have to set this option to make it work.
Example:
>
let g:tagbar_usearrows = 1
<
==============================================================================
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.
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 string with two or three parts separated
by a colon: the first part is the one-character abbreviation that
ctags uses, and the second part is an arbitrary string that will
be used in Tagbar as the header for the tags of this kind that are
not listed under a specific scope. The optional third part
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. For
example, the string >
"f:functions:1"
< would list all the function definitions in a file under the header
"functions" and fold them.
sro: The scope resolution operator. For example, in C++ it is "::" and
in Java it is ".". When in doubt run ctags as shown above and look
at 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 followin way: >
ctags -f - --format=2 --excmd=pattern --fields=nksazSmt --extra= 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'
<
You then have to assign this dictionary to a variable 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 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.
>
let g:tagbar_type_cpp = {
\ 'ctagstype' : 'c++',
\ 'kinds' : [
\ 'd:macros:1',
\ 'p:prototypes:1',
\ 'g:enums',
\ 'e:enumerators',
\ 't:typedefs',
\ 'n:namespaces',
\ 'c:classes',
\ 's:structs',
\ 'u:unions',
\ 'f:functions',
\ 'm:members',
\ 'v:variables'
\ ],
\ '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"
and/or "scopes", which would be the case if you wanted to exclude certain
kinds from appearing in Tagbar or if you want to change their order. As an
example, if you didn't want Tagbar to show prototypes for C++ files and switch
the order of enums and typedefs, you would do it like this:
>
let g:tagbar_type_cpp = {
\ 'kinds' : [
\ 'd:macros:1',
\ 'g:enums',
\ 't:typedefs',
\ 'e:enumerators',
\ 'n:namespaces',
\ 'c:classes',
\ 's:structs',
\ 'u:unions',
\ 'f:functions',
\ 'm:members',
\ 'v:variables'
\ ]
\ }
<
Compare with the complete example above to see the exact change.
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',
\ 'l:labels',
\ 'r:refs:1',
\ 'p:pagerefs:1'
\ ],
\ '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.
==============================================================================
7. Bugs and limitations *tagbar-bugs*
- 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++ 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 clean 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*
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.
Taybin Rutkin:
- Contributed tagbar_autofocus option
Jan Christoph Ebersbach:
- Suggested "deffile" option
Seth Milliken:
- Contributed folding keybindings that resemble the built-in ones
==============================================================================
vim: tw=78 ts=8 sw=8 sts=8 noet ft=help
Reference in New Issue View Git Blame Copy Permalink