1 *taglist-plus.txt* Plugin for browsing source code
3 Author: Yegappan Lakshmanan (yegappan AT yahoo DOT com)
4 Modified By: Jezreel Ng (jezreel AT gmail DOT com)
5 For Vim version 6.0 and above
7 1. Overview |taglist-intro|
8 2. Requirements |taglist-requirements|
9 3. Installation |taglist-install|
10 4. Usage |taglist-using|
11 5. Options |taglist-options|
12 6. Commands |taglist-commands|
13 7. Global functions |taglist-functions|
14 8. Extending |taglist-extend|
16 10. License |taglist-license|
17 11. Todo |taglist-todo|
19 ==============================================================================
23 The "Tag List" plugin is a source code browser plugin for Vim. This plugin
24 allows you to efficiently browse through source code files for different
25 programming languages. The "Tag List" plugin provides the following features:
27 * Displays the tags (functions, classes, structures, variables, etc.)
28 defined in a file in a vertically or horizontally split Vim window.
29 * In GUI Vim, optionally displays the tags in the Tags drop-down menu and
31 * Automatically updates the taglist window as you switch between
32 files/buffers. As you open new files, the tags defined in the new files
33 are added to the existing file list and the tags defined in all the
34 files are displayed grouped by the filename.
35 * When a tag name is selected from the taglist window, positions the
36 cursor at the definition of the tag in the source file.
37 * Automatically highlights the current tag name.
38 * Groups the tags by their type and displays them in a foldable tree.
39 * Can display the prototype and scope of a tag.
40 * Can optionally display the tag prototype instead of the tag name in the
42 * The tag list can be sorted either by name or by chronological order.
43 * Supports the following language files: Assembly, ASP, Awk, Beta, C,
44 C++, C#, Cobol, Eiffel, Erlang, Fortran, HTML, Java, Javascript, Lisp,
45 Lua, Make, Pascal, Perl, PHP, Python, Rexx, Ruby, Scheme, Shell, Slang,
46 SML, Sql, TCL, Verilog, Vim and Yacc.
47 * Can be easily extended to support new languages. Support for
48 existing languages can be modified easily.
49 * Provides functions to display the current tag name in the Vim status
50 line or the window title bar.
51 * The list of tags and files in the taglist can be saved and
52 restored across Vim sessions.
53 * Provides commands to get the name and prototype of the current tag.
54 * Runs in both console/terminal and GUI versions of Vim.
55 * Works with the winmanager plugin. Using the winmanager plugin, you
56 can use Vim plugins like the file explorer, buffer explorer and the
57 taglist plugin at the same time like an IDE.
58 * Can be used in both Unix and MS-Windows systems.
60 ==============================================================================
61 *taglist-requirements*
64 The taglist plugin requires the following:
66 * Vim version 6.0 and above
67 * Exuberant ctags 5.0 and above
69 The taglist plugin will work on all the platforms where the exuberant ctags
70 utility and Vim are supported (this includes MS-Windows and Unix based
73 The taglist plugin relies on the exuberant ctags utility to dynamically
74 generate the tag listing. The exuberant ctags utility must be installed in
75 your system to use this plugin. The exuberant ctags utility is shipped with
76 most of the Linux distributions. You can download the exuberant ctags utility
79 http://ctags.sourceforge.net
81 The taglist plugin doesn't use or create a tags file and there is no need to
82 create a tags file to use this plugin. The taglist plugin will not work with
83 the GNU ctags or the Unix ctags utility.
85 This plugin relies on the Vim "filetype" detection mechanism to determine the
86 type of the current file. You have to turn on the Vim filetype detection by
87 adding the following line to your .vimrc file:
91 The taglist plugin will not work if you run Vim in the restricted mode (using
92 the -Z command-line argument).
94 The taglist plugin uses the Vim system() function to invoke the exuberant
95 ctags utility. If Vim is compiled without the system() function then you
96 cannot use the taglist plugin. Some of the Linux distributions (Suse) compile
97 Vim without the system() function for security reasons.
99 ==============================================================================
103 1. Download the taglist.zip file and unzip the files to the $HOME/.vim or the
104 $HOME/vimfiles or the $VIM/vimfiles directory. After this step, you should
105 have the following two files (the directory structure should be preserved):
107 plugin/taglist.vim - main taglist plugin file
108 doc/taglist.txt - documentation (help) file
110 Refer to the |add-plugin|and |'runtimepath'| Vim help pages for more
111 details about installing Vim plugins.
112 2. Change to the $HOME/.vim/doc or $HOME/vimfiles/doc or $VIM/vimfiles/doc
113 directory, start Vim and run the ":helptags ." command to process the
114 taglist help file. Without this step, you cannot jump to the taglist help
116 3. If the exuberant ctags utility is not present in one of the directories in
117 the PATH environment variable, then set the 'Tlist_Ctags_Cmd' variable to
118 point to the location of the exuberant ctags utility (not to the directory)
120 4. If you are running a terminal/console version of Vim and the terminal
121 doesn't support changing the window width then set the
122 'Tlist_Inc_Winwidth' variable to 0 in the .vimrc file.
124 6. You can now use the ":TlistToggle" command to open/close the taglist
125 window. You can use the ":help taglist" command to get more information
126 about using the taglist plugin.
128 To uninstall the taglist plugin, remove the plugin/taglist.vim and
129 doc/taglist.txt files from the $HOME/.vim or $HOME/vimfiles directory.
131 ==============================================================================
135 The taglist plugin can be used in several different ways.
137 1. You can keep the taglist window open during the entire editing session. On
138 opening the taglist window, the tags defined in all the files in the Vim
139 buffer list will be displayed in the taglist window. As you edit files, the
140 tags defined in them will be added to the taglist window. You can select a
141 tag from the taglist window and jump to it. The current tag will be
142 highlighted in the taglist window. You can close the taglist window when
143 you no longer need the window.
144 2. You can configure the taglist plugin to process the tags defined in all the
145 edited files always. In this configuration, even if the taglist window is
146 closed and the taglist menu is not displayed, the taglist plugin will
147 processes the tags defined in newly edited files. You can then open the
148 taglist window only when you need to select a tag and then automatically
149 close the taglist window after selecting the tag.
150 3. You can configure the taglist plugin to display only the tags defined in
151 the current file in the taglist window. By default, the taglist plugin
152 displays the tags defined in all the files in the Vim buffer list. As you
153 switch between files, the taglist window will be refreshed to display only
154 the tags defined in the current file.
155 4. In GUI Vim, you can use the Tags pull-down and popup menu created by the
156 taglist plugin to display the tags defined in the current file and select a
157 tag to jump to it. You can use the menu without opening the taglist window.
158 By default, the Tags menu is disabled.
159 5. You can configure the taglist plugin to display the name of the current tag
160 in the Vim window status line or in the Vim window title bar. For this to
161 work without the taglist window or menu, you need to configure the taglist
162 plugin to process the tags defined in a file always.
163 6. You can save the tags defined in multiple files to a taglist session file
164 and load it when needed. You can also configure the taglist plugin to not
165 update the taglist window when editing new files. You can then manually add
166 files to the taglist window.
168 Opening the taglist window~
169 You can open the taglist window using the ":TlistOpen" or the ":TlistToggle"
170 commands. The ":TlistOpen" command opens the taglist window and jumps to it.
171 The ":TlistToggle" command opens or closes (toggle) the taglist window and the
172 cursor remains in the current window. If the 'Tlist_GainFocus_On_ToggleOpen'
173 variable is set to 1, then the ":TlistToggle" command opens the taglist window
174 and moves the cursor to the taglist window.
176 You can map a key to invoke these commands. For example, the following command
177 creates a normal mode mapping for the <F8> key to toggle the taglist window.
179 nnoremap <silent> <F8> :TlistToggle<CR>
181 Add the above mapping to your ~/.vimrc or $HOME/_vimrc file.
183 To automatically open the taglist window on Vim startup, set the
184 'Tlist_Auto_Open' variable to 1.
186 You can also open the taglist window on startup using the following command
191 Closing the taglist window~
192 You can close the taglist window from the taglist window by pressing 'q' or
193 using the Vim ":q" command. You can also use any of the Vim window commands to
194 close the taglist window. Invoking the ":TlistToggle" command when the taglist
195 window is opened, closes the taglist window. You can also use the
196 ":TlistClose" command to close the taglist window.
198 To automatically close the taglist window when a tag or file is selected, you
199 can set the 'Tlist_Close_On_Select' variable to 1. To exit Vim when only the
200 taglist window is present, set the 'Tlist_Exit_OnlyWindow' variable to 1.
202 Jumping to a tag or a file~
203 You can select a tag in the taglist window either by pressing the <Enter> key
204 or by double clicking the tag name using the mouse. To jump to a tag on a
205 single mouse click set the 'Tlist_Use_SingleClick' variable to 1.
207 If the selected file is already opened in a window, then the cursor is moved
208 to that window. If the file is not currently opened in a window then the file
209 is opened in the window used by the taglist plugin to show the previously
210 selected file. If there are no usable windows, then the file is opened in a
211 new window. The file is not opened in special windows like the quickfix
212 window, preview window and windows containing buffer with the 'buftype' option
215 To jump to the tag in a new window, press the 'o' key. To open the file in the
216 previous window (Ctrl-W_p) use the 'P' key. You can press the 'p' key to jump
217 to the tag but still keep the cursor in the taglist window (preview).
219 To open the selected file in a tab, use the 't' key. If the file is already
220 present in a tab then the cursor is moved to that tab otherwise the file is
221 opened in a new tab. To jump to a tag in a new tab press Ctrl-t. The taglist
222 window is automatically opened in the newly created tab.
224 Instead of jumping to a tag, you can open a file by pressing the <Enter> key
225 or by double clicking the file name using the mouse.
227 In the taglist window, you can use the [[ or <Backspace> key to jump to the
228 beginning of the previous file. You can use the ]] or <Tab> key to jump to the
229 beginning of the next file. When you reach the first or last file, the search
230 wraps around and the jumps to the next/previous file.
232 Highlighting the current tag~
233 The taglist plugin automatically highlights the name of the current tag in the
234 taglist window. The Vim |CursorHold| autocmd event is used for this. If the
235 current tag name is not visible in the taglist window, then the taglist window
236 contents are scrolled to make that tag name visible. You can also use the
237 ":TlistHighlightTag" command to force the highlighting of the current tag.
239 The tag name is highlighted if no activity is performed for |'updatetime'|
240 milliseconds. The default value for this Vim option is 4 seconds. To avoid
241 unexpected problems, you should not set the |'updatetime'| option to a very
244 To disable the automatic highlighting of the current tag name in the taglist
245 window, set the 'Tlist_Auto_Highlight_Tag' variable to zero.
247 When entering a Vim buffer/window, the taglist plugin automatically highlights
248 the current tag in that buffer/window. If you like to disable the automatic
249 highlighting of the current tag when entering a buffer, set the
250 'Tlist_Highlight_Tag_On_BufEnter' variable to zero.
252 Adding files to the taglist~
253 When the taglist window is opened, all the files in the Vim buffer list are
254 processed and the supported files are added to the taglist. When you edit a
255 file in Vim, the taglist plugin automatically processes this file and adds it
256 to the taglist. If you close the taglist window, the tag information in the
259 To process files even when the taglist window is not open, set the
260 'Tlist_Process_File_Always' variable to 1.
262 You can manually add multiple files to the taglist without opening them using
263 the ":TlistAddFiles" and the ":TlistAddFilesRecursive" commands.
265 For example, to add all the C files in the /my/project/dir directory to the
266 taglist, you can use the following command:
268 :TlistAddFiles /my/project/dir/*.c
270 Note that when adding several files with a large number of tags or a large
271 number of files, it will take several seconds to several minutes for the
272 taglist plugin to process all the files. You should not interrupt the taglist
273 plugin by pressing <CTRL-C>.
275 You can recursively add multiple files from a directory tree using the
276 ":TlistAddFilesRecursive" command:
278 :TlistAddFilesRecursive /my/project/dir *.c
280 This command takes two arguments. The first argument specifies the directory
281 from which to recursively add the files. The second optional argument
282 specifies the wildcard matching pattern for selecting the files to add. The
283 default pattern is * and all the files are added.
285 Displaying tags for only one file~
286 The taglist window displays the tags for all the files in the Vim buffer list
287 and all the manually added files. To display the tags for only the current
288 active buffer, set the 'Tlist_Show_One_File' variable to 1.
290 Removing files from the taglist~
291 You can remove a file from the taglist window, by pressing the 'd' key when the
292 cursor is on one of the tags listed for the file in the taglist window. The
293 removed file will no longer be displayed in the taglist window in the current
294 Vim session. To again display the tags for the file, open the file in a Vim
295 window and then use the ":TlistUpdate" command or use ":TlistAddFiles" command
296 to add the file to the taglist.
298 When a buffer is removed from the Vim buffer list using the ":bdelete" or the
299 ":bwipeout" command, the taglist is updated to remove the stored information
302 Updating the tags displayed for a file~
303 The taglist plugin keeps track of the modification time of a file. When the
304 modification time changes (the file is modified), the taglist plugin
305 automatically updates the tags listed for that file. The modification time of
306 a file is checked when you enter a window containing that file or when you
309 You can also update or refresh the tags displayed for a file by pressing the
310 "u" key in the taglist window. If an existing file is modified, after the file
311 is saved, the taglist plugin automatically updates the tags displayed for the
314 You can also use the ":TlistUpdate" command to update the tags for the current
315 buffer after you made some changes to it. You should save the modified buffer
316 before you update the taglist window. Otherwise the listed tags will not
317 include the new tags created in the buffer.
319 If you have deleted the tags displayed for a file in the taglist window using
320 the 'd' key, you can again display the tags for that file using the
321 ":TlistUpdate" command.
323 Controlling the taglist updates~
324 To disable the automatic processing of new files or modified files, you can
325 set the 'Tlist_Auto_Update' variable to zero. When this variable is set to
326 zero, the taglist is updated only when you use the ":TlistUpdate" command or
327 the ":TlistAddFiles" or the ":TlistAddFilesRecursive" commands. You can use
328 this option to control which files are added to the taglist.
330 You can use the ":TlistLock" command to lock the taglist contents. After this
331 command is executed, new files are not automatically added to the taglist.
332 When the taglist is locked, you can use the ":TlistUpdate" command to add the
333 current file or the ":TlistAddFiles" or ":TlistAddFilesRecursive" commands to
334 add new files to the taglist. To unlock the taglist, use the ":TlistUnlock"
337 Displaying the tag prototype~
338 To display the prototype of the tag under the cursor in the taglist window,
339 press the space bar. If you place the cursor on a tag name in the taglist
340 window, then the tag prototype is displayed at the Vim status line after
341 |'updatetime'| milliseconds. The default value for the |'updatetime'| Vim
344 You can get the name and prototype of a tag without opening the taglist window
345 and the taglist menu using the ":TlistShowTag" and the ":TlistShowPrototype"
346 commands. These commands will work only if the current file is already present
347 in the taglist. To use these commands without opening the taglist window, set
348 the 'Tlist_Process_File_Always' variable to 1.
350 You can use the ":TlistShowTag" command to display the name of the tag at or
351 before the specified line number in the specified file. If the file name and
352 line number are not supplied, then this command will display the name of the
353 current tag. For example,
356 :TlistShowTag myfile.java 100
358 You can use the ":TlistShowPrototype" command to display the prototype of the
359 tag at or before the specified line number in the specified file. If the file
360 name and the line number are not supplied, then this command will display the
361 prototype of the current tag. For example,
364 :TlistShowPrototype myfile.c 50
366 In the taglist window, when the mouse is moved over a tag name, the tag
367 prototype is displayed in a balloon. This works only in GUI versions where
368 balloon evaluation is supported.
370 Taglist window contents~
371 The taglist window contains the tags defined in various files in the taglist
372 grouped by the filename and by the tag type (variable, function, class, etc.).
373 For tags with scope information (like class members, structures inside
374 structures, etc.), the scope information is displayed in square brackets "[]"
377 The contents of the taglist buffer/window are managed by the taglist plugin.
378 The |'filetype'| for the taglist buffer is set to 'taglist'. The Vim
379 |'modifiable'| option is turned off for the taglist buffer. You should not
380 manually edit the taglist buffer, by setting the |'modifiable'| flag. If you
381 manually edit the taglist buffer contents, then the taglist plugin will be out
382 of sync with the taglist buffer contents and the plugin will no longer work
383 correctly. To redisplay the taglist buffer contents again, close the taglist
384 window and reopen it.
386 Opening and closing the tag and file tree~
387 In the taglist window, the tag names are displayed as a foldable tree using
388 the Vim folding support. You can collapse the tree using the '-' key or using
389 the Vim |zc| fold command. You can open the tree using the '+' key or using
390 the Vim |zo| fold command. You can open all the folds using the '*' key or
391 using the Vim |zR| fold command. You can also use the mouse to open/close the
392 folds. You can close all the folds using the '=' key. You should not manually
393 create or delete the folds in the taglist window.
395 To automatically close the fold for the inactive files/buffers and open only
396 the fold for the current buffer in the taglist window, set the
397 'Tlist_File_Fold_Auto_Close' variable to 1.
399 Sorting the tags for a file~
400 The tags displayed in the taglist window can be sorted either by their name or
401 by their chronological order. The default sorting method is by the order in
402 which the tags appear in a file. You can change the default sort method by
403 setting the 'Tlist_Sort_Type' variable to either "name" or "order". You can
404 sort the tags by their name by pressing the "s" key in the taglist window. You
405 can again sort the tags by their chronological order using the "s" key. Each
406 file in the taglist window can be sorted using different order.
408 Zooming in and out of the taglist window~
409 You can press the 'x' key in the taglist window to maximize the taglist
410 window width/height. The window will be maximized to the maximum possible
411 width/height without closing the other existing windows. You can again press
412 'x' to restore the taglist window to the default width/height.
416 A taglist session refers to the group of files and their tags stored in the
417 taglist in a Vim session.
419 You can save and restore a taglist session (and all the displayed tags) using
420 the ":TlistSessionSave" and ":TlistSessionLoad" commands.
422 To save the information about the tags and files in the taglist to a file, use
423 the ":TlistSessionSave" command and specify the filename:
425 :TlistSessionSave <file name>
427 To load a saved taglist session, use the ":TlistSessionLoad" command: >
429 :TlistSessionLoad <file name>
431 When you load a taglist session file, the tags stored in the file will be
432 added to the tags already stored in the taglist.
434 The taglist session feature can be used to save the tags for large files or a
435 group of frequently used files (like a project). By using the taglist session
436 file, you can minimize the amount to time it takes to load/refresh the taglist
439 You can create more than one taglist session file for multiple groups of
442 Displaying the tag name in the Vim status line or the window title bar~
443 You can use the Tlist_Get_Tagname_By_Line() function provided by the taglist
444 plugin to display the current tag name in the Vim status line or the window
445 title bar. Similarly, you can use the Tlist_Get_Tag_Prototype_By_Line()
446 function to display the current tag prototype in the Vim status line or the
449 For example, the following command can be used to display the current tag name
452 :set statusline=%<%f%=%([%{Tlist_Get_Tagname_By_Line()}]%)
454 The following command can be used to display the current tag name in the
457 :set title titlestring=%<%f\ %([%{Tlist_Get_Tagname_By_Line()}]%)
459 Note that the current tag name can be displayed only after the file is
460 processed by the taglist plugin. For this, you have to either set the
461 'Tlist_Process_File_Always' variable to 1 or open the taglist window or use
462 the taglist menu. For more information about configuring the Vim status line,
463 refer to the documentation for the Vim |'statusline'| option.
465 Changing the taglist window highlighting~
466 The following Vim highlight groups are defined and used to highlight the
467 various entities in the taglist window:
469 TagListTagName - Used for tag names
470 TagListTagScope - Used for tag scope
471 TagListTitle - Used for tag titles
472 TagListComment - Used for comments
473 TagListFileName - Used for filenames
475 By default, these highlight groups are linked to the standard Vim highlight
476 groups. If you want to change the colors used for these highlight groups,
477 prefix the highlight group name with 'My' and define it in your .vimrc or
478 .gvimrc file: MyTagListTagName, MyTagListTagScope, MyTagListTitle,
479 MyTagListComment and MyTagListFileName. For example, to change the colors
480 used for tag names, you can use the following command:
482 :highlight MyTagListTagName guifg=blue ctermfg=blue
484 Controlling the taglist window~
485 To use a horizontally split taglist window, instead of a vertically split
486 window, set the 'Tlist_Use_Horiz_Window' variable to 1.
488 To use a vertically split taglist window on the rightmost side of the Vim
489 window, set the 'Tlist_Use_Right_Window' variable to 1.
491 You can specify the width of the vertically split taglist window, by setting
492 the 'Tlist_WinWidth' variable. You can specify the height of the horizontally
493 split taglist window, by setting the 'Tlist_WinHeight' variable.
495 When opening a vertically split taglist window, the Vim window width is
496 increased to accommodate the new taglist window. When the taglist window is
497 closed, the Vim window is reduced. To disable this, set the
498 'Tlist_Inc_Winwidth' variable to zero.
500 To reduce the number of empty lines in the taglist window, set the
501 'Tlist_Compact_Format' variable to 1.
503 To not display the Vim fold column in the taglist window, set the
504 'Tlist_Enable_Fold_Column' variable to zero.
506 To display the tag prototypes instead of the tag names in the taglist window,
507 set the 'Tlist_Display_Prototype' variable to 1.
509 To not display the scope of the tags next to the tag names, set the
510 'Tlist_Display_Tag_Scope' variable to zero.
513 Taglist window key list~
514 The following table lists the description of the keys that can be used
515 in the taglist window.
519 <CR> Jump to the location where the tag under cursor is
521 o Jump to the location where the tag under cursor is
522 defined in a new window.
523 P Jump to the tag in the previous (Ctrl-W_p) window.
524 p Display the tag definition in the file window and
525 keep the cursor in the taglist window itself.
526 t Jump to the tag in a new tab. If the file is already
527 opened in a tab, move to that tab.
528 Ctrl-t Jump to the tag in a new tab.
529 <Space> Display the prototype of the tag under the cursor.
530 For file names, display the full path to the file,
531 file type and the number of tags. For tag types, display the
532 tag type and the number of tags.
533 u Update the tags listed in the taglist window
534 s Change the sort order of the tags (by name or by order)
535 d Remove the tags for the file under the cursor
536 x Zoom-in or Zoom-out the taglist window
541 [[ Jump to the beginning of the previous file
542 <Backspace> Jump to the beginning of the previous file
543 ]] Jump to the beginning of the next file
544 <Tab> Jump to the beginning of the next file
545 q Close the taglist window
548 The above keys will work in both the normal mode and the insert mode.
552 When using GUI Vim, the taglist plugin can display the tags defined in the
553 current file in the drop-down menu and the popup menu. By default, this
554 feature is turned off. To turn on this feature, set the 'Tlist_Show_Menu'
557 You can jump to a tag by selecting the tag name from the menu. You can use the
558 taglist menu independent of the taglist window i.e. you don't need to open the
559 taglist window to get the taglist menu.
561 When you switch between files/buffers, the taglist menu is automatically
562 updated to display the tags defined in the current file/buffer.
564 The tags are grouped by their type (variables, functions, classes, methods,
565 etc.) and displayed as a separate sub-menu for each type. If all the tags
566 defined in a file are of the same type (e.g. functions), then the sub-menu is
569 If the number of items in a tag type submenu exceeds the value specified by
570 the 'Tlist_Max_Submenu_Items' variable, then the submenu will be split into
571 multiple submenus. The default setting for 'Tlist_Max_Submenu_Items' is 25.
572 The first and last tag names in the submenu are used to form the submenu name.
573 The menu items are prefixed by alpha-numeric characters for easy selection by
576 If the popup menu support is enabled (the |'mousemodel'| option contains
577 "popup"), then the tags menu is added to the popup menu. You can access
578 the popup menu by right clicking on the GUI window.
580 You can regenerate the tags menu by selecting the 'Tags->Refresh menu' entry.
581 You can sort the tags listed in the menu either by name or by order by
582 selecting the 'Tags->Sort menu by->Name/Order' menu entry.
584 You can tear-off the Tags menu and keep it on the side of the Vim window
585 for quickly locating the tags.
587 Using the taglist plugin with the winmanager plugin~
588 You can use the taglist plugin with the winmanager plugin. This will allow you
589 to use the file explorer, buffer explorer and the taglist plugin at the same
590 time in different windows. To use the taglist plugin with the winmanager
591 plugin, set 'TagList' in the 'winManagerWindowLayout' variable. For example,
592 to use the file explorer plugin and the taglist plugin at the same time, use
593 the following setting: >
595 let winManagerWindowLayout = 'FileExplorer|TagList'
598 If you have installed the taglist help file (this file), then you can use the
599 Vim ":help taglist-<keyword>" command to get help on the various taglist
602 You can press the <F1> key in the taglist window to display the help
603 information about using the taglist window. If you again press the <F1> key,
604 the help information is removed from the taglist window.
607 Debugging the taglist plugin~
608 You can use the ":TlistDebug" command to enable logging of the debug messages
609 from the taglist plugin. To display the logged debug messages, you can use the
610 ":TlistMessages" command. To disable the logging of the debug messages, use
611 the ":TlistUndebug" command.
613 You can specify a file name to the ":TlistDebug" command to log the debug
614 messages to a file. Otherwise, the debug messages are stored in a script-local
615 variable. In the later case, to minimize memory usage, only the last 3000
616 characters from the debug messages are stored.
618 ==============================================================================
622 A number of Vim variables control the behavior of the taglist plugin. These
623 variables are initialized to a default value. By changing these variables you
624 can change the behavior of the taglist plugin. You need to change these
625 settings only if you want to change the behavior of the taglist plugin. You
626 should use the |:let| command in your .vimrc file to change the setting of any
629 The configurable taglist variables are listed below. For a detailed
630 description of these variables refer to the text below this table.
632 |'Tlist_Auto_Highlight_Tag'| Automatically highlight the current tag in the
634 |'Tlist_Auto_Open'| Open the taglist window when Vim starts.
635 |'Tlist_Auto_Update'| Automatically update the taglist to include
637 |'Tlist_Close_On_Select'| Close the taglist window when a file or tag is
639 |'Tlist_Compact_Format'| Remove extra information and blank lines from
641 |'Tlist_Ctags_Cmd'| Specifies the path to the ctags utility.
642 |'Tlist_Display_Prototype'| Show prototypes and not tags in the taglist
644 |'Tlist_Display_Tag_Scope'| Show tag scope next to the tag name.
645 |'Tlist_Enable_Fold_Column'| Show the fold indicator column in the taglist
647 |'Tlist_Exit_OnlyWindow'| Close Vim if the taglist is the only window.
648 |'Tlist_File_Fold_Auto_Close'| Close tag folds for inactive buffers.
649 |'Tlist_GainFocus_On_ToggleOpen'|
650 Jump to taglist window on open.
651 |'Tlist_Highlight_Tag_On_BufEnter'|
652 On entering a buffer, automatically highlight
654 |'Tlist_Inc_Winwidth'| Increase the Vim window width to accommodate
656 |'Tlist_Max_Submenu_Items'| Maximum number of items in a tags sub-menu.
657 |'Tlist_Max_Tag_Length'| Maximum tag length used in a tag menu entry.
658 |'Tlist_Process_File_Always'| Process files even when the taglist window is
660 |'Tlist_Show_Menu'| Display the tags menu.
661 |'Tlist_Show_One_File'| Show tags for the current buffer only.
662 |'Tlist_Sort_Type'| Sort method used for arranging the tags.
663 |'Tlist_Use_Horiz_Window'| Use a horizontally split window for the
665 |'Tlist_Use_Right_Window'| Place the taglist window on the right side.
666 |'Tlist_Use_SingleClick'| Single click on a tag jumps to it.
667 |'Tlist_WinHeight'| Horizontally split taglist window height.
668 |'Tlist_WinWidth'| Vertically split taglist window width.
669 |'Tlist_javascript_Hide_Extras'| Hide extra tag data produced by jsctags.
671 *'Tlist_Auto_Highlight_Tag'*
672 Tlist_Auto_Highlight_Tag~
673 The taglist plugin will automatically highlight the current tag in the taglist
674 window. If you want to disable this, then you can set the
675 'Tlist_Auto_Highlight_Tag' variable to zero. Note that even though the current
676 tag highlighting is disabled, the tags for a new file will still be added to
679 let Tlist_Auto_Highlight_Tag = 0
681 With the above variable set to 1, you can use the ":TlistHighlightTag" command
682 to highlight the current tag.
686 To automatically open the taglist window, when you start Vim, you can set the
687 'Tlist_Auto_Open' variable to 1. By default, this variable is set to zero and
688 the taglist window will not be opened automatically on Vim startup.
690 let Tlist_Auto_Open = 1
692 The taglist window is opened only when a supported type of file is opened on
693 Vim startup. For example, if you open text files, then the taglist window will
696 *'Tlist_Auto_Update'*
698 When a new file is edited, the tags defined in the file are automatically
699 processed and added to the taglist. To stop adding new files to the taglist,
700 set the 'Tlist_Auto_Update' variable to zero. By default, this variable is set
703 let Tlist_Auto_Update = 0
705 With the above variable set to 1, you can use the ":TlistUpdate" command to
706 add the tags defined in the current file to the taglist.
708 *'Tlist_Close_On_Select'*
709 Tlist_Close_On_Select~
710 If you want to close the taglist window when a file or tag is selected, then
711 set the 'Tlist_Close_On_Select' variable to 1. By default, this variable is
712 set zero and when you select a tag or file from the taglist window, the window
715 let Tlist_Close_On_Select = 1
717 *'Tlist_Compact_Format'*
718 Tlist_Compact_Format~
719 By default, empty lines are used to separate different tag types displayed for
720 a file and the tags displayed for different files in the taglist window. If
721 you want to display as many tags as possible in the taglist window, you can
722 set the 'Tlist_Compact_Format' variable to 1 to get a compact display.
724 let Tlist_Compact_Format = 1
728 The 'Tlist_Ctags_Cmd' variable specifies the location (path) of the exuberant
729 ctags utility. If exuberant ctags is present in any one of the directories in
730 the PATH environment variable, then there is no need to set this variable.
732 The exuberant ctags tool can be installed under different names. When the
733 taglist plugin starts up, if the 'Tlist_Ctags_Cmd' variable is not set, it
734 checks for the names exuberant-ctags, exctags, ctags, ctags.exe and tags in
735 the PATH environment variable. If any one of the named executable is found,
736 then the Tlist_Ctags_Cmd variable is set to that name.
738 If exuberant ctags is not present in one of the directories specified in the
739 PATH environment variable, then set this variable to point to the location of
740 the ctags utility in your system. Note that this variable should point to the
741 fully qualified exuberant ctags location and NOT to the directory in which
742 exuberant ctags is installed. If the exuberant ctags tool is not found in
743 either PATH or in the specified location, then the taglist plugin will not be
746 let Tlist_Ctags_Cmd = 'd:\tools\ctags.exe'
747 let Tlist_Ctags_Cmd = '/usr/local/bin/ctags'
749 *'Tlist_Display_Prototype'*
750 Tlist_Display_Prototype~
751 By default, only the tag name will be displayed in the taglist window. If you
752 like to see tag prototypes instead of names, set the 'Tlist_Display_Prototype'
753 variable to 1. By default, this variable is set to zero and only tag names
756 let Tlist_Display_Prototype = 1
758 *'Tlist_Display_Tag_Scope'*
759 Tlist_Display_Tag_Scope~
760 By default, the scope of a tag (like a C++ class) will be displayed in
761 square brackets next to the tag name. If you don't want the tag scopes
762 to be displayed, then set the 'Tlist_Display_Tag_Scope' to zero. By default,
763 this variable is set to 1 and the tag scopes will be displayed.
765 let Tlist_Display_Tag_Scope = 0
767 *'Tlist_Enable_Fold_Column'*
768 Tlist_Enable_Fold_Column~
769 By default, the Vim fold column is enabled and displayed in the taglist
770 window. If you wish to disable this (for example, when you are working with a
771 narrow Vim window or terminal), you can set the 'Tlist_Enable_Fold_Column'
774 let Tlist_Enable_Fold_Column = 1
776 *'Tlist_Exit_OnlyWindow'*
777 Tlist_Exit_OnlyWindow~
778 If you want to exit Vim if only the taglist window is currently opened, then
779 set the 'Tlist_Exit_OnlyWindow' variable to 1. By default, this variable is
780 set to zero and the Vim instance will not be closed if only the taglist window
783 let Tlist_Exit_OnlyWindow = 1
785 *'Tlist_File_Fold_Auto_Close'*
786 Tlist_File_Fold_Auto_Close~
787 By default, the tags tree displayed in the taglist window for all the files is
788 opened. You can close/fold the tags tree for the files manually. To
789 automatically close the tags tree for inactive files, you can set the
790 'Tlist_File_Fold_Auto_Close' variable to 1. When this variable is set to 1,
791 the tags tree for the current buffer is automatically opened and for all the
792 other buffers is closed.
794 let Tlist_File_Fold_Auto_Close = 1
796 *'Tlist_GainFocus_On_ToggleOpen'*
797 Tlist_GainFocus_On_ToggleOpen~
798 When the taglist window is opened using the ':TlistToggle' command, this
799 option controls whether the cursor is moved to the taglist window or remains
800 in the current window. By default, this option is set to 0 and the cursor
801 remains in the current window. When this variable is set to 1, the cursor
802 moves to the taglist window after opening the taglist window.
804 let Tlist_GainFocus_On_ToggleOpen = 1
806 *'Tlist_Highlight_Tag_On_BufEnter'*
807 Tlist_Highlight_Tag_On_BufEnter~
808 When you enter a Vim buffer/window, the current tag in that buffer/window is
809 automatically highlighted in the taglist window. If the current tag name is
810 not visible in the taglist window, then the taglist window contents are
811 scrolled to make that tag name visible. If you like to disable the automatic
812 highlighting of the current tag when entering a buffer, you can set the
813 'Tlist_Highlight_Tag_On_BufEnter' variable to zero. The default setting for
816 let Tlist_Highlight_Tag_On_BufEnter = 0
818 *'Tlist_Inc_Winwidth'*
820 By default, when the width of the window is less than 100 and a new taglist
821 window is opened vertically, then the window width is increased by the value
822 set in the 'Tlist_WinWidth' variable to accommodate the new window. The value
823 of this variable is used only if you are using a vertically split taglist
826 If your terminal doesn't support changing the window width from Vim (older
827 version of xterm running in a Unix system) or if you see any weird problems in
828 the screen due to the change in the window width or if you prefer not to
829 adjust the window width then set the 'Tlist_Inc_Winwidth' variable to zero.
830 CAUTION: If you are using the MS-Windows version of Vim in a MS-DOS command
831 window then you must set this variable to zero, otherwise the system may hang
832 due to a Vim limitation (explained in :help win32-problems)
834 let Tlist_Inc_Winwidth = 0
836 *'Tlist_Max_Submenu_Items'*
837 Tlist_Max_Submenu_Items~
838 If a file contains too many tags of a particular type (function, variable,
839 class, etc.), greater than that specified by the 'Tlist_Max_Submenu_Items'
840 variable, then the menu for that tag type will be split into multiple
841 sub-menus. The default setting for the 'Tlist_Max_Submenu_Items' variable is
842 25. This can be changed by setting the 'Tlist_Max_Submenu_Items' variable:
844 let Tlist_Max_Submenu_Items = 20
846 The name of the submenu is formed using the names of the first and the last
847 tag entries in that submenu.
849 *'Tlist_Max_Tag_Length'*
850 Tlist_Max_Tag_Length~
851 Only the first 'Tlist_Max_Tag_Length' characters from the tag names will be
852 used to form the tag type submenu name. The default value for this variable is
853 10. Change the 'Tlist_Max_Tag_Length' setting if you want to include more or
856 let Tlist_Max_Tag_Length = 10
858 *'Tlist_Process_File_Always'*
859 Tlist_Process_File_Always~
860 By default, the taglist plugin will generate and process the tags defined in
861 the newly opened files only when the taglist window is opened or when the
862 taglist menu is enabled. When the taglist window is closed, the taglist plugin
863 will stop processing the tags for newly opened files.
865 You can set the 'Tlist_Process_File_Always' variable to 1 to generate the list
866 of tags for new files even when the taglist window is closed and the taglist
869 let Tlist_Process_File_Always = 1
871 To use the ":TlistShowTag" and the ":TlistShowPrototype" commands without the
872 taglist window and the taglist menu, you should set this variable to 1.
876 When using GUI Vim, you can display the tags defined in the current file in a
877 menu named "Tags". By default, this feature is turned off. To turn on this
878 feature, set the 'Tlist_Show_Menu' variable to 1:
880 let Tlist_Show_Menu = 1
882 *'Tlist_Show_One_File'*
884 By default, the taglist plugin will display the tags defined in all the loaded
885 buffers in the taglist window. If you prefer to display the tags defined only
886 in the current buffer, then you can set the 'Tlist_Show_One_File' to 1. When
887 this variable is set to 1, as you switch between buffers, the taglist window
888 will be refreshed to display the tags for the current buffer and the tags for
889 the previous buffer will be removed.
891 let Tlist_Show_One_File = 1
895 The 'Tlist_Sort_Type' variable specifies the sort order for the tags in the
896 taglist window. The tags can be sorted either alphabetically by their name or
897 by the order of their appearance in the file (chronological order). By
898 default, the tag names will be listed by the order in which they are defined
899 in the file. You can change the sort type (from name to order or from order to
900 name) by pressing the "s" key in the taglist window. You can also change the
901 default sort order by setting 'Tlist_Sort_Type' to "name" or "order":
903 let Tlist_Sort_Type = "name"
905 *'Tlist_Use_Horiz_Window'*
906 Tlist_Use_Horiz_Window~
907 Be default, the tag names are displayed in a vertically split window. If you
908 prefer a horizontally split window, then set the 'Tlist_Use_Horiz_Window'
909 variable to 1. If you are running MS-Windows version of Vim in a MS-DOS
910 command window, then you should use a horizontally split window instead of a
911 vertically split window. Also, if you are using an older version of xterm in a
912 Unix system that doesn't support changing the xterm window width, you should
913 use a horizontally split window.
915 let Tlist_Use_Horiz_Window = 1
917 *'Tlist_Use_Right_Window'*
918 Tlist_Use_Right_Window~
919 By default, the vertically split taglist window will appear on the left hand
920 side. If you prefer to open the window on the right hand side, you can set the
921 'Tlist_Use_Right_Window' variable to 1:
923 let Tlist_Use_Right_Window = 1
925 *'Tlist_Use_SingleClick'*
926 Tlist_Use_SingleClick~
927 By default, when you double click on the tag name using the left mouse
928 button, the cursor will be positioned at the definition of the tag. You
929 can set the 'Tlist_Use_SingleClick' variable to 1 to jump to a tag when
930 you single click on the tag name using the mouse. By default this variable
933 let Tlist_Use_SingleClick = 1
935 Due to a bug in Vim, if you set 'Tlist_Use_SingleClick' to 1 and try to resize
936 the taglist window using the mouse, then Vim will crash. This problem is fixed
937 in Vim 6.3 and above. In the meantime, instead of resizing the taglist window
938 using the mouse, you can use normal Vim window resizing commands to resize the
943 The default height of the horizontally split taglist window is 10. This can be
944 changed by modifying the 'Tlist_WinHeight' variable:
946 let Tlist_WinHeight = 20
948 The |'winfixheight'| option is set for the taglist window, to maintain the
949 height of the taglist window, when new Vim windows are opened and existing
954 The default width of the vertically split taglist window is 30. This can be
955 changed by modifying the 'Tlist_WinWidth' variable:
957 let Tlist_WinWidth = 20
959 Setting Tlist_WinWidth to 'auto' causes the taglist window to resize
960 automatically to fit the contents.
962 Note that the value of the |'winwidth'| option setting determines the minimum
963 width of the current window. If you set the 'Tlist_WinWidth' variable to a
964 value less than that of the |'winwidth'| option setting, then Vim will use the
965 value of the |'winwidth'| option.
967 When new Vim windows are opened and existing windows are closed, the taglist
968 plugin will try to maintain the width of the taglist window to the size
969 specified by the 'Tlist_WinWidth' variable.
971 *'Tlist_javascript_Hide_Extras'*
972 Tlist_javascript_Hide_Extras~
974 To hide the type inference data generated by jsctags, modify this variable:
976 let Tlist_javascript_Hide_Extras = ['type']
978 Note that 'javascript' here is not capitalized!
980 ==============================================================================
984 The taglist plugin provides the following ex-mode commands:
986 |:TlistAddFiles| Add multiple files to the taglist.
987 |:TlistAddFilesRecursive|
988 Add files recursively to the taglist.
989 |:TlistClose| Close the taglist window.
990 |:TlistDebug| Start logging of taglist debug messages.
991 |:TlistLock| Stop adding new files to the taglist.
992 |:TlistMessages| Display the logged taglist plugin debug messages.
993 |:TlistOpen| Open and jump to the taglist window.
994 |:TlistSessionSave| Save the information about files and tags in the
995 taglist to a session file.
996 |:TlistSessionLoad| Load the information about files and tags stored
997 in a session file to taglist.
998 |:TlistShowPrototype| Display the prototype of the tag at or before the
999 specified line number.
1000 |:TlistShowTag| Display the name of the tag defined at or before the
1001 specified line number.
1002 |:TlistHighlightTag| Highlight the current tag in the taglist window.
1003 |:TlistToggle| Open or close (toggle) the taglist window.
1004 |:TlistUndebug| Stop logging of taglist debug messages.
1005 |:TlistUnlock| Start adding new files to the taglist.
1006 |:TlistUpdate| Update the tags for the current buffer.
1009 :TlistAddFiles {file(s)} [file(s) ...]
1010 Add one or more specified files to the taglist. You can
1011 specify multiple filenames using wildcards. To specify a
1012 file name with space character, you should escape the space
1013 character with a backslash.
1016 :TlistAddFiles *.c *.cpp
1017 :TlistAddFiles file1.html file2.html
1019 If you specify a large number of files, then it will take some
1020 time for the taglist plugin to process all of them. The
1021 specified files will not be edited in a Vim window and will
1022 not be added to the Vim buffer list.
1024 *:TlistAddFilesRecursive*
1025 :TlistAddFilesRecursive {directory} [ {pattern} ]
1026 Add files matching {pattern} recursively from the specified
1027 {directory} to the taglist. If {pattern} is not specified,
1028 then '*' is assumed. To specify the current directory, use "."
1029 for {directory}. To specify a directory name with space
1030 character, you should escape the space character with a
1034 :TlistAddFilesRecursive myproject *.java
1035 :TlistAddFilesRecursive smallproject
1037 If large number of files are present in the specified
1038 directory tree, then it will take some time for the taglist
1039 plugin to process all of them.
1042 :TlistClose Close the taglist window. This command can be used from any
1043 one of the Vim windows.
1046 :TlistDebug [filename]
1047 Start logging of debug messages from the taglist plugin.
1048 If {filename} is specified, then the debug messages are stored
1049 in the specified file. Otherwise, the debug messages are
1050 stored in a script local variable. If the file {filename} is
1051 already present, then it is overwritten.
1055 Lock the taglist and don't process new files. After this
1056 command is executed, newly edited files will not be added to
1061 Display the logged debug messages from the taglist plugin
1062 in a window. This command works only when logging to a
1063 script-local variable.
1066 :TlistOpen Open and jump to the taglist window. Creates the taglist
1067 window, if the window is not opened currently. After executing
1068 this command, the cursor is moved to the taglist window. When
1069 the taglist window is opened for the first time, all the files
1070 in the buffer list are processed and the tags defined in them
1071 are displayed in the taglist window.
1074 :TlistSessionSave {filename}
1075 Saves the information about files and tags in the taglist to
1076 the specified file. This command can be used to save and
1077 restore the taglist contents across Vim sessions.
1080 :TlistSessionLoad {filename}
1081 Load the information about files and tags stored in the
1082 specified session file to the taglist.
1084 *:TlistShowPrototype*
1085 :TlistShowPrototype [filename] [linenumber]
1086 Display the prototype of the tag at or before the specified
1087 line number. If the file name and the line number are not
1088 specified, then the current file name and line number are
1089 used. A tag spans multiple lines starting from the line where
1090 it is defined to the line before the next tag. This command
1091 displays the prototype for the tag for any line number in this
1095 :TlistShowTag [filename] [linenumber]
1096 Display the name of the tag defined at or before the specified
1097 line number. If the file name and the line number are not
1098 specified, then the current file name and line number are
1099 used. A tag spans multiple lines starting from the line where
1100 it is defined to the line before the next tag. This command
1101 displays the tag name for any line number in this range.
1103 *:TlistHighlightTag*
1105 Highlight the current tag in the taglist window. By default,
1106 the taglist plugin periodically updates the taglist window to
1107 highlight the current tag. This command can be used to force
1108 the taglist plugin to highlight the current tag.
1111 :TlistToggle Open or close (toggle) the taglist window. Opens the taglist
1112 window, if the window is not opened currently. Closes the
1113 taglist window, if the taglist window is already opened. When
1114 the taglist window is opened for the first time, all the files
1115 in the buffer list are processed and the tags are displayed in
1116 the taglist window. After executing this command, the cursor
1117 is not moved from the current window to the taglist window.
1121 Stop logging of debug messages from the taglist plugin.
1125 Unlock the taglist and start processing newly edited files.
1128 :TlistUpdate Update the tags information for the current buffer. This
1129 command can be used to re-process the current file/buffer and
1130 get the tags information. As the taglist plugin uses the file
1131 saved in the disk (instead of the file displayed in a Vim
1132 buffer), you should save a modified buffer before you update
1133 the taglist. Otherwise the listed tags will not include the
1134 new tags created in the buffer. You can use this command even
1135 when the taglist window is not opened.
1137 ==============================================================================
1139 7. Global functions~
1141 The taglist plugin provides several global functions that can be used from
1142 other Vim plugins to interact with the taglist plugin. These functions are
1145 |Tlist_Update_File_Tags()| Update the tags for the specified file
1146 |Tlist_Get_Tag_Prototype_By_Line()| Return the prototype of the tag at or
1147 before the specified line number in the
1149 |Tlist_Get_Tagname_By_Line()| Return the name of the tag at or
1150 before the specified line number in
1152 |Tlist_Set_App()| Set the name of the application
1153 controlling the taglist window.
1155 *Tlist_Update_File_Tags()*
1156 Tlist_Update_File_Tags({filename}, {filetype})
1157 Update the tags for the file {filename}. The second argument
1158 specifies the Vim filetype for the file. If the taglist plugin
1159 has not processed the file previously, then the exuberant
1160 ctags tool is invoked to generate the tags for the file.
1162 *Tlist_Get_Tag_Prototype_By_Line()*
1163 Tlist_Get_Tag_Prototype_By_Line([{filename}, {linenumber}])
1164 Return the prototype of the tag at or before the specified
1165 line number in the specified file. If the filename and line
1166 number are not specified, then the current buffer name and the
1167 current line number are used.
1169 *Tlist_Get_Tagname_By_Line()*
1170 Tlist_Get_Tagname_By_Line([{filename}, {linenumber}])
1171 Return the name of the tag at or before the specified line
1172 number in the specified file. If the filename and line number
1173 are not specified, then the current buffer name and the
1174 current line number are used.
1177 Tlist_Set_App({appname})
1178 Set the name of the plugin that controls the taglist plugin
1179 window and buffer. This can be used to integrate the taglist
1180 plugin with other Vim plugins.
1182 For example, the winmanager plugin and the Cream package use
1183 this function and specify the appname as "winmanager" and
1184 "cream" respectively.
1186 By default, the taglist plugin is a stand-alone plugin and
1187 controls the taglist window and buffer. If the taglist window
1188 is controlled by an external plugin, then the appname should
1189 be set appropriately.
1191 ==============================================================================
1195 The taglist plugin supports all the languages supported by the exuberant ctags
1196 tool, which includes the following languages: Assembly, ASP, Awk, Beta, C,
1197 C++, C#, Cobol, Eiffel, Erlang, Fortran, HTML, Java, Javascript, Lisp, Lua,
1198 Make, Pascal, Perl, PHP, Python, Rexx, Ruby, Scheme, Shell, Slang, SML, Sql,
1199 TCL, Verilog, Vim and Yacc.
1201 You can extend the taglist plugin to add support for new languages and also
1202 modify the support for the above listed languages.
1204 You should NOT make modifications to the taglist plugin script file to add
1205 support for new languages. You will lose these changes when you upgrade to the
1206 next version of the taglist plugin. Instead you should follow the below
1207 described instructions to extend the taglist plugin.
1209 You can extend the taglist plugin by setting variables in the .vimrc or _vimrc
1210 file. The name of these variables depends on the language name and is
1213 Modifying support for an existing language~
1214 To modify the support for an already supported language, you have to set the
1215 tlist_xxx_settings variable in the ~/.vimrc or $HOME/_vimrc file. Replace xxx
1216 with the Vim filetype name for the language file. For example, to modify the
1217 support for the perl language files, you have to set the tlist_perl_settings
1218 variable. To modify the support for java files, you have to set the
1219 tlist_java_settings variable.
1221 To determine the filetype name used by Vim for a file, use the following
1222 command in the buffer containing the file:
1226 The above command will display the Vim filetype for the current buffer.
1228 The format of the value set in the tlist_xxx_settings variable is
1230 <language_name>;flag1:name1;flag2:name2;flag3:name3
1232 The different fields in the value are separated by the ';' character.
1234 The first field 'language_name' is the name used by exuberant ctags to refer
1235 to this language file. This name can be different from the file type name used
1236 by Vim. For example, for C++, the language name used by ctags is 'c++' but the
1237 filetype name used by Vim is 'cpp'. To get the list of language names
1238 supported by exuberant ctags, use the following command:
1240 $ ctags --list-maps=all
1242 The remaining fields follow the format "flag:name". The sub-field 'flag' is
1243 the language specific flag used by exuberant ctags to generate the
1244 corresponding tags. For example, for the C language, to list only the
1245 functions, the 'f' flag is used. To get the list of flags supported by
1246 exuberant ctags for the various languages use the following command:
1248 $ ctags --list-kinds=all
1250 The sub-field 'name' specifies the title text to use for displaying the tags
1251 of a particular type. For example, 'name' can be set to 'functions'. This
1252 field can be set to any text string name.
1254 For example, to list only the classes and functions defined in a C++ language
1255 file, add the following line to your .vimrc file:
1257 let tlist_cpp_settings = 'c++;c:class;f:function'
1259 In the above setting, 'cpp' is the Vim filetype name and 'c++' is the name
1260 used by the exuberant ctags tool. 'c' and 'f' are the flags passed to
1261 exuberant ctags to list C++ classes and functions and 'class' is the title
1262 used for the class tags and 'function' is the title used for the function tags
1263 in the taglist window.
1265 For example, to display only functions defined in a C file and to use "My
1266 Functions" as the title for the function tags, use
1268 let tlist_c_settings = 'c;f:My Functions'
1270 When you set the tlist_xxx_settings variable, you will override the default
1271 setting used by the taglist plugin for the 'xxx' language. You cannot add to
1272 the default options used by the taglist plugin for a particular file type. To
1273 add to the options used by the taglist plugin for a language, copy the option
1274 values from the taglist plugin file to your .vimrc file and modify it.
1276 Adding support for a new language~
1277 If you want to add support for a new language to the taglist plugin, you need
1278 to first extend the exuberant ctags tool. For more information about extending
1279 exuberant ctags, visit the following page:
1281 http://ctags.sourceforge.net/EXTENDING.html
1283 To add support for a new language, set the tlist_xxx_settings variable in the
1284 ~/.vimrc file appropriately as described above. Replace 'xxx' in the variable
1285 name with the Vim filetype name for the new language.
1287 For example, to extend the taglist plugin to support the latex language, you
1288 can use the following line (assuming, you have already extended exuberant
1289 ctags to support the latex language):
1291 let tlist_tex_settings='latex;b:bibitem;c:command;l:label'
1293 With the above line, when you edit files of filetype "tex" in Vim, the taglist
1294 plugin will invoke the exuberant ctags tool passing the "latex" filetype and
1295 the flags b, c and l to generate the tags. The text heading 'bibitem',
1296 'command' and 'label' will be used in the taglist window for the tags which
1297 are generated for the flags b, c and l respectively.
1299 ==============================================================================
1301 9. Frequently Asked Questions~
1303 Q. The taglist plugin doesn't work. The taglist window is empty and the tags
1304 defined in a file are not displayed.
1305 A. Are you using Vim version 6.0 and above? The taglist plugin relies on the
1306 features supported by Vim version 6.0 and above. You can use the following
1307 command to get the Vim version:
1311 Are you using exuberant ctags version 5.0 and above? The taglist plugin
1312 relies on the features supported by exuberant ctags and will not work with
1313 GNU ctags or the Unix ctags utility. You can use the following command to
1314 determine whether the ctags installed in your system is exuberant ctags:
1318 Is exuberant ctags present in one of the directories in your PATH? If not,
1319 you need to set the Tlist_Ctags_Cmd variable to point to the location of
1320 exuberant ctags. Use the following Vim command to verify that this is setup
1323 :echo system(Tlist_Ctags_Cmd . ' --version')
1325 The above command should display the version information for exuberant
1328 Did you turn on the Vim filetype detection? The taglist plugin relies on
1329 the filetype detected by Vim and passes the filetype to the exuberant ctags
1330 utility to parse the tags. Check the output of the following Vim command:
1334 The output of the above command should contain "filetype detection:ON".
1335 To turn on the filetype detection, add the following line to the .vimrc or
1340 Is your version of Vim compiled with the support for the system() function?
1341 The following Vim command should display 1:
1343 :echo exists('*system')
1345 In some Linux distributions (particularly Suse Linux), the default Vim
1346 installation is built without the support for the system() function. The
1347 taglist plugin uses the system() function to invoke the exuberant ctags
1348 utility. You need to rebuild Vim after enabling the support for the
1349 system() function. If you use the default build options, the system()
1350 function will be supported.
1352 Do you have the |'shellslash'| option set? You can try disabling the
1353 |'shellslash'| option. When the taglist plugin invokes the exuberant ctags
1354 utility with the path to the file, if the incorrect slashes are used, then
1355 you will see errors.
1357 Check the shell related Vim options values using the following command:
1359 :set shell? shellcmdflag? shellpipe?
1360 :set shellquote? shellredir? shellxquote?
1362 If these options are set in your .vimrc or _vimrc file, try removing those
1365 Are you using a Unix shell in a MS-Windows environment? For example,
1366 the Unix shell from the MKS-toolkit. Do you have the SHELL environment
1367 set to point to this shell? You can try resetting the SHELL environment
1370 If you are using a Unix shell on MS-Windows, you should try to use
1371 exuberant ctags that is compiled for Unix-like environments so that
1372 exuberant ctags will understand path names with forward slash characters.
1374 Is your filetype supported by the exuberant ctags utility? The file types
1375 supported by the exuberant ctags utility are listed in the ctags help. If a
1376 file type is not supported, you have to extend exuberant ctags. You can use
1377 the following command to list the filetypes supported by exuberant ctags:
1379 ctags --list-languages
1381 Run the following command from the shell prompt and check whether the tags
1382 defined in your file are listed in the output from exuberant ctags:
1384 ctags -f - --format=2 --excmd=pattern --fields=nks <filename>
1386 If you see your tags in the output from the above command, then the
1387 exuberant ctags utility is properly parsing your file.
1389 Do you have the .ctags or _ctags or the ctags.cnf file in your home
1390 directory for specifying default options or for extending exuberant ctags?
1391 If you do have this file, check the options in this file and make sure
1392 these options are not interfering with the operation of the taglist plugin.
1394 If you are using MS-Windows, check the value of the TEMP and TMP
1395 environment variables. If these environment variables are set to a path
1396 with space characters in the name, then try using the DOS 8.3 short name
1397 for the path or set them to a path without the space characters in the
1398 name. For example, if the temporary directory name is "C:\Documents and
1399 Settings\xyz\Local Settings\Temp", then try setting the TEMP variable to
1402 set TEMP=C:\DOCUMEN~1\xyz\LOCALS~1\Temp
1404 If exuberant ctags is installed in a directory with space characters in the
1405 name, then try adding the directory to the PATH environment variable or try
1406 setting the 'Tlist_Ctags_Cmd' variable to the shortest path name to ctags
1407 or try copying the exuberant ctags to a path without space characters in
1408 the name. For example, if exuberant ctags is installed in the directory
1409 "C:\Program Files\Ctags", then try setting the 'Tlist_Ctags_Cmd' variable
1412 let Tlist_Ctags_Cmd='C:\Progra~1\Ctags\ctags.exe'
1414 If you are using a cygwin compiled version of exuberant ctags on MS-Windows,
1415 make sure that either you have the cygwin compiled sort utility installed
1416 and available in your PATH or compile exuberant ctags with internal sort
1417 support. Otherwise, when exuberant ctags sorts the tags output by invoking
1418 the sort utility, it may end up invoking the MS-Windows version of
1419 sort.exe, thereby resulting in failure.
1421 Q. When I try to open the taglist window, I am seeing the following error
1422 message. How do I fix this problem?
1424 Taglist: Failed to generate tags for /my/path/to/file
1425 ctags: illegal option -- -^@usage: ctags [-BFadtuwvx] [-f tagsfile] file ...
1427 A. The taglist plugin will work only with the exuberant ctags tool. You
1428 cannot use the GNU ctags or the Unix ctags program with the taglist plugin.
1429 You will see an error message similar to the one shown above, if you try
1430 use a non-exuberant ctags program with Vim. To fix this problem, either add
1431 the exuberant ctags tool location to the PATH environment variable or set
1432 the 'Tlist_Ctags_Cmd' variable.
1434 Q. A file has more than one tag with the same name. When I select a tag name
1435 from the taglist window, the cursor is positioned at the incorrect tag
1437 A. The taglist plugin uses the search pattern generated by the exuberant ctags
1438 utility to position the cursor at the location of a tag definition. If a
1439 file has more than one tag with the same name and same prototype, then the
1440 search pattern will be the same. In this case, when searching for the tag
1441 pattern, the cursor may be positioned at the incorrect location.
1443 Q. I have made some modifications to my file and introduced new
1444 functions/classes/variables. I have not yet saved my file. The taglist
1445 plugin is not displaying the new tags when I update the taglist window.
1446 A. The exuberant ctags utility will process only files that are present in the
1447 disk. To list the tags defined in a file, you have to save the file and
1448 then update the taglist window.
1450 Q. I have created a ctags file using the exuberant ctags utility for my source
1451 tree. How do I configure the taglist plugin to use this tags file?
1452 A. The taglist plugin doesn't use a tags file stored in disk. For every opened
1453 file, the taglist plugin invokes the exuberant ctags utility to get the
1454 list of tags dynamically. The Vim system() function is used to invoke
1455 exuberant ctags and get the ctags output. This function internally uses a
1456 temporary file to store the output. This file is deleted after the output
1457 from the command is read. So you will never see the file that contains the
1458 output of exuberant ctags.
1460 Q. When I set the |'updatetime'| option to a low value (less than 1000) and if
1461 I keep pressing a key with the taglist window open, the current buffer
1462 contents are changed. Why is this?
1463 A. The taglist plugin uses the |CursorHold| autocmd to highlight the current
1464 tag. The CursorHold autocmd triggers for every |'updatetime'| milliseconds.
1465 If the |'updatetime'| option is set to a low value, then the CursorHold
1466 autocmd will be triggered frequently. As the taglist plugin changes
1467 the focus to the taglist window to highlight the current tag, this could
1468 interfere with the key movement resulting in changing the contents of
1469 the current buffer. The workaround for this problem is to not set the
1470 |'updatetime'| option to a low value.
1472 ==============================================================================
1475 Permission is hereby granted to use and distribute the taglist plugin, with or
1476 without modifications, provided that this copyright notice is copied with it.
1477 Like anything else that's free, taglist.vim is provided *as is* and comes with
1478 no warranty of any kind, either expressed or implied. In no event will the
1479 copyright holder be liable for any damamges resulting from the use of this
1482 ==============================================================================
1486 1. Group tags according to the scope and display them. For example,
1487 group all the tags belonging to a C++/Java class
1488 2. Support for displaying tags in a modified (not-yet-saved) file.
1489 3. Automatically open the taglist window only for selected filetypes.
1490 For other filetypes, close the taglist window.
1491 4. When using the shell from the MKS toolkit, the taglist plugin
1493 5. The taglist plugin doesn't work with files edited remotely using the
1494 netrw plugin. The exuberant ctags utility cannot process files over
1497 ==============================================================================
1499 vim:tw=78:ts=8:noet:ft=help: