Version 2.6

Use psearch instead of pedit since pedit essentially reloads the file
and creates an empty undo entry. This also makes it faster.

README.md

@@ -3,8 +3,11 @@
 Tagbar is a vim 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.
 
-Check out the homepage at http://majutsushi.github.com/tagbar/ for more information.
+Check out the homepage at http://majutsushi.github.io/tagbar/ for more information.
 
+# Support for additional filetypes
+
+For filetypes that are not supported by Exuberant Ctags check out [the wiki](https://github.com/majutsushi/tagbar/wiki) to see whether other projects offer support for them and how to use them. Please add any other projects/configurations that you find or create yourself so that others can benefit from them, too.
 
 # Important: If the file structure is displayed wrong
 

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.5
+Version:        2.6
 
 ==============================================================================
 Contents                                            *tagbar* *tagbar-contents*
@@ -21,6 +21,7 @@ Contents                                            *tagbar* *tagbar-contents*
               Highlight colours ............. |tagbar-highlight|
               Automatically opening Tagbar .. |tagbar-autoopen|
               Show current tag in statusline  |tagbar-statusline|
+              Ignoring specific files ....... |tagbar-ignore|
          6. Extending Tagbar ................ |tagbar-extend|
          7. Troubleshooting & Known issues .. |tagbar-issues|
          8. History ......................... |tagbar-history|
@@ -261,14 +262,15 @@ COMMANDS                                                     *tagbar-commands*
     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.
+:Tagbar
+    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".
 
 :TagbarTogglePause                                        *:TagbarTogglePause*
-    Freezes/Unfreezes the Tagbar window.  Stops the contents of the window 
+    Freezes/Unfreezes the Tagbar window.  Stops the contents of the window
     from changing when a different source file is selected.
 
 :TagbarSetFoldlevel[!] {number}                          *:TagbarSetFoldlevel*
@@ -298,6 +300,8 @@ COMMANDS                                                     *tagbar-commands*
     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!
+    Note also that it is usually necessary to call this command before loading
+    a file that creates problems in order to get all of the needed data.
 
 :TagbarDebugEnd                                              *:TagbarDebugEnd*
     End debug mode, debug messages will no longer be written to the logfile.
@@ -308,27 +312,53 @@ KEY MAPPINGS                                                     *tagbar-keys*
 The following mappings are valid in the Tagbar window:
 
 <F1>          Display key mapping help.
+                Map option: tagbar_map_help
 <CR>/<Enter>  Jump to the tag under the cursor. Doesn't work for pseudo-tags
               or generic headers.
+                Map option: tagbar_map_jump
 p             Jump to the tag under the cursor, but stay in the Tagbar window.
+                Map option: tagbar_map_preview
+P             Open the tag in a |preview-window|.
+                Map option: tagbar_map_previewwin
 <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.
+<C-N>         Go to the next top-level tag.
+                Map option: tagbar_map_nexttag
+<C-P>         Go to the previous top-level tag.
+                Map option: tagbar_map_prevtag
 <Space>       Display the prototype of the current tag (i.e. the line defining
               it) in the command line.
+                Map option: tagbar_map_showproto
 +/zo          Open the fold under the cursor.
+                Map option: tagbar_map_openfold
 -/zc          Close the fold under the cursor or the current one if there is
               no fold under the cursor.
+                Map option: tagbar_map_closefold
 o/za          Toggle the fold under the cursor or the current one if there is
               no fold under the cursor.
+                Map option: tagbar_map_togglefold
 */zR          Open all folds by setting foldlevel to 99.
+                Map option: tagbar_map_openallfolds
 =/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.
+                Map option: tagbar_map_closeallfolds
 s             Toggle sort order between name and file order.
+                Map option: tagbar_map_togglesort
 x             Toggle zooming the window.
+                Map option: tagbar_map_zoomwin
 q             Close the Tagbar window.
+                Map option: tagbar_map_close
+
+These mappings can be redefined with the given map options. The argument can
+be either a string or a |List| of strings. In the latter case the
+functionality will be assigned to all of the keys in the list. For example, if
+you want to remap the sort toggling functionality to "r":
+>
+        let g:tagbar_map_togglesort = "r"
+<
+See |key-notation| for how to write special keys like <Space> or the keypad
+keys.
 
 ==============================================================================
 5. Configuration                                        *tagbar-configuration*
@@ -443,12 +473,31 @@ Example:
         let g:tagbar_show_visibility = 0
 <
 
+                                                   *g:tagbar_show_linenumbers*
+g:tagbar_show_linenumbers~
+Default: 0
+
+Whether line numbers should be shown in the Tagbar window.
+
+Possible values are:
+  0: Don't show any line numbers.
+  1: Show absolute line numbers.
+  2: Show relative line numbers.
+  -1: Use the global line number settings.
+
+Example:
+>
+        let g:tagbar_show_linenumbers = 2
+<
+
                                                              *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.
+If this option is set to 1 the Vim window will be expanded by the width of the
+Tagbar window if using a GUI version of Vim. Setting it to 2 will also try
+expanding a terminal, but note that this is not supported by all terminals.
+See also |xterm-resize|.
 
 Example:
 >
@@ -492,7 +541,7 @@ 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 = ['▷', '◢']
         let g:tagbar_iconchars = ['+', '-']  (default on Windows)
 <
@@ -501,17 +550,50 @@ just choose other characters in that case):
 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.
