Version 2.3

Ignore /doc/tags

.gitattributes

@@ -0,0 +1,4 @@
+.gitignore     export-ignore
+.gitattributes export-ignore
+README         export-ignore
+.info          export-ignore

.gitignore

@@ -0,0 +1 @@
+/doc/tags

.info

@@ -0,0 +1,2 @@
+tagbar
+3465

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:	2.1
+Version:	2.3
 
 ==============================================================================
 Contents					*tagbar* *tagbar-contents*
@@ -21,7 +21,7 @@ Contents					*tagbar* *tagbar-contents*
 	      Highlight colours ............. |tagbar-highlight|
 	      Automatically opening Tagbar .. |tagbar-autoopen|
 	 6. Extending Tagbar ................ |tagbar-extend|
-	 7. Bugs and limitations ............ |tagbar-bugs|
+	 7. Troubleshooting & Known issues .. |tagbar-issues|
 	 8. History ......................... |tagbar-history|
 	 9. Todo ............................ |tagbar-todo|
 	10. Credits ......................... |tagbar-credits|
@@ -113,11 +113,7 @@ 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: 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.
+Note: Please check |tagbar-issues| for some possible issues with jsctags.
 
 ==============================================================================
 2. Requirements						*tagbar-requirements*
@@ -229,9 +225,22 @@ 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.
+:TagbarOpen [{flags}]
+    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')
+
+    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
     Close the Tagbar window if it is open.
 
@@ -239,11 +248,11 @@ COMMANDS						*tagbar-commands*
     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.
+    Open the Tagbar window, jump to it and close it on tag selection. This is
+    an alias for ":TagbarOpen fc".
 
-:TagbarSetFoldlevel [number]
-    Set the foldlevel of the tags of the current file to [number]. The
+: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'.
 
@@ -251,10 +260,18 @@ COMMANDS						*tagbar-commands*
     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.
 
+:TagbarDebug [logfile]
+    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
+    End debug mode, debug messages will no longer be written to the logfile.
+
 ------------------------------------------------------------------------------
 KEY MAPPINGS						*tagbar-keys*
 
-These mappings are valid in the Tagbar window:
+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
@@ -262,7 +279,8 @@ These mappings are valid in the Tagbar window:
 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>.
+<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.
@@ -321,7 +339,7 @@ g:tagbar_autoclose~
 Default: 0
 
 If you set this option the Tagbar window will automatically close when you
-jump to a tag.
+jump to a tag. This implies |g:tagbar_autofocus|.
 
 Example:
 >
@@ -379,6 +397,18 @@ 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
@@ -391,21 +421,22 @@ Example:
 	let g:tagbar_foldlevel = 2
 <
 
-							*g:tagbar_usearrows*
-g:tagbar_usearrows~
-{Windows only}
-Default: 0
+							*g:tagbar_iconchars*
+g:tagbar_iconchars~
 
-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.
+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.
 
-Example:
+Examples (don't worry if some the characters aren't displayed correctly, just
+choose other characters in that case):
 >
-	let g:tagbar_usearrows = 1
+	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*
@@ -423,6 +454,22 @@ Example:
 	let g:tagbar_autoshowtag = 1
 <
 
+						*g:tagbar_updateonsave_maxlines*
+g:tagbar_updateonsave_maxlines~
+Default: 5000
+
+If the current file has fewer lines than the value of this variable, Tagbar
+will update immediately after saving the file. If it is longer then the update
+will only happen on the |CursorHold| event and when switching buffers (or
+windows). This is to prevent the time it takes to save a large file from
+becoming annoying in case you have a slow computer. If you have a fast
+computer you can set it to a higher value.
+
+Example:
+>
+	let g:tagbar_updateonsave_maxlines = 10000
+<
+
 							*g:tagbar_systemenc*
 g:tagbar_systemenc~
 Default: value of 'encoding'
@@ -450,6 +497,9 @@ TagbarComment
 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.
 
@@ -487,19 +537,32 @@ 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|).
+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).
 
-Check out |autocmd.txt| if you want it to automatically open in more
+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()
+<
+For opening Tagbar also if you open a supported file in an already running
+Vim:
+>
+    autocmd FileType * nested :call tagbar#autoopen()
+<
+And if you only 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.
 
 ==============================================================================
