VimPlugin: TagBar

TagBar leverages ctags to create a table-of-contents of your current source file.

Documentation

github	https://github.com/preservim/tagbar
wiki: languages	https://github.com/preservim/tagbar/wiki

Install

Prerequisites

• requires universal-ctags (updated fork of exuberant-ctags)

See Also ctags

pacman -S ctags              # Archlinux
pkg install universal-ctags  # FreeBSD

Install

Plug 'https://github.com/preservim/tagbar'  " vim-plug

Usage

Buffer Commands

:TagbarToggle    "open/close tagbar

TagBar Commands

<Enter>          "open section under cursor, and set cursor in file
<space>          "display line with arguments, etc
p                "show section under cursor, without moving cursor
s                "toggle sort alphabetical vs order in file

"" tagbar also makes use of folds, so you can fold/unfold table of contents ""

Languages

Builtin

ctags --list-languages      # list all ctags supported languages
ctags --list-kinds=${LANG}  # list symbols available for language

When a language is builtin to ctags,
if it does not show up in tagbar, you can extend it to do so.

let g:tagbar_type_${vim_type} = {  " vim-type as appears in `:set filetype?`
\   'ctagstype': 'sh',             " as appears in ctags --list-languages, but lowercased
\   'kinds': [                     " as appears in ctags --list-kinds=${LANG}
\       'f:functions',
\       'a:aliases',
\   ]
\ }

Custom Languages

Ctags can be extended to add support for new/custom languages. You can then add them to tagbar.

Define custom ctags language

# ~/.config/ctags/graphql.ctags
# https://gist.github.com/hoop33/b0a33cf8fdcf4d64689f58efed75c15e

--langdef=graphql
--langmap=graphql:.graphql
--regex-graphql=/^[ \t]*enum[ \t]+([_A-Za-z][_0-9A-Za-z]*)/\1/e,enum/
--regex-graphql=/^[ \t]*query[ \t]+([_A-Za-z][_0-9A-Za-z]*)/\1/q,query/
--regex-graphql=/^[ \t]*fragment[ \t]+([_A-Za-z][_0-9A-Za-z]*)/\1/f,fragment/
--regex-graphql=/^[ \t]*type[ \t]+([_A-Za-z][_0-9A-Za-z]*)/\1/t,type/
--regex-graphql=/^[ \t]*input[ \t]+([_A-Za-z][_0-9A-Za-z]*)/\1/i,input/
--regex-graphql=/^[ \t]*mutation[ \t]+([_A-Za-z][_0-9A-Za-z]*)/\1/m,mutation/
--regex-graphql=/^[ \t]*interface[ \t]+([_A-Za-z][_0-9A-Za-z]*)/\1/i,interface/

Define language in tagbar

let g:tagbar_type_graphql = {
    \ 'kinds': [
        \ 'e:enum',
        \ 'q:query',
        \ 'f:fragment',
        \ 't:type',
        \ 'i:input',
        \ 'm:mutation',
        \ 'i:interface',
    \ ]
\ }

Third Party

rst2ctags	ReStructuredText	https://github.com/jszakmeister/rst2ctags
tagbar-markdown.vim	Markdown	https://github.com/tenfyzhong/tagbar-markdown.vim
marktag	Markdown	https://github.com/t4ku/marktag
ripper-tags	Ruby	https://github.com/tmm1/ripper-tags

Troubleshooting

TagBar: Error detected while processing function <SNR>217_ShowPrototype

See https://github.com/majutsushi/tagbar/issues/219

This was caused by my use of rippertags, and the tags file I generated with it(?).
Deleting it seems to have fixed issues.

It is possible this was caused by an out-of-date rippertags .tags file?