+If this variable is set to 1 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 set to 0 then the folds will only be opened
+when opening the Tagbar window and the current tag is insided a closed fold,
+otherwise the folds won't be opened and the parent tag will be highlighted
+instead. If it is set to 2 then the folds will never be opened automatically.
+
+You can use the |:TagbarShowTag| command to open the folds manually.
 
 Example:
 >
         let g:tagbar_autoshowtag = 1
 <
 
+                                                     *g:tagbar_previewwin_pos*
+g:tagbar_previewwin_pos~
+Default: topleft
+
+The position of the preview window. Valid values are the window splitting
+commands that are described starting from |:vertical|. Set it to an empty
+string to use the options 'splitbelow' and 'splitright'.
+
+Example:
+>
+        let g:tagbar_previewwin_pos = "aboveleft"
+<
+If you want to disable line numbers in the preview window put something like
+this into your vimrc:
+>
+        autocmd BufWinEnter * if &previewwindow | setlocal nonumber | endif
+<
+
+                                                        *g:tagbar_autopreview*
+g:tagbar_autopreview~
+Default: 0
+
+If this variable is set to 1 then moving the cursor in the Tagbar window will
+automatically show the current tag in the preview window.
+
+Example:
+>
+        let g:tagbar_autopreview = 1
+<
+
                                               *g:tagbar_updateonsave_maxlines*
 g:tagbar_updateonsave_maxlines~
 
@@ -535,6 +617,33 @@ Example:
         let g:tagbar_systemenc = 'cp936'
 <
 
+                                                        *g:tagbar_status_func*
+g:tagbar_status_func~
+Default: undefined
+
+This is the name of a function whose return value will be used to draw the
+statusline of the Tagbar window.
+
+The function has to take three arguments:
+  1. current: Whether Tagbar is the current window; 0 or 1.
+  2. sort: The sort order of the tags; 'Name' if they are sorted by name and
+     'Order' if they are sorted by their order of appearance in the file.
+  3. fname: The name of the file that the tags belong to.
+
+In order to avoid possible future additions to the arguments resulting in an
+error it is recommended to add an additional vararg to the signature (see
+|a:0|).
+
+Here is an example that, when put into your vimrc, will emulate Tagbar's
+default statusline:
+>
+        function! TagbarStatusFunc(current, sort, fname, ...) abort
+            let colour = a:current ? '%#StatusLine#' : '%#StatusLineNC#'
+            return colour . '[' . a:sort . '] ' . a:fname
+        endfunction
+        let g:tagbar_status_func = 'TagbarStatusFunc'
+<
+
 ------------------------------------------------------------------------------
 HIGHLIGHT COLOURS                                           *tagbar-highlight*
 
@@ -663,6 +772,18 @@ Note that if there is an error when processing the current file no error
 message will be shown in order to not disrupt the statusline. If the function
 doesn't seem to work right open the Tagbar window to see any error messages.
 
