Version 2.0

- added zo alias to OpenFold()
- added za alias to ToggleFold()
- added zc alias to CloseFold()
- added zC alias to CloseParent()
- added zn alias to SetFoldLevel(99, 1)
- added zR alias to SetFoldLevel(99, 1)
- added zM alias to SetFoldLevel(0, 1)
- changed z zoom shortcut to zz to avoid delay caused by presence of new z-prefix bindings
- update s:PrintHelp() to reflect new bindings

doc/tagbar.txt

@@ -3,7 +3,7 @@
 Author:		Jan Larres <jan@majutsushi.net>
 Licence:	Vim licence, see |license|
 Homepage:	http://majutsushi.github.com/tagbar/
-Version:	1.0
+Version:	2.0
 
 ==============================================================================
 Contents					*tagbar* *tagbar-contents*
@@ -11,12 +11,15 @@ 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|
 	 6. Extending Tagbar ................ |tagbar-extend|
 	 7. Bugs and limitations ............ |tagbar-bugs|
 	 8. History ......................... |tagbar-history|
@@ -100,6 +103,16 @@ The following features are supported by Tagbar:
     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.
+
 ==============================================================================
 2. Requirements						*tagbar-requirements*
 
@@ -117,15 +130,15 @@ The following requirements have to be met in order to be able to use tagbar:
     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.
+    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|.
+  - Tagbar will not work in |restricted-mode| or with 'compatible' set.
 
 ==============================================================================
 3. Installation						*tagbar-installation*
@@ -195,9 +208,9 @@ 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|.
+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
@@ -223,20 +236,38 @@ COMMANDS						*tagbar-commands*
     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 [number]
+    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'.
+
+: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.
+
 ------------------------------------------------------------------------------
 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.
+<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>.
 <Space>       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.
++/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.
@@ -246,6 +277,8 @@ q             Close the Tagbar window.
 
 							*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.
 
@@ -256,6 +289,8 @@ Example:
 
 							*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.
 
@@ -266,7 +301,9 @@ Example:
 
 							*g:tagbar_width*
 g:tagbar_width~
-Width of the Tagbar window in characters. The default is 40.
+Default: 40
+
+Width of the Tagbar window in characters.
 
 Example:
 >
@@ -275,19 +312,34 @@ Example:
 
 							*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. The default is to not automatically close the window.
+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. The default
-is to sort them by name.
+unset they are sorted according to their order in the source file.
 
 Example:
 >
@@ -296,14 +348,137 @@ Example:
 
 							*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. The default is to not use compact mode.
+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
+<
+
+							*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
+<
+
+------------------------------------------------------------------------------
+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".
+
+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*
+
+If you want Tagbar to open automatically, for example on Vim startup or for
+specific filetypes, there are various ways to do it. For example, to always
+open Tagbar on Vim startup you can put this into your vimrc file:
+>
+    autocmd VimEnter * nested TagbarOpen
+<
+If you want to have it start for specific filetypes put
+>
+    TagbarOpen
+<
+into a corresponding filetype plugin (see |filetype-plugin|).
+
+Check out |autocmd.txt| if you want it to automatically open in more
+complicated cases.
+
 ==============================================================================
 6. Extending Tagbar					*tagbar-extend*
 
@@ -322,19 +497,28 @@ kinds:      A list of the "language kinds" that should be listed in Tagbar,
             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 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. For example, the string >
-                "f:functions"
+            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".
-scopes:     A list of the scopes that ctags supports for a given language, 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: >
+            "functions" and fold them.
+sro:        The scope resolution operator. For example, in C++ it is "::" and
+            in Java it is ".". If in doubt run ctags as shown above 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:
@@ -348,15 +532,8 @@ scopes:     A list of the scopes that ctags supports for a given language, for
 <           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 you would need to put this exact word into the
-            "scopes" list. The order again determines the order in which the
-            tags will be displayed in Tagbar.
-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.
+            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
@@ -371,6 +548,32 @@ sort:       This entry can be used to override the global sort setting for
             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 provide the
+           complete configuration and use the "replace" key (see the
+           Tagbar source code for the suggested configuration).
+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 with the name
 >
