diff --git a/doc/taglist.txt b/doc/taglist.txt index 2400a4a..ae01332 100644 --- a/doc/taglist.txt +++ b/doc/taglist.txt @@ -2,7 +2,7 @@ Author: Yegappan Lakshmanan (yegappan AT yahoo DOT com) For Vim version 6.0 and above -Last change: 2005 April 4 +Last change: 2005 August 1 1. Overview |taglist-intro| 2. Taglist on the internet |taglist-internet| @@ -250,10 +250,15 @@ width/height without closing the other existing windows. You can again press 'x' to restore the taglist window to the default width/height. Updating the tags displayed for a file~ -You can update or refresh the tags displayed for a file by pressing the "u" -key in the taglist window. If an existing file is modified, after the file is -saved, the taglist plugin will automatically update the tags displayed for the -file. +The taglist plugin keeps track of the modification time of a file. When the +modification time changes (the file is modified), the taglist plugin will +automatically update the tags listed for that file. The modification time is +checked when you enter a window containing the file or when you load the file. + +You can also update or refresh the tags displayed for a file by pressing the +"u" key in the taglist window. If an existing file is modified, after the file +is saved, the taglist plugin will automatically update the tags displayed for +the file. You can also use the ":TlistUpdate" command to update the tags for the current buffer after you made some changes to it. You should save the modified buffer @@ -264,6 +269,17 @@ If you have deleted the tags displayed for a file in the taglist window using the 'd' key, you can again display the tags for that file using the ':TlistUpdate' command. +Adding multiples files to the taglist window~ +You can add the tags defined in a file(s) without opening it using the +":TlistAddFiles" command. For example, to add the tags defined in all +the C files in a directory, you can use the following command: + + :TlistAddFiles my/project/dir/*.c + +Note that if you try to add several files with a large number of tags or a +large number of files, then it will take several seconds to minutes for the +taglist plugin to process all the files. + Modifying the contents of the taglist buffer/window~ The contents of the taglist buffer/window are managed by the taglist plugin. The Vim 'modifiable' option is turned off for the taglist buffer. You should @@ -448,32 +464,67 @@ should use the |let| command in your .vimrc file to change the setting of any of these variables. The configurable taglist variables are listed below. For a detailed -description of these variables refer to the text after this table. +description of these variables refer to the text below this table. +|'Tlist_Auto_Highlight_Tag'| Highlight the current tag in the taglist. +|'Tlist_Auto_Open'| Open the taglist window when Vim starts. +|'Tlist_Compact_Format'| Remove extra information and blank lines from + the taglist window. |'Tlist_Ctags_Cmd'| Specifies the path to the ctags utility. -|'Tlist_Sort_Type'| Sort method used for arranging the tags. -|'Tlist_Use_Horiz_Window'| Use a horizontal split window for the taglist. -|'Tlist_Use_Right_Window'| Put the taglist window on the right side. -|'Tlist_Auto_Open'| Open the taglist window when VIM starts. |'Tlist_Display_Prototype'| Show prototypes, not just tags. |'Tlist_Display_Tag_Scope'| Show tag scope next to the tag name. -|'Tlist_Show_One_File'| Show tags for the current buffer only. -|'Tlist_WinWidth'| Set the taglist window width. -|'Tlist_Inc_Winwidth'| Expand the current window to accommodate the - taglist. -|'Tlist_WinHeight'| If horizontal is set, set the window height. -|'Tlist_Use_SingleClick'| Single click on a tag jumps to it. -|'Tlist_Compact_Format'| Remove extra information and blank lines from - the taglist. +|'Tlist_Enable_Fold_Column'| Show the fold indicator column. |'Tlist_Exit_OnlyWindow'| Close VIM if the taglist is the only window. |'Tlist_File_Fold_Auto_Close'| Close tag folds for all buffers not shown. -|'Tlist_Enable_Fold_Column'| Show the fold indicator column. -|'Tlist_Auto_Highlight_Tag'| Highlight the current tag in the taglist. -|'Tlist_Process_File_Always'| Process tags for files when taglist is closed. -|'Tlist_Show_Menu'| Display the tags menu. +|'Tlist_Inc_Winwidth'| Expand the current window to accommodate the + taglist window. |'Tlist_Max_Submenu_Items'| Maximum number of items in a tags sub-menu. |'Tlist_Max_Tag_Length'| Maximum tag length used in a tag menu entry. +|'Tlist_Process_File_Always'| Process tags for files when the taglist window + is closed. +|'Tlist_Show_Menu'| Display the tags menu. +|'Tlist_Show_One_File'| Show tags for the current buffer only. +|'Tlist_Sort_Type'| Sort method used for arranging the tags. +|'Tlist_Use_Horiz_Window'| Use a horizontally split window for the + taglist window. +|'Tlist_Use_Right_Window'| Put the taglist window on the right side. +|'Tlist_Use_SingleClick'| Single click on a tag jumps to it. +|'Tlist_WinHeight'| Horizontally split taglist window height. +|'Tlist_WinWidth'| Vertically split taglist window width. + *'Tlist_Auto_Highlight_Tag'* +Tlist_Auto_Highlight_Tag~ +By default, the taglist plugin will highlight the current tag in the taglist +window. If you want to disable the highlighting of the current tag, then you +can set the Tlist_Auto_Highlight_Tag variable to zero. Note that even though +the current tag highlighting is disabled, the tags for a new file will still +be added to the taglist window. +> + let Tlist_Auto_Highlight_Tag = 0 +< +You can still use the ':TlistSync' command to highlight the current tag. + + *'Tlist_Auto_Open'* +Tlist_Auto_Open~ +To automatically open the taglist window, when you start Vim, you can set the +'Tlist_Auto_Open' variable to 1. By default, this variable is set to 0 and the +taglist window will not be opened automatically on Vim startup. > + + let Tlist_Auto_Open = 1 +< +The taglist window is opened only when a supported type of file is opened on +Vim startup. For example, if you open text files, then the taglist window will +not be opened. + + *'Tlist_Compact_Format'* +Tlist_Compact_Format~ +By default, empty lines are used to separate different tag types displayed for +a file and the tags displayed for different files in the taglist window. If +you want to display as many tags as possible in the taglist window, you can +set the Tlist_Compact_Format variable to one to get a compact display. > + + let Tlist_Compact_Format = 1 +< *'Tlist_Ctags_Cmd'* Tlist_Ctags_Cmd~ The 'Tlist_Ctags_Cmd' variable specifies the location (path) of the exuberant @@ -496,6 +547,128 @@ loaded. > let Tlist_Ctags_Cmd = 'd:\tools\ctags.exe' let Tlist_Ctags_Cmd = '/usr/local/bin/ctags' +< + *'Tlist_Display_Prototype'* +Tlist_Display_Prototype~ +By default, only the tag name will be displayed in the taglist window. If you +like to see tag prototypes instead of names, set the 'Tlist_Display_Prototype' +variable to 1. By default, this variable is set to 0 and only tag names will +be displayed. > + + let Tlist_Display_Prototype = 1 +< + *'Tlist_Display_Tag_Scope'* +Tlist_Display_Tag_Scope~ +By default, the scope of a tag (like a C++ class) will be displayed in +square brackets next to the tag name. If you don't want the tag scopes +to be displayed, then set the 'Tlist_Display_Tag_Scope' to 0. By default, +this variable is set to 1 and the tag scopes will be displayed. > + + let Tlist_Display_Tag_Scope = 0 +< + *'Tlist_Enable_Fold_Column'* +Tlist_Enable_Fold_Column~ +By default, the Vim fold column is enabled and displayed in the taglist +window. If you wish to disable this (for example, when you are working with a +narrow Vim window or terminal), you can set the Tlist_Enable_Fold_Column +variable to 0. +> + let Tlist_Enable_Fold_Column = 1 +< + *'Tlist_Exit_OnlyWindow'* +Tlist_Exit_OnlyWindow~ +If you want to exit Vim if only the taglist window is currently opened, then +set the Tlist_Exit_OnlyWindow variable to one. By default, this variable is +set to zero and the Vim instance will not be closed if only the taglist window +is present. > + + let Tlist_Exit_OnlyWindow = 1 +< + *'Tlist_File_Fold_Auto_Close'* +Tlist_File_Fold_Auto_Close~ +By default, the tags tree displayed in the taglist window for all the files is +opened. You can close/fold the tags tree for the files manually. To +automatically close the tags tree for inactive files, you can set the +Tlist_File_Fold_Auto_Close variable to 1. When this variable is set to 1, if a +Vim buffer is no longer displayed in a Vim window, the corresponding tags tree +in the taglist window will be collapsed/folded. When a buffer is loaded in a +Vim window, the corresponding tags tree will be opened. +> + let Tlist_File_Fold_Auto_Close = 1 +< + *'Tlist_Inc_Winwidth'* +Tlist_Inc_Winwidth~ +By default, when the width of the window is less than 100 and a new taglist +window is opened vertically, then the window width will be increased by the +value set in the Tlist_WinWidth variable to accommodate the new window. The +value of this variable is used only if you are using a vertically split +taglist window. + +If your terminal doesn't support changing the window width from Vim (older +version of xterm running in a Unix system) or if you see any weird problems in +the screen due to the change in the window width or if you prefer not to +adjust the window width then set the 'Tlist_Inc_Winwidth' variable to 0. +CAUTION: If you are using the MS-Windows version of Vim in a MS-DOS command +window then you must set this variable to 0, otherwise the system may hang due +to a Vim limitation (explained in :help win32-problems) > + + let Tlist_Inc_Winwidth = 0 +< + *'Tlist_Max_Submenu_Items'* +Tlist_Max_Submenu_Items~ +If a file contains too many tags of a particular type (function, variable, +class, etc.), greater than that specified by the Tlist_Max_Submenu_Items +variable, then the menu for that tag type will be split into multiple +sub-menus. The default setting for the Tlist_Max_Submenu_Items variable is 25. +This can be changed by setting the Tlist_Max_Submenu_Items variable: +> + let Tlist_Max_Submenu_Items = 20 +< +The name of the submenu is formed using the names of the first and the last +tag entries in that submenu. + + *'Tlist_Max_Tag_Length'* +Tlist_Max_Tag_Length~ +Only the first Tlist_Max_Tag_Length characters from the tag names will be used +to form the tag type submenu name. Change the Tlist_Max_Tag_Length setting if +you want to include more or less characters: +> + let Tlist_Max_Tag_Length = 10 +< + *'Tlist_Process_File_Always'* +Tlist_Process_File_Always~ +By default, the taglist plugin will generate and process the tags defined in +the newly opened files only when the taglist window is opened or when the +taglist menu is enabled. When the taglist window is closed, the taglist plugin +will stop processing the tags for newly opened files. + +You can set the Tlist_Process_File_Always variable to 1 to generate the list +of tags for new files even when the taglist window is closed and the taglist +menu is disabled. +> + let Tlist_Process_File_Always = 1 +< +You should set this variable to 1, if you want to use the :TlistShowTag and +:TlistShowPrototype commands without the taglist window and the taglist menu. + + *'Tlist_Show_Menu'* +Tlist_Show_Menu~ +When using GUI Vim, you can display the tags defined in the current file in a +menu named "Tags". By default, this feature is turned off. To turn on this +feature, set the Tlist_Show_Menu variable to one: +> + let Tlist_Show_Menu = 1 +< + *'Tlist_Show_One_File'* +Tlist_Show_One_File~ +By default, the taglist plugin will display the tags defined in all the loaded +buffers in the taglist window. If you prefer to display the tags defined only +in the current buffer, then you can set the 'Tlist_Show_One_File' to 1. When +this variable is set to 1, as you switch between buffers, the taglist window +will be refreshed to display the tags for the current buffer and the tags for +the previous buffer will be removed. +> + let Tlist_Show_One_File = 1 < *'Tlist_Sort_Type'* Tlist_Sort_Type~ @@ -528,80 +701,6 @@ side. If you prefer to open the window on the right hand side, you can set the 'Tlist_Use_Right_Window' variable to one: > let Tlist_Use_Right_Window = 1 -< - *'Tlist_Auto_Open'* -Tlist_Auto_Open~ -To automatically open the taglist window, when you start Vim, you can set the -'Tlist_Auto_Open' variable to 1. By default, this variable is set to 0 and the -taglist window will not be opened automatically on Vim startup. > - - let Tlist_Auto_Open = 1 -< - *'Tlist_Display_Prototype'* -Tlist_Display_Prototype~ -By default, only the tag name will be displayed in the taglist window. If you -like to see tag prototypes instead of names, set the 'Tlist_Display_Prototype' -variable to 1. By default, this variable is set to 0 and only tag names will -be displayed. > - - let Tlist_Display_Prototype = 1 -< - *'Tlist_Display_Tag_Scope'* -Tlist_Display_Tag_Scope~ -By default, the scope of a tag (like a C++ class) will be displayed in -square brackets next to the tag name. If you don't want the tag scopes -to be displayed, then set the 'Tlist_Display_Tag_Scope' to 0. By default, -this variable is set to 1 and the tag scopes will be displayed. > - - let Tlist_Display_Tag_Scope = 0 -< - *'Tlist_Show_One_File'* -Tlist_Show_One_File~ -By default, the taglist plugin will display the tags defined in all the loaded -buffers in the taglist window. If you prefer to display the tags defined only -in the current buffer, then you can set the 'Tlist_Show_One_File' to 1. When -this variable is set to 1, as you switch between buffers, the taglist window -will be refreshed to display the tags for the current buffer and the tags for -the previous buffer will be removed. -> - let Tlist_Show_One_File = 1 -< - *'Tlist_WinWidth'* -Tlist_WinWidth~ -The default width of the vertically split taglist window is 30. This can be -changed by modifying the 'Tlist_WinWidth' variable: > - - let Tlist_WinWidth = 20 -< -Note that the value of the |winwidth| option setting determines the minimum -width of the current window. If you set the 'Tlist_WinWidth' variable to a -value less than that of the |winwidth| option setting, then Vim will use the -value of the |winwidth| option. - - *'Tlist_Inc_Winwidth'* -Tlist_Inc_Winwidth~ -By default, when the width of the window is less than 100 and a new taglist -window is opened vertically, then the window width will be increased by the -value set in the Tlist_WinWidth variable to accommodate the new window. The -value of this variable is used only if you are using a vertically split -taglist window. - -If your terminal doesn't support changing the window width from Vim (older -version of xterm running in a Unix system) or if you see any weird problems in -the screen due to the change in the window width or if you prefer not to -adjust the window width then set the 'Tlist_Inc_Winwidth' variable to 0. -CAUTION: If you are using the MS-Windows version of Vim in a MS-DOS command -window then you must set this variable to 0, otherwise the system may hang due -to a Vim limitation (explained in :help win32-problems) > - - let Tlist_Inc_Winwidth = 0 -< - *'Tlist_WinHeight'* -Tlist_WinHeight~ -The default height of the horizontally split taglist window is 10. This can be -changed by modifying the 'Tlist_WinHeight' variable: > - - let Tlist_WinHeight = 20 < *'Tlist_Use_SingleClick'* Tlist_Use_SingleClick~ @@ -619,100 +718,33 @@ will be available in Vim 6.3 and above. In the meantime, instead of resizing the taglist window using the mouse, you can use normal Vim window resizing commands to resize the taglist window. - *'Tlist_Compact_Format'* -Tlist_Compact_Format~ -By default, empty lines are used to separate different tag types displayed for -a file and the tags displayed for different files in the taglist window. If -you want to display as many tags as possible in the taglist window, you can -set the Tlist_Compact_Format variable to one to get a compact display. > + *'Tlist_WinHeight'* +Tlist_WinHeight~ +The default height of the horizontally split taglist window is 10. This can be +changed by modifying the 'Tlist_WinHeight' variable: > - let Tlist_Compact_Format = 1 + let Tlist_WinHeight = 20 < - *'Tlist_Exit_OnlyWindow'* -Tlist_Exit_OnlyWindow~ -If you want to exit Vim if only the taglist window is currently opened, then -set the Tlist_Exit_OnlyWindow variable to one. By default, this variable is -set to zero and the Vim instance will not be closed if only the taglist window -is present. > +The 'winfixheight' option is set for the the taglist window, to maintain the +height of the taglist window, when new Vim windows are opened and existing +windows are closed. - let Tlist_Exit_OnlyWindow = 1 -< - *'Tlist_File_Fold_Auto_Close'* -Tlist_File_Fold_Auto_Close~ -By default, the tags tree displayed in the taglist window for all the files is -opened. You can close/fold the tags tree for the files manually. To -automatically close the tags tree for inactive files, you can set the -Tlist_File_Fold_Auto_Close variable to 1. When this variable is set to 1, if a -Vim buffer is no longer displayed in a Vim window, the corresponding tags tree -in the taglist window will be collapsed/folded. When a buffer is loaded in a -Vim window, the corresponding tags tree will be opened. -> - let Tlist_File_Fold_Auto_Close = 1 -< - *'Tlist_Enable_Fold_Column'* -Tlist_Enable_Fold_Column~ -By default, the Vim fold column is enabled and displayed in the taglist -window. If you wish to disable this (for example, when you are working with a -narrow Vim window or terminal), you can set the Tlist_Enable_Fold_Column -variable to 0. -> - let Tlist_Enable_Fold_Column = 1 -< - *'Tlist_Auto_Highlight_Tag'* -Tlist_Auto_Highlight_Tag~ -By default, the taglist plugin will highlight the current tag in the taglist -window. If you want to disable the highlighting of the current tag, then you -can set the Tlist_Auto_Highlight_Tag variable to zero. Note that even though -the current tag highlighting is disabled, the tags for a new file will still -be added to the taglist window. -> - let Tlist_Auto_Highlight_Tag = 0 -< - *'Tlist_Process_File_Always'* -Tlist_Process_File_Always~ -By default, the taglist plugin will generate and process the tags defined in -the newly opened files only when the taglist window is opened or when the -taglist menu is enabled. When the taglist window is closed, the taglist plugin -will stop processing the tags for newly opened files. + *'Tlist_WinWidth'* +Tlist_WinWidth~ +The default width of the vertically split taglist window is 30. This can be +changed by modifying the 'Tlist_WinWidth' variable: > -You can set the Tlist_Process_File_Always variable to 1 to generate the list -of tags for new files even when the taglist window is closed and the taglist -menu is disabled. -> - let Tlist_Process_File_Always = 1 + let Tlist_WinWidth = 20 < -You should set this variable to 1, if you want to use the :TlistShowTag and -:TlistShowPrototype commands without the taglist window and the taglist menu. +Note that the value of the |winwidth| option setting determines the minimum +width of the current window. If you set the 'Tlist_WinWidth' variable to a +value less than that of the |winwidth| option setting, then Vim will use the +value of the |winwidth| option. - *'Tlist_Show_Menu'* -Tlist_Show_Menu~ -When using GUI Vim, you can display the tags defined in the current file in a -menu named "Tags". By default, this feature is turned off. To turn on this -feature, set the Tlist_Show_Menu variable to one: -> - let Tlist_Show_Menu = 1 -< - *'Tlist_Max_Submenu_Items'* -Tlist_Max_Submenu_Items~ -If a file contains too many tags of a particular type (function, variable, -class, etc.), greater than that specified by the Tlist_Max_Submenu_Items -variable, then the menu for that tag type will be split into multiple -sub-menus. The default setting for the Tlist_Max_Submenu_Items variable is 25. -This can be changed by setting the Tlist_Max_Submenu_Items variable: -> - let Tlist_Max_Submenu_Items = 20 -< -The name of the submenu is formed using the names of the first and the last -tag entries in that submenu. +When new Vim windows are opened and existing windows are closed, the taglist +plugin will try to maintain the width of the taglist window to the size +specified by the Tlist_WinWidth variable. - *'Tlist_Max_Tag_Length'* -Tlist_Max_Tag_Length~ -Only the first Tlist_Max_Tag_Length characters from the tag names will be used -to form the tag type submenu name. Change the Tlist_Max_Tag_Length setting if -you want to include more or less characters: -> - let Tlist_Max_Tag_Length = 10 -< ============================================================================== *taglist-commands* 7. Commands~ @@ -720,18 +752,21 @@ you want to include more or less characters: The taglist plugin provides the following ex-mode commands: |:Tlist| Open or close (toggle) the taglist window. +|:TlistAddFiles| Add multiple files to the taglist window. |:TlistClose| Close the taglist window. -|:TlistUpdate| Update the tags for the current buffer. -|:TlistSync| Highlight the current tag in the taglist window. -|:TlistShowPrototype| Display the prototype of the tag at or below the - specified line number. -|:TlistShowTag| Display the name of the tag defined at or below the - specified line number. -|:TlistSessionSave| Save the information about files and tags in use. -|:TlistSessionLoad| Load information about files and tags last saved. |:TlistDebug| Start logging of taglist debug messages. -|:TlistUndebug| Stop logging of taglist debug messages. |:TlistMessages| Display the logged taglist plugin debug messages. +|:TlistSessionSave| Save the information about files and tags displayed + in the taglist window to a session file. +|:TlistSessionLoad| Load the information about files and tags stored + in a session file to the taglist window. +|:TlistShowPrototype| Display the prototype of the tag at or above the + specified line number. +|:TlistShowTag| Display the name of the tag defined at or above the + specified line number. +|:TlistSync| Highlight the current tag in the taglist window. +|:TlistUndebug| Stop logging of taglist debug messages. +|:TlistUpdate| Update the tags for the current buffer. *:Tlist* :Tlist Open or close (toggle) the taglist window. Opens the taglist @@ -741,24 +776,39 @@ The taglist plugin provides the following ex-mode commands: in the buffer list are processed and the tags are displayed in the taglist window. + *:TlistAddFiles* +:TlistAddFiles {file(s)} [file(s) ...] + Process the tags defined in the specified file(s) and add them + to the taglist window. The files will not be edited and will + not be added to the Vim buffer list. You can specify + filenames using patterns. + *:TlistClose* :TlistClose Close the taglist window. This command can be used from any one of the Vim windows. - *:TlistUpdate* -:TlistUpdate Update the tags displayed for the current buffer. This - command can be used to force an update of the tags for the - current file/buffer. As the taglist plugin uses the file saved - in the disk (instead of the file displayed in a Vim buffer), - you should save the modified buffer before you update the - taglist window. Otherwise the listed tags will not include the - new tags created in the buffer. + *:TlistDebug* +:TlistDebug + Start logging of debug messages from the taglist plugin. + The debug messages are stored in a script local variable by + the taglist plugin. - *:TlistSync* -:TlistSync Highlight the current tag in the taglist window. By default, - the taglist plugin periodically updates the taglist window to - highlight the current tag. This command can be used to force - the taglist plugin to highlight the current tag. + *:TlistMessages* +:TlistMessages + Display the logged debug messages from the taglist plugin. + + *:TlistSessionSave* +:TlistSessionSave {filename} + Save the information about files and tags displayed in the + taglist window to the specified file. This command can be used + to save and restore the taglist window contents across Vim + sessions. + + *:TlistSessionLoad* +:TlistSessionLoad {filename} + Load the information about files and tags stored in the + specified session file and update the taglist window with + the tags stored in the session file. *:TlistShowPrototype* :TlistShowPrototype [filename] [linenumber] @@ -779,32 +829,24 @@ The taglist plugin provides the following ex-mode commands: it is defined to the line before the next tag. This command displays the tag name for any line number in this range. - *:TlistSessionSave* -:TlistSessionSave {filename} - Save the information about files and tags displayed in the - taglist window to the specified file. This command can be used - to save and restore the taglist window contents across Vim - sessions. - - *:TlistSessionLoad* -:TlistSessionLoad {filename} - Load the information about files and tags stored in the - specified session file and update the taglist window with - the tags stored in the session file. - - *:TlistDebug* -:TlistDebug - Start logging of debug messages from the taglist plugin. - The debug messages are stored in a script local variable by - the taglist plugin. + *:TlistSync* +:TlistSync Highlight the current tag in the taglist window. By default, + the taglist plugin periodically updates the taglist window to + highlight the current tag. This command can be used to force + the taglist plugin to highlight the current tag. *:TlistUndebug* :TlistUndebug Stop logging of debug messages from the taglist plugin. - *:TlistMessages* -:TlistMessages - Display the logged debug messages from the taglist plugin. + *:TlistUpdate* +:TlistUpdate Update the tags displayed for the current buffer. This + command can be used to force an update of the tags for the + current file/buffer. As the taglist plugin uses the file saved + in the disk (instead of the file displayed in a Vim buffer), + you should save the modified buffer before you update the + taglist window. Otherwise the listed tags will not include the + new tags created in the buffer. ============================================================================== *taglist-functions* @@ -1016,6 +1058,19 @@ A. Are you using Vim version 6.0 and above? The taglist plugin relies on the name, then try adding the directory to the PATH environment variable or try copying the exuberant ctags to a path without space characters in the name. +Q. When I try to open the taglist window, I am seeing the following error + message. How do I fix this problem? + + Taglist: Failed to generate tags for /my/path/to/file + ctags: illegal option -- -^@usage: ctags [-BFadtuwvx] [-f tagsfile] file ... + +A. The taglist plugin will work only with the exuberant ctags tool. You + cannot use the GNU ctags or the Unix ctags program with the taglist plugin. + You will see an error message similar to the one shown above, if you try + use a non-exuberant ctags program with Vim. To fix this problem, either add + the exuberant ctags tool location to the PATH environment variable or set + the Tlist_Ctags_Cmd variable. + Q. A file has more than one tag with the same name. When I select a tag name from the taglist window, the cursor is positioned at the incorrect tag location. @@ -1058,9 +1113,9 @@ A. The taglist plugin uses the |CursorHold| autocmd to highlight the current *taglist-todo* 11. Todo~ -1. Support for displaying tags in a modified (not-yet-saved) file. -2. Group tags according to the scope and display them. For example, +1. Group tags according to the scope and display them. For example, group all the tags belonging to a C++/Java class +2. Support for displaying tags in a modified (not-yet-saved) file. 3. Automatically open the taglist window only for selected filetypes. For other filetypes, close the taglist window. 4. Taglist plugin doesn't work properly with the Vim session support. diff --git a/plugin/taglist.vim b/plugin/taglist.vim index 67008e1..901b5be 100644 --- a/plugin/taglist.vim +++ b/plugin/taglist.vim @@ -1,7 +1,7 @@ " File: taglist.vim " Author: Yegappan Lakshmanan (yegappan AT yahoo DOT com) -" Version: 4.0 Beta1 -" Last Modified: April 4, 2005 +" Version: 4.0 Beta 2 +" Last Modified: July 21, 2005 " " The "Tag List" plugin is a source code browser plugin for Vim and provides " an overview of the structure of the programming language files and allows @@ -458,7 +458,8 @@ function! s:Tlist_Log_Msg(msg) if len > 3000 let s:tlist_msg = strpart(s:tlist_msg, len - 3000) endif - let s:tlist_msg = s:tlist_msg . strftime('%T') . ': ' . a:msg . "\n" + let s:tlist_msg = s:tlist_msg . strftime('%H:%M:%S') . ': ' . + \ a:msg . "\n" endif endfunction @@ -537,8 +538,7 @@ endfunction " Tlist_User_Removed_File " Returns 1 if a file is removed by a user from the taglist function! s:Tlist_User_Removed_File(filename) - let esc_fname = escape(a:filename, '\') . "\n" - return match(s:tlist_removed_flist, esc_fname) != -1 + return stridx(s:tlist_removed_flist, a:filename . "\n") != -1 endfunction " Tlist_Update_Remove_List @@ -549,9 +549,13 @@ function! s:Tlist_Update_Remove_List(filename, add) if a:add let s:tlist_removed_flist = s:tlist_removed_flist . a:filename . "\n" else - let esc_fname = escape(a:filename, '\') . "\n" - let s:tlist_removed_flist = substitute(s:tlist_removed_flist, - \ esc_fname, '', '') + let idx = stridx(s:tlist_removed_flist, a:filename . "\n") + let text_before = strpart(s:tlist_removed_flist, 0, idx) + let rem_text = strpart(s:tlist_removed_flist, idx) + let next_idx = stridx(rem_text, "\n") + let text_after = strpart(rem_text, next_idx + 1) + + let s:tlist_removed_flist = text_before . text_after endif endfunction @@ -912,8 +916,13 @@ function! s:Tlist_Open_Window() " needed, to accomodate the new window if g:Tlist_Inc_Winwidth && \ &columns < (80 + g:Tlist_WinWidth) + " Save the original window position + let s:tlist_pre_winx = getwinposx() + let s:tlist_pre_winy = getwinposy() + " one extra column is needed to include the vertical split let &columns= &columns + g:Tlist_WinWidth + 1 + let s:tlist_winsize_chgd = 1 else let s:tlist_winsize_chgd = 0 @@ -943,6 +952,10 @@ function! s:Tlist_Open_Window() " Create the taglist window exe 'silent! ' . win_dir . ' ' . win_size . 'split ' . wcmd + " Save the new window position + let s:tlist_winx = getwinposx() + let s:tlist_winy = getwinposy() + " Initialize the taglist window call s:Tlist_Init_Window() endfunction @@ -970,6 +983,32 @@ function! s:Tlist_Zoom_Window() endif endfunction +" Tlist_Check_Window_Size +" Check the width of the taglist window. For horizontally split windows, the +" 'winfixheight' option is used to fix the height of the window. For +" vertically split windows, Vim doesn't support the 'winfixwidth' option. So +" need to handle window width changes from this function. +function! s:Tlist_Check_Window_Width() + let tlist_winnr = bufwinnr(g:TagList_title) + if tlist_winnr == -1 + return + endif + + let width = winwidth(tlist_winnr) + if width != g:Tlist_WinWidth + call s:Tlist_Log_Msg("Tlist_Check_Window_Width: Changing window " . + \ "width from " . width . "to " . g:Tlist_WinWidth) + let save_winnr = winnr() + if save_winnr != tlist_winnr + exe tlist_winnr . 'wincmd w' + endif + exe 'vert resize ' . g:Tlist_WinWidth + if save_winnr != tlist_winnr + wincmd p + endif + endif +endfunction + " Tlist_Init_Window " Set the default options for the taglist window function! s:Tlist_Init_Window() @@ -1052,6 +1091,13 @@ function! s:Tlist_Init_Window() " window silent! setlocal nonumber + " Use fixed height when horizontally split window is used + if g:Tlist_Use_Horiz_Window + if v:version >= 602 + set winfixheight + endif + endif + " Setup the cpoptions properly for the maps to work let old_cpoptions = &cpoptions set cpoptions&vim @@ -1138,24 +1184,32 @@ function! s:Tlist_Init_Window() " Display the tag prototype for the tag under the cursor. autocmd CursorHold __Tag_List__ call s:Tlist_Show_Tag_Prototype() " Highlight the current tag periodically - autocmd CursorHold * silent call Tlist_Highlight_Tag( - \ fnamemodify(bufname('%'), ':p'), line('.'), 1) + autocmd CursorHold * silent call s:Tlist_Highlight_Tag( + \ fnamemodify(bufname('%'), ':p'), line('.'), 1, 0) " Adjust the Vim window width when taglist window is closed - autocmd BufUnload __Tag_List__ call Tlist_Post_Close_Cleanup() + autocmd BufUnload __Tag_List__ call s:Tlist_Post_Close_Cleanup() " Close the fold for this buffer when it's not visible in any window - autocmd BufWinLeave * silent call Tlist_Update_File_Display( + if g:Tlist_File_Fold_Auto_Close + autocmd BufWinLeave * silent call s:Tlist_Update_File_Display( \ fnamemodify(expand(''), ':p'), 1) + endif " Remove the file from the list when it's buffer is deleted - autocmd BufDelete * silent call Tlist_Update_File_Display( + autocmd BufDelete * silent call s:Tlist_Update_File_Display( \ fnamemodify(expand(''), ':p'), 2) " Exit Vim itself if only the taglist window is present (optional) - autocmd BufEnter __Tag_List__ call Tlist_Check_Only_Window() + if g:Tlist_Exit_OnlyWindow + autocmd BufEnter __Tag_List__ if winbufnr(2) == -1 | quit | endif + endif if s:tlist_app_name != "winmanager" && \ !g:Tlist_Process_File_Always && \ (!has('gui_running') || !g:Tlist_Show_Menu) " Auto refresh the taglist window - autocmd BufEnter * call Tlist_Refresh() + autocmd BufEnter * call s:Tlist_Refresh() + endif + + if !g:Tlist_Use_Horiz_Window + autocmd WinEnter * call s:Tlist_Check_Window_Width() endif augroup end @@ -1258,6 +1312,14 @@ function! s:Tlist_Post_Close_Cleanup() " window or if columns is less than 101 or if the user chose not to " adjust the window width else + " If the user didn't manually move the window, then restore the window + " position to the pre-taglist position + if s:tlist_pre_winx != -1 && s:tlist_pre_winy != -1 && + \ getwinposx() == s:tlist_winx && + \ getwinposy() == s:tlist_winy + exe 'winpos ' . s:tlist_pre_winx . ' ' . s:tlist_pre_winy + endif + " Adjust the Vim window width let &columns= &columns - (g:Tlist_WinWidth + 1) endif @@ -1270,19 +1332,6 @@ function! s:Tlist_Post_Close_Cleanup() endif endfunction -" Tlist_Check_Only_Window -" Check if only the taglist window is opened currently. If the -" Tlist_Exit_OnlyWindow variable is set, then close the taglist window -function! s:Tlist_Check_Only_Window() - if g:Tlist_Exit_OnlyWindow - if winbufnr(2) == -1 && bufname(winbufnr(1)) == g:TagList_title - " If only the taglist window is currently open, then the buffer - " number associated with window 2 will be -1. - quit - endif - endif -endfunction - " Tlist_Explore_File() " List the tags defined in the specified file in a Vim window function! s:Tlist_Explore_File(filename, ftype) @@ -1733,7 +1782,7 @@ function! s:Tlist_Process_File(filename, ftype) " No tags for current file if cmd_output == '' - call s:Tlist_Warning_Msg('Taglist: No tags found for ' . a:filename) + call s:Tlist_Warning_Msg('Taglist: No tags defined in ' . a:filename) return fidx endif @@ -1752,7 +1801,7 @@ function! s:Tlist_Process_File(filename, ftype) " Process the ctags output one line at a time. The substitute() " command is used to parse the tag lines instead of using the " matchstr()/stridx()/strpart() functions for performance reason - call substitute(cmd_output, '\(.\{-}\)\n', + call substitute(cmd_output, "\\([^\n]\\+\\)\n", \ '\=s:Tlist_Parse_Tagline(submatch(1))', 'g') " Save the number of tags for this file @@ -1888,6 +1937,17 @@ function! Tlist_Update_File_Tags(filename, ftype) " and return call s:Tlist_Process_File(fname, a:ftype) else + if g:Tlist_Show_One_File && s:tlist_cur_file_idx != -1 + " If tags for only one file are displayed and we are not + " updating the tags for that file, then no need to + " refresh the taglist window. Otherwise, the taglist + " window should be updated. + if s:tlist_{s:tlist_cur_file_idx}_filename != fname + call s:Tlist_Process_File(fname, a:ftype) + return + endif + endif + " Save the current window number let save_winnr = winnr() @@ -1997,7 +2057,7 @@ function! s:Tlist_Toggle_Window() endif " Highlight the current tag - call s:Tlist_Highlight_Tag(curbuf_name, cur_lnum, 1) + call s:Tlist_Highlight_Tag(curbuf_name, cur_lnum, 1, 1) " Go back to the original window let prev_Tlist_Skip_Refresh = s:Tlist_Skip_Refresh @@ -2011,6 +2071,61 @@ function! s:Tlist_Toggle_Window() endif endfunction +" Tlist_Add_Files +" Add the specified list of files to the taglist +function! s:Tlist_Add_Files(...) + let flist = '' + let i = 1 + + " Get all the files matching the file patterns supplied as argument + while i <= a:0 + let flist = flist . glob(a:{i}) . "\n" + let i = i + 1 + endwhile + + if flist == '' + call s:Tlist_Warning_Msg('Error: No matching files are found') + return + endif + + let flist = flist . "\n" + + " Enable lazy screen updates + let old_lazyredraw = &lazyredraw + set lazyredraw + + " Ignore the filetype autocommands + let old_eventignore = &eventignore + set eventignore=FileType + + " Save the 'filetype', as this will be changed temporarily + let old_filetype = &filetype + + " Process one file at a time + while flist != '' + let one_file = strpart(flist, 0, stridx(flist, "\n")) + + let flist = strpart(flist, stridx(flist, "\n") + 1) + + " Run the filetypedetect group of autocommands to determine + " the filetype for one_file + exe 'doautocmd filetypedetect BufRead ' . one_file + + echon "\r " + echon "\rProcessing tags for " . fnamemodify(one_file, ':p:t') + + silent call Tlist_Update_File_Tags(one_file, &filetype) + endwhile + + " Clear the displayed informational messages + echon "\r " + + " Restore the previous state + let &filetype = old_filetype + let &eventignore = old_eventignore + let &lazyredraw = old_lazyredraw +endfunction + " Tlist_Extract_Tagtype " Extract the tag type from the tag text function! s:Tlist_Extract_Tagtype(tag_line) @@ -2112,6 +2227,15 @@ function! s:Tlist_Refresh() " Update the taglist window if tlist_win != -1 + if g:Tlist_Show_One_File && s:tlist_cur_file_idx != fidx + " If displaying tags for only one file in the taglist + " window and about to display the tags for a new file, + " then center the current tag line for the new file + let center_tag_line = 1 + else + let center_tag_line = 0 + endif + " Disable screen updates let old_lazyredraw = &lazyredraw set nolazyredraw @@ -2132,11 +2256,16 @@ function! s:Tlist_Refresh() call s:Tlist_Explore_File(filename, ftype) " Highlight the current tag - call s:Tlist_Highlight_Tag(filename, cur_lnum, 1) + call s:Tlist_Highlight_Tag(filename, cur_lnum, 1, center_tag_line) if !g:Tlist_Auto_Highlight_Tag " Restore the cursor position - call cursor(save_line, save_col) + if v:version >= 601 + call cursor(save_line, save_col) + else + exe save_line + exe 'normal! ' . save_col . '|' + endif endif if s:tlist_app_name != "winmanager" @@ -2256,9 +2385,8 @@ function! s:Tlist_Update_Window() endfunction " Tlist_Get_Tag_Index() -" Return the tag index for the current line -function! s:Tlist_Get_Tag_Index(fidx) - let lnum = line('.') +" Return the tag index for the specified line +function! s:Tlist_Get_Tag_Index(fidx, lnum) let ftype = s:tlist_{a:fidx}_filetype " Determine to which tag type the current line number belongs to using the @@ -2268,7 +2396,7 @@ function! s:Tlist_Get_Tag_Index(fidx) let ttype = s:tlist_{ftype}_{i}_name let start_lnum = s:tlist_{a:fidx}_start + s:tlist_{a:fidx}_{ttype}_start let end = start_lnum + s:tlist_{a:fidx}_{ttype}_count - if lnum >= start_lnum && lnum <= end + if a:lnum >= start_lnum && a:lnum <= end break endif let i = i + 1 @@ -2280,7 +2408,7 @@ function! s:Tlist_Get_Tag_Index(fidx) endif " Compute the index into the displayed tags for the tag type - let tidx = lnum - start_lnum + let tidx = a:lnum - start_lnum if tidx == 0 return 0 endif @@ -2316,18 +2444,24 @@ function! s:Tlist_Jump_To_Tag(win_ctrl) return endif - " If inside a fold, then don't try to jump to the tag - if foldclosed('.') != -1 - return + " If inside a closed fold, then use the first line of the fold + " and jump to the file. + let lnum = foldclosed('.') + if lnum == -1 + " Jump to the selected tag or file + let lnum = line('.') + else + " Open the closed fold + .foldopen! endif - let fidx = s:Tlist_Get_File_Index_By_Linenum(line('.')) + let fidx = s:Tlist_Get_File_Index_By_Linenum(lnum) if fidx == -1 return endif " Get the tag output for the current tag - let tidx = s:Tlist_Get_Tag_Index(fidx) + let tidx = s:Tlist_Get_Tag_Index(fidx, lnum) if tidx != 0 let tagpat = s:Tlist_Get_Tag_SearchPat(fidx, tidx) @@ -2427,6 +2561,9 @@ function! s:Tlist_Open_File(win_ctrl, filename, tagpat) " Jump to the tag if a:tagpat != '' + " Add the current cursor position to the jump list, so that user can + " jump back using the ' and ` marks. + mark ' silent call search(a:tagpat, 'w') endif @@ -2473,14 +2610,16 @@ function! s:Tlist_Show_Tag_Prototype() return endif + let lnum = line('.') + " Get the file index - let fidx = s:Tlist_Get_File_Index_By_Linenum(line('.')) + let fidx = s:Tlist_Get_File_Index_By_Linenum(lnum) if fidx == -1 return endif " Get the tag output line for the current tag - let tidx = s:Tlist_Get_Tag_Index(fidx) + let tidx = s:Tlist_Get_Tag_Index(fidx, lnum) if tidx == 0 return endif @@ -2561,7 +2700,8 @@ endfunction " Highlight the current tag " cntx == 1, Called by the taglist plugin itself " cntx == 2, Forced by the user through the TlistSync command -function! s:Tlist_Highlight_Tag(filename, cur_lnum, cntx) +" center = 1, move the tag line to the center of the taglist window +function! s:Tlist_Highlight_Tag(filename, cur_lnum, cntx, center) " Highlight the current tag only if the user configured the " taglist plugin to do so or if the user explictly invoked the " command to highlight the current tag. @@ -2664,10 +2804,15 @@ function! s:Tlist_Highlight_Tag(filename, cur_lnum, cntx) .foldopen endif - " Make sure the current tag line is visible in the taglist window. - " Calling the winline() function makes the line visible. Don't know - " of a better way to achieve this. - call winline() + if a:center + " Move the tag line to the center of the taglist window + normal! z. + else + " Make sure the current tag line is visible in the taglist window. + " Calling the winline() function makes the line visible. Don't know + " of a better way to achieve this. + call winline() + endif " Highlight the tag name call s:Tlist_Highlight_Tagline() @@ -2972,7 +3117,7 @@ function! s:Tlist_Session_Load(...) let s:Tlist_Skip_Refresh = prev_Tlist_Skip_Refresh " Highlight the current tag - call s:Tlist_Highlight_Tag(fnamemodify(bufname('%'), ':p'), line('.'), 1) + call s:Tlist_Highlight_Tag(fnamemodify(bufname('%'), ':p'), line('.'), 1, 1) endfunction " Tlist_Session_Save @@ -3001,6 +3146,9 @@ function! s:Tlist_Session_Save(...) echo "\n" endif + let old_verbose = &verbose + set verbose&vim + exe 'redir! > ' . sessionfile silent! echo '" Taglist session file. This file is auto-generated.' @@ -3058,6 +3206,8 @@ function! s:Tlist_Session_Save(...) endwhile redir END + + let &verbose = old_verbose endfunction " Tlist_Update_File_Display @@ -3065,7 +3215,8 @@ endfunction " action == 1, Close the fold for the file " action == 2, Remove the file from the taglist window function! s:Tlist_Update_File_Display(filename, action) - call s:Tlist_Log_Msg('Tlist_Update_File_Display (' . a:filename . ')') + call s:Tlist_Log_Msg('Tlist_Update_File_Display (' . a:filename . + \ ', action = ' . a:action . ')') " Make sure a valid filename is supplied if a:filename == '' return @@ -3123,23 +3274,48 @@ function! s:Tlist_Update_File_Display(filename, action) endif endfunction +" Tlist_Auto_Open_Check +" Open the taglist window automatically on Vim startup. +" Open the window only when files present in any of the Vim windows support +" tags. +function! s:Tlist_Check_Auto_Open () + let open = 0 + + let i = 1 + let buf_num = winbufnr(i) + while buf_num != -1 + let filename = fnamemodify(bufname(buf_num), ':p') + if !s:Tlist_Skip_File(filename, getbufvar(buf_num, '&filetype')) + let open = 1 + break + endif + let i = i + 1 + let buf_num = winbufnr(i) + endwhile + + if open + call s:Tlist_Toggle_Window() + endif +endfunction + " Define the taglist autocommand to automatically open the taglist window on " Vim startup if g:Tlist_Auto_Open - autocmd VimEnter * nested Tlist + autocmd VimEnter * nested call s:Tlist_Check_Auto_Open() endif " Refresh the taglist if g:Tlist_Process_File_Always - autocmd BufEnter * call Tlist_Refresh() + autocmd BufEnter * call s:Tlist_Refresh() endif " Define the user commands to manage the taglist window command! -nargs=0 Tlist call s:Tlist_Toggle_Window() +command! -nargs=+ -complete=file TlistAddFiles call s:Tlist_Add_Files() command! -nargs=0 TlistClose call s:Tlist_Close_Window() command! -nargs=0 TlistUpdate call s:Tlist_Update_Tags() command! -nargs=0 TlistSync call s:Tlist_Highlight_Tag( - \ fnamemodify(bufname('%'), ':p'), line('.'), 2) + \ fnamemodify(bufname('%'), ':p'), line('.'), 2, 1) command! -nargs=* -complete=buffer TlistShowPrototype \ echo Tlist_Get_Tag_Prototype_By_Line() command! -nargs=* -complete=buffer TlistShowTag @@ -3233,19 +3409,6 @@ function! s:Tlist_Menu_Get_Tag_Type_Cmd(fidx, ftype, ttype_idx) let tname = s:tlist_{a:fidx}_{tidx}_tag_name - " If there is more than one tag with the same name, then - " add a count to the end of the menu name. Otherwise only - " one menu entry will be added for multiple tags with the - " same name (overloaded functions). - "let var_name = ttype . '_' . - " \ substitute(tname, '\W', '__tagname__', 'g') - "if exists(var_name) - " let {var_name} = {var_name} + 1 - " let tname = tname . '\ (' . {var_name} . ')' - "else - " let {var_name} = 1 - "endif - let mcmd = mcmd . m_prefix . '\&' . \ s:menu_char_prefix[m_prefix_idx] . '\.' . \ tname . ' :call Tlist_Menu_Jump_To_Tag(' . @@ -3266,19 +3429,6 @@ function! s:Tlist_Menu_Get_Tag_Type_Cmd(fidx, ftype, ttype_idx) let tname = s:tlist_{a:fidx}_{tidx}_tag_name - " If there is more than one tag with the same name, then - " add a count to the end of the menu name. Otherwise only - " one menu entry will be added for multiple tags with the - " same name (overloaded functions). - "let var_name = ttype . '_' . - " \ substitute(tname, '\W', '__tagname__', 'g') - "if exists(var_name) - " let {var_name} = {var_name} + 1 - " let tname = tname . '\ (' . {var_name} . ')' - "else - " let {var_name} = 1 - "endif - let mcmd = mcmd . m_prefix . '\&' . \ s:menu_char_prefix[m_prefix_idx] . '\.' . \ tname . ' :call Tlist_Menu_Jump_To_Tag(' . tidx @@ -3447,6 +3597,10 @@ function! s:Tlist_Menu_Jump_To_Tag(tidx) return endif + " Add the current cursor position to the jump list, so that user can + " jump back using the ' and ` marks. + mark ' + silent call search(tagpat, 'w') " Bring the line to the middle of the window @@ -3468,7 +3622,7 @@ function! s:Tlist_Menu_Init() autocmd! if !g:Tlist_Process_File_Always - autocmd BufEnter * call Tlist_Refresh() + autocmd BufEnter * call s:Tlist_Refresh() endif autocmd BufLeave * call s:Tlist_Menu_Remove_File() augroup end @@ -3477,7 +3631,7 @@ function! s:Tlist_Menu_Init() endfunction if g:Tlist_Show_Menu - autocmd GUIEnter * call Tlist_Menu_Init() + autocmd GUIEnter * call s:Tlist_Menu_Init() endif " Tlist_Set_App