+------------------------------------------------------------------------------
+IGNORING SPECIFIC FILES                                        *tagbar-ignore*
+
+You can ignore specific files by setting the |buffer-variable|
+"b:tagbar_ignore" to 1. This is best done with an |autocommand|:
+>
+    autocmd BufNewFile,BufReadPost foo.cpp let b:tagbar_ignore = 1
+<
+Note that autocommands are order-sensitive, so make sure that this autocommand
+gets defined before the ones that Tagbar defines so the variable will get
+found at the right time.
+
 ==============================================================================
 6. Extending Tagbar                                            *tagbar-extend*
 
@@ -793,6 +914,25 @@ ctagsargs: The arguments to be passed to the filetype-specific ctags program
            program output its data on stdout. Not used for the normal ctags
            program.
 
+           The value of ctagsargs may be a |List| of strings (a string for
+           each argument), or a single string (|expr-string|) of all the
+           arguments.
+
+           When the value of ctagsargs is a list, tagbar.vim takes care of
+           escaping each argument in the list as required for the current
+           'shell' type.
+
+           When the value of ctagsargs is a string, it must be properly
+           escaped (if required by the current shell type). The reason
+           tagbar.vim does not attempt to escape the string in this case is
+           because if there is a space, it is ambiguous as to whether the
+           space is delimiting an argument or included in the argument. To
+           avoid this amiguity, tagbar.vim expects the string to be already
+           escaped as required.
+
+           If special escaping is required for different OS shell types or if
+           in doubt, then it is recommended to define ctagsargs with a List.
+
 
 You then have to assign this dictionary to a variable in your vimrc with the
 name
@@ -961,6 +1101,30 @@ 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.
 