@@ -390,8 +593,8 @@ used in Tagbar.
 	let g:tagbar_type_cpp = {
 	    \ 'ctagstype' : 'c++',
 	    \ 'kinds'     : [
-	        \ 'd:macros',
-	        \ 'p:prototypes',
+	        \ 'd:macros:1',
+	        \ 'p:prototypes:1',
 	        \ 'g:enums',
 	        \ 'e:enumerators',
 	        \ 't:typedefs',
@@ -403,13 +606,6 @@ used in Tagbar.
 	        \ 'm:members',
 	        \ 'v:variables'
 	    \ ],
-	    \ 'scopes' : [
-	        \ 'namespace',
-	        \ 'class',
-	        \ 'struct',
-	        \ 'enum',
-	        \ 'union'
-	    \ ],
 	    \ 'sro'        : '::',
 	    \ 'kind2scope' : {
 	        \ 'g' : 'enum',
@@ -440,7 +636,7 @@ the order of enums and typedefs, you would do it like this:
 >
 	let g:tagbar_type_cpp = {
 	    \ 'kinds' : [
-	        \ 'd:macros',
+	        \ 'd:macros:1',
 	        \ 'g:enums',
 	        \ 't:typedefs',
 	        \ 'e:enumerators',
@@ -475,7 +671,8 @@ 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:
+approach. First we put the following text into ~/.ctags or a file pointed to
+by the "deffile" definition entry:
 >
 	--langdef=latex
 	--langmap=latex:.tex
@@ -514,12 +711,16 @@ Now we have to create the Tagbar language definition in our vimrc:
 	        \ 's:sections',
 	        \ 'g:graphics',
 	        \ 'l:labels',
-	        \ 'r:refs',
-	        \ 'p:pagerefs'
+	        \ 'r:refs:1',
+	        \ 'p:pagerefs:1'
 	    \ ],
-	    \ 'sort' : 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
@@ -574,13 +775,40 @@ files.
     problem in practice anyway. Tags with the same name at any other level are
     no problem, though.
 
-  - The fold state of the Tagbar window is lost when the window is left.
-    Again, I don't know of any proper way around this that still allows
-    auto-updating -- |winsaveview()| doesn't really help here.
-
 ==============================================================================
 8. History						*tagbar-history*
 
+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 usefult 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
 
@@ -607,3 +835,16 @@ 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
+Seth Milliken:
+  - Contributed folding keybindings that resemble the built-in ones
+
+Thanks to the following people for feature suggestions etc: Jan Christoph
+Ebersbach, pielgrzym
+
+==============================================================================
+ vim: tw=78 ts=8 sw=8 sts=8 noet ft=help

syntax/tagbar.vim

@@ -0,0 +1,60 @@
+" File:        tagbar.vim
+" Description: Tagbar syntax settings
+" Author:      Jan Larres <jan@majutsushi.net>
+" Licence:     Vim licence
+" Website:     http://majutsushi.github.com/tagbar/
+" Version:     2.0
+
+if exists("b:current_syntax")
+  finish
+endif
+
+if has('multi_byte') && has('unix') && &encoding == 'utf-8' &&
+ \ (empty(&termencoding) || &termencoding == 'utf-8')
+    syntax match TagbarKind  '\([▶▼] \)\@<=[^-+: ]\+[^:]\+$'
+    syntax match TagbarScope '\([▶▼][-+# ]\)\@<=[^*]\+\(\*\?\(([^)]\+)\)\? :\)\@='
+
+    syntax match TagbarFoldIcon '[▶▼]\([-+# ]\)\@='
+
+    syntax match TagbarAccessPublic    '\([▶▼ ]\)\@<=+\([^-+# ]\)\@='
+    syntax match TagbarAccessProtected '\([▶▼ ]\)\@<=#\([^-+# ]\)\@='
+    syntax match TagbarAccessPrivate   '\([▶▼ ]\)\@<=-\([^-+# ]\)\@='
+elseif has('multi_byte') && (has('win32') || has('win64')) && g:tagbar_usearrows
+    syntax match TagbarKind  '\([▷◢] \)\@<=[^-+: ]\+[^:]\+$'
+    syntax match TagbarScope '\([▷◢][-+# ]\)\@<=[^*]\+\(\*\?\(([^)]\+)\)\? :\)\@='
+
+    syntax match TagbarFoldIcon '[▷◢]\([-+# ]\)\@='
+
+    syntax match TagbarAccessPublic    '\([▷◢ ]\)\@<=+\([^-+# ]\)\@='
+    syntax match TagbarAccessProtected '\([▷◢ ]\)\@<=#\([^-+# ]\)\@='
+    syntax match TagbarAccessPrivate   '\([▷◢ ]\)\@<=-\([^-+# ]\)\@='
+else
+    syntax match TagbarKind  '\([-+] \)\@<=[^-+: ]\+[^:]\+$'
+    syntax match TagbarScope '\([-+][-+# ]\)\@<=[^*]\+\(\*\?\(([^)]\+)\)\? :\)\@='
+
+    syntax match TagbarFoldIcon '[-+]\([-+# ]\)\@='
+
+    syntax match TagbarAccessPublic    '\([-+ ]\)\@<=+\([^-+# ]\)\@='
+    syntax match TagbarAccessProtected '\([-+ ]\)\@<=#\([^-+# ]\)\@='
+    syntax match TagbarAccessPrivate   '\([-+ ]\)\@<=-\([^-+# ]\)\@='
+endif
+
+syntax match TagbarComment   '^".*'
+syntax match TagbarType      ' : \zs.*'
+syntax match TagbarSignature '(.*)'
+syntax match TagbarPseudoID  '\*\ze :'
+
+highlight default link TagbarComment   Comment
+highlight default link TagbarKind      Identifier
+highlight default link TagbarScope     Title
+highlight default link TagbarType      Type
+highlight default link TagbarSignature SpecialKey
+highlight default link TagbarPseudoID  NonText
+highlight default link TagbarFoldIcon  Statement
+highlight default link TagbarHighlight Search
+
+highlight default TagbarAccessPublic    guifg=Green ctermfg=Green
+highlight default TagbarAccessProtected guifg=Blue  ctermfg=Blue
+highlight default TagbarAccessPrivate   guifg=Red   ctermfg=Red
+
+let b:current_syntax = "tagbar"