@@ -511,6 +574,12 @@ existing types and to add completely new types. A complete configuration
 consists of a type definition for Tagbar in your |vimrc| and optionally a
 language definition for ctags in case you want to add a new language.
 
+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 >
@@ -535,7 +604,7 @@ kinds:      A list of the "language kinds" that should be listed in Tagbar,
 <           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 ".". If in doubt run ctags as shown above and check
+            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
@@ -552,8 +621,8 @@ kind2scope: A dictionary describing the mapping of tag kinds (in their
                 private:
                     int var;
                 };
-<           We then run ctags in the followin way: >
-                ctags -f - --format=2 --excmd=pattern --fields=nksazSmt --extra= test.cpp
+<           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
@@ -591,9 +660,9 @@ deffile:    The path to a file with additional ctags definitions (see the
 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).
+           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).
 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
@@ -614,7 +683,8 @@ 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.
+used in Tagbar. This is just for illustration purposes since user
+configurations will usually be less complicated.
 >
 	let g:tagbar_type_cpp = {
 	    \ 'ctagstype' : 'c++',
@@ -676,7 +746,7 @@ the order of enums and typedefs, you would do it like this:
 	    \ ]
 	\ }
 <
-Compare with the complete example above to see the exact change.
+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
@@ -756,14 +826,38 @@ Tagbar should now be able to show the sections and other tags from LaTeX
 files.
 
 ==============================================================================
-7. Bugs and limitations					*tagbar-bugs*
+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++ with the following content:
+    For example, if we have a C++ file with the following content:
 >
         foo::Bar::init()
         {
@@ -804,6 +898,33 @@ files.
 ==============================================================================
 8. History						*tagbar-history*
 
+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
@@ -883,13 +1004,13 @@ 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
+Thanks to the following people for code contributions, feature suggestions etc:
+Jan Christoph Ebersbach
+Leandro Freitas
+Seth Milliken
+Kien N
+pielgrzym
+Taybin Rutkin
 
 ==============================================================================
  vim: tw=78 ts=8 sw=8 sts=8 noet ft=help

syntax/tagbar.vim

@@ -3,58 +3,61 @@
 " Author:      Jan Larres <jan@majutsushi.net>
 " Licence:     Vim licence
 " Website:     http://majutsushi.github.com/tagbar/
-" Version:     2.1
+" Version:     2.3
+
+scriptencoding utf-8
 
 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   '\([-+ ]\)\@<=-\([^-+# ]\)\@='
+let s:ic = g:tagbar_iconchars[0]
+if s:ic =~ '[]^\\-]'
+    let s:ic = '\' . s:ic
+endif
+let s:io = g:tagbar_iconchars[1]
+if s:io =~ '[]^\\-]'
+    let s:io = '\' . s:io
 endif
 
-syntax match TagbarComment   '^".*'
-syntax match TagbarType      ' : \zs.*'
-syntax match TagbarSignature '(.*)'
-syntax match TagbarPseudoID  '\*\ze :'
+let s:pattern = '\([' . s:ic . s:io . '] \)\@<=[^-+: ]\+[^:]\+$'
+execute "syntax match TagbarKind '" . s:pattern . "'"
 
-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
+let s:pattern = '\([' . s:ic . s:io . '][-+# ]\)\@<=[^*]\+\(\*\?\(([^)]\+)\)\? :\)\@='
+execute "syntax match TagbarScope '" . s:pattern . "'"
+
+let s:pattern = '[' . s:ic . s:io . ']\([-+# ]\)\@='
+execute "syntax match TagbarFoldIcon '" . s:pattern . "'"
+
+let s:pattern = '\([' . s:ic . s:io . ' ]\)\@<=+\([^-+# ]\)\@='
+execute "syntax match TagbarAccessPublic '" . s:pattern . "'"
+let s:pattern = '\([' . s:ic . s:io . ' ]\)\@<=#\([^-+# ]\)\@='
+execute "syntax match TagbarAccessProtected '" . s:pattern . "'"
+let s:pattern = '\([' . s:ic . s:io . ' ]\)\@<=-\([^-+# ]\)\@='
+execute "syntax match TagbarAccessPrivate '" . s:pattern . "'"
+
+unlet s:pattern
+
+syntax match TagbarNestedKind '^\s\+\[[^]]\+\]$'
+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 TagbarNestedKind TagbarKind
+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"
+
+" vim: ts=8 sw=4 sts=4 et foldenable foldmethod=marker foldcolumn=1