+Project-specific configuration~
+
+In addition to the normal global configuration it is also possible to have
+project-specific settings. This is mostly useful for additional ctags options,
+like for example macros to ignore. Or maybe you want to do things like folding
+certain tag kinds in some projects.
+
+In order to use this feature you need to create User |autocommand|s in an
+augroup called "TagbarProjects" and have it create a buffer-local variable
+called "b:tagbar_type". This variable has to hold a type definition just like
+the normal ones described in this chapter. This definition will then be
+applied only to the files matched by the autocommand.
+
+Note that there can be multiple definitions of the augroup with their own
+autocommands (for example in separate project directories); they will get
+merged automatically by Vim.
+
+Example:
+>
+    augroup TagbarProjects
+        autocmd User ~/myproject/*.c let b:tagbar_type = {'deffile' : '~/myproject/ctags.cnf'}
+    augroup END
+<
+
 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:
@@ -1067,6 +1231,20 @@ file.
 ==============================================================================
 8. History                                                    *tagbar-history*
 
+2.6 (2013-12-06)
+    - Added possibility to show tags in the preview window, either manually or
+      automatically.
+    - Allow customizing the statusline, see :help g:tagbar_status_func.
+    - Type configuration can now be project-specific.
+    - The keybindings in the Tagbar window are now configurable.
+    - Improvements to Ctags execution on Windows, thanks to Darcy Parker.
+    - Added function tagbar#currentfile() that returns the path to the file
+      currently being displayed in Tagbar, thanks to Zhao Cai.
+    - Added a :Tagbar command as an alias for :TagbarToggle.
+    - Added an way to ignore specific files in case they create problems.
+    - Optionally show line numbers in the Tagbar window.
+    - The usual bunch of small improvements and bugfixes.
+
 2.5 (2013-03-25)
     - New command :TagbarTogglePause to freeze Tagbar in its current state so
       you can switch to other files while keeping the old information
@@ -1219,11 +1397,16 @@ software.
 The folding technique was inspired by NERDTree by Martin Grenfell.
 
 Thanks to the following people for code contributions, feature suggestions etc:
+Peter Butkovic
+Zhao Cai
 Jan Christoph Ebersbach
 Vadim Fint
 Leandro Freitas
+Ingo Karkat
+Michael McClimon
 Seth Milliken
 Kien N
+Darcy Parker
 pielgrzym
 Taybin Rutkin
 Kian Ryan

plugin/tagbar.vim

@@ -4,7 +4,7 @@
 " Author:      Jan Larres <jan@majutsushi.net>
 " Licence:     Vim licence
 " Website:     http://majutsushi.github.com/tagbar/
-" Version:     2.5
+" Version:     2.6
 " Note:        This plugin was heavily inspired by the 'Taglist' plugin by
 "              Yegappan Lakshmanan and uses a small amount of code from it.
 "
@@ -42,49 +42,35 @@ if v:version == 700 && !has('patch167')
     finish
 endif
 
-if !exists('g:tagbar_left')
-    let g:tagbar_left = 0
-endif
+function! s:init_var(var, value) abort
+    if !exists('g:tagbar_' . a:var)
+        execute 'let g:tagbar_' . a:var . ' = ' . string(a:value)
+    endif
+endfunction
 
-if !exists('g:tagbar_width')
-    let g:tagbar_width = 40
-endif
+let s:options = [
+    \ ['autoclose', 0],
+    \ ['autofocus', 0],
+    \ ['autopreview', 0],
+    \ ['autoshowtag', 0],
+    \ ['compact', 0],
+    \ ['expand', 0],
+    \ ['foldlevel', 99],
+    \ ['indent', 2],
+    \ ['left', 0],
+    \ ['previewwin_pos', 'topleft'],
+    \ ['show_visibility', 1],
+    \ ['show_linenumbers', 0],
+    \ ['singleclick', 0],
+    \ ['sort', 1],
+    \ ['systemenc', &encoding],
+    \ ['width', 40],
+\ ]
 
-if !exists('g:tagbar_autoclose')
-    let g:tagbar_autoclose = 0
-endif
-
-if !exists('g:tagbar_autofocus')
-    let g:tagbar_autofocus = 0
-endif
-
-if !exists('g:tagbar_sort')
-    let g:tagbar_sort = 1
-endif
-
-if !exists('g:tagbar_compact')
-    let g:tagbar_compact = 0
-endif
-
-if !exists('g:tagbar_indent')
-    let g:tagbar_indent = 2
-endif
-
-if !exists('g:tagbar_show_visibility')
-    let g:tagbar_show_visibility = 1
-endif
-
-if !exists('g:tagbar_expand')
-    let g:tagbar_expand = 0
-endif
-
-if !exists('g:tagbar_singleclick')
-    let g:tagbar_singleclick = 0
-endif
-
-if !exists('g:tagbar_foldlevel')
-    let g:tagbar_foldlevel = 99
-endif
+for [opt, val] in s:options
+    call s:init_var(opt, val)
+endfor
+unlet s:options
 
 if !exists('g:tagbar_iconchars')
     if has('multi_byte') && has('unix') && &encoding == 'utf-8' &&
@@ -95,13 +81,31 @@ if !exists('g:tagbar_iconchars')
     endif
 endif
 
-if !exists('g:tagbar_autoshowtag')
-    let g:tagbar_autoshowtag = 0
-endif
+let s:keymaps = [
+    \ ['jump',       '<CR>'],
+    \ ['preview',    'p'],
+    \ ['previewwin', 'P'],
+    \ ['nexttag',    '<C-N>'],
+    \ ['prevtag',    '<C-P>'],
+    \ ['showproto',  '<Space>'],
+    \
+    \ ['openfold',      ['+', '<kPlus>', 'zo']],
+    \ ['closefold',     ['-', '<kMinus>', 'zc']],
+    \ ['togglefold',    ['o', 'za']],
+    \ ['openallfolds',  ['*', '<kMultiply>', 'zR']],
+    \ ['closeallfolds', ['=', 'zM']],
+    \
+    \ ['togglesort', 's'],
+    \ ['zoomwin',    'x'],
+    \ ['close',      'q'],
+    \ ['help',       '<F1>'],
+\ ]
 
-if !exists('g:tagbar_systemenc')
-    let g:tagbar_systemenc = &encoding
-endif
+for [map, key] in s:keymaps
+    call s:init_var('map_' . map, key)
+    unlet key
+endfor
+unlet s:keymaps
 
 augroup TagbarSession
     autocmd!
@@ -109,6 +113,7 @@ augroup TagbarSession
 augroup END
 
 " Commands {{{1
+command! -nargs=0 Tagbar              call tagbar#ToggleWindow()
 command! -nargs=0 TagbarToggle        call tagbar#ToggleWindow()
 command! -nargs=? TagbarOpen          call tagbar#OpenWindow(<f-args>)
 command! -nargs=0 TagbarOpenAutoClose call tagbar#OpenWindow('fcj')
@@ -119,7 +124,7 @@ command! -nargs=? TagbarCurrentTag    echo tagbar#currenttag('%s', 'No current t
 command! -nargs=1 TagbarGetTypeConfig call tagbar#gettypeconfig(<f-args>)
 command! -nargs=? TagbarDebug         call tagbar#StartDebug(<f-args>)
 command! -nargs=0 TagbarDebugEnd      call tagbar#StopDebug()
-command! -nargs=0 TagbarTogglePause   call tagbar#PauseAutocommands()
+command! -nargs=0 TagbarTogglePause   call tagbar#toggle_pause()
 
 " Modeline {{{1
 " vim: ts=8 sw=4 sts=4 et foldenable foldmethod=marker foldcolumn=1

syntax/tagbar.vim

@@ -3,48 +3,45 @@
 " Author:      Jan Larres <jan@majutsushi.net>
 " Licence:     Vim licence
 " Website:     http://majutsushi.github.com/tagbar/
-" Version:     2.5
+" Version:     2.6
 
 scriptencoding utf-8
 
 if exists("b:current_syntax")
-  finish
+    finish
 endif
 
-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
-
-let s:pattern = '\([' . s:ic . s:io . '] \?\)\@<=[^-+: ]\+[^:]\+$'
+let s:ics = escape(join(g:tagbar_iconchars, ''), ']^\-')
+let s:pattern = '\(^[' . s:ics . '] \?\)\@<=[^-+: ]\+[^:]\+$'
 execute "syntax match TagbarKind '" . s:pattern . "'"
 
-let s:pattern = '\([' . s:ic . s:io . '][-+# ]\?\)\@<=[^*(]\+\(\*\?\(([^)]\+)\)\? :\)\@='
+let s:pattern = '\(\S\@<![' . s:ics . '][-+# ]\?\)\@<=[^*(]\+\(\*\?\(([^)]\+)\)\? :\)\@='
 execute "syntax match TagbarScope '" . s:pattern . "'"
 
-let s:pattern = '[' . s:ic . s:io . ']\([-+# ]\?\)\@='
+let s:pattern = '\S\@<![' . s:ics . ']\([-+# ]\?\)\@='
 execute "syntax match TagbarFoldIcon '" . s:pattern . "'"
 
-let s:pattern = '\([' . s:ic . s:io . ' ]\)\@<=+\([^-+# ]\)\@='
+let s:pattern = '\(\S\@<![' . s:ics . ' ]\)\@<=+\([^-+# ]\)\@='
 execute "syntax match TagbarVisibilityPublic '" . s:pattern . "'"
-let s:pattern = '\([' . s:ic . s:io . ' ]\)\@<=#\([^-+# ]\)\@='
+let s:pattern = '\(\S\@<![' . s:ics . ' ]\)\@<=#\([^-+# ]\)\@='
 execute "syntax match TagbarVisibilityProtected '" . s:pattern . "'"
-let s:pattern = '\([' . s:ic . s:io . ' ]\)\@<=-\([^-+# ]\)\@='
+let s:pattern = '\(\S\@<![' . s:ics . ' ]\)\@<=-\([^-+# ]\)\@='
 execute "syntax match TagbarVisibilityPrivate '" . s:pattern . "'"
 
 unlet s:pattern
 
+syntax match TagbarHelp      '^".*' contains=TagbarHelpKey,TagbarHelpTitle
+syntax match TagbarHelpKey   '" \zs.*\ze:' contained
+syntax match TagbarHelpTitle '" \zs-\+ \w\+ -\+' contained
+
 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 TagbarHelp       Comment
+highlight default link TagbarHelpKey    Identifier
+highlight default link TagbarHelpTitle  PreProc
 highlight default link TagbarKind       Identifier
 highlight default link TagbarNestedKind TagbarKind
 highlight default link TagbarScope      Title