*tagbar.txt* Display tags of a file in their correct scope Author: Jan Larres Licence: Vim licence, see |license| Homepage: http://github.com/majutsushi/tagbar Version: TODO ============================================================================== 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. Adding your own file types ...... |tagbar-add-types| 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 correct 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|. ============================================================================== 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 :TagbarToggle < You can then open and close Tagbar by simply pressing the 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 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 untinteresting information. Unfortunately the folding state is lost once you leave the Tagbar window, see |tagbar-bugs|. 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 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. ------------------------------------------------------------------------------ KEY MAPPINGS *tagbar-keys* These mappings are valid in the Tagbar window: Display key mapping help. / Jump to the tag under the cursor. Doesn't work for pseudo-tags. <2-LeftMouse> Same as . Display the prototype of the current tag (i.e. the line defining it) in the command line. + Open the fold under the cursor. - Close the fold under the cursor. * Open all folds. = 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~ 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~ 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~ Width of the Tagbar window in characters. The default is 40. Example: > let g:tagbar_width = 30 < *g:tagbar_autoclose* g:tagbar_autoclose~ If you set this option the Tagbar window will automatically close when you jump to a tag. The default is to not automatically close the window. Example: > let g:tagbar_autoclose = 1 < *g:tagbar_sort* g:tagbar_sort~ 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. The default is to sort them by name. Example: > let g:tagbar_sort = 0 < *g:tagbar_compact* g:tagbar_compact~ 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. The default is to not use compact mode. Example: > let g:tagbar_compact = 1 < ============================================================================== 6. Adding your own file types *tagbar-add-types* ============================================================================== 7. Bugs and limitations *tagbar-bugs* ============================================================================== 8. History *tagbar-history* ============================================================================== 9. Todo *tagbar-todo* ============================================================================== 10. Credits *tagbar-credits* caveats: C++: foo::Bar::init() foo::Baz::method() type of 'foo' is unknown (sorting problems), foo::Bar and foo::Baz listed separately class test: class Inner: def __init__(self): print "Inner" def test(): class Inner2: def __init__(self): print "Inner2" keep folds window numbers