diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | INSTALL.md | 3 | ||||
| -rw-r--r-- | README.md | 551 | ||||
| -rw-r--r-- | TODO.md | 34 | ||||
| -rw-r--r-- | autoload/xolox/easytags.vim | 1028 | ||||
| -rw-r--r-- | doc/easytags.txt | 659 | ||||
| -rw-r--r-- | misc/easytags/highlight.py | 55 | ||||
| -rwxr-xr-x | misc/easytags/normalize-tags.py | 80 | ||||
| -rwxr-xr-x | misc/easytags/why-so-slow.py | 39 | ||||
| -rw-r--r-- | plugin/easytags.vim | 181 |
10 files changed, 2273 insertions, 358 deletions
diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..926ccaa --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +doc/tags diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..1d863ca --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,3 @@ +If you're looking for the simplest way to get the plug-in up and running, download [the latest ZIP archive](http://peterodding.com/code/vim/downloads/easytags.zip) from [Vim Online](http://www.vim.org/scripts/script.php?script_id=3114), unzip that in `~/.vim/` (on UNIX) or `%USERPROFILE%\vimfiles` (on Windows) and you're good to go. + +If you're using git and/or [Pathogen](http://www.vim.org/scripts/script.php?script_id=2332), [Vundle](https://github.com/gmarik/vundle) or a similar plug-in manager and want to keep the plug-in up to date using git, you can use the GitHub repository directly, it should just work. @@ -1,503 +1,338 @@ -# Miscellaneous auto-load Vim scripts +# Automated tag generation and syntax highlighting in Vim -The git repository at [github.com/xolox/vim-misc] [repository] contains Vim -scripts that are used by most of the [Vim plug-ins I've written] [plugins] yet -don't really belong with any single one of the plug-ins. Basically it's an -extended standard library of Vim script functions that I wrote during the -development of my Vim plug-ins. +[Vim] [vim] has long been my favorite text editor and combined with [Exuberant Ctags] [exctags] it has the potential to provide most of what I expect from an [integrated development environment] [ide]. Exuberant Ctags is the latest incarnation of a [family of computer programs] [ctags] that scan source code files to create an index of identifiers (tags) and where they are defined. Vim uses this index (a so-called tags file) to enable you to jump to the definition of any identifier using the [Control-]] [ctrl_mapping] mapping. -The miscellaneous scripts are bundled with each of my plug-ins using git -merges, so that a repository checkout of a plug-in contains everything that's -needed to get started. This means the git repository of the miscellaneous -scripts is only used to track changes in a central, public place. +When you're familiar with integrated development environments you may recognize this feature as "Go-to definition". One advantage of the combination of Vim and Exuberant Ctags over integrated development environments is that Vim supports syntax highlighting for [over 500 file types] [vim_fts] (!) and Exuberant Ctags can generate tags for [over 40 file types] [ctags_fts] as well... -## Documentation for the included functions +There's just one problem: You have to manually keep your tags files up-to-date and this turns out to be a royal pain in the ass! So I set out to write a Vim plug-in that would do this boring work for me. When I finished the plug-in's basic functionality (one automatic command and a call to [system()] [system] later) I became interested in dynamic syntax highlighting, so I added that as well to see if it would work -- surprisingly well I'm happy to report! -The documentation of the 41 functions below was extracted from 12 Vim scripts -on May 19, 2013 at 23:27. +## Installation -### Handling of special buffers +Unzip the most recent [ZIP archive] [download] file inside your Vim profile directory (usually this is `~/.vim` on UNIX and `%USERPROFILE%\vimfiles` on Windows), restart Vim and execute the command `:helptags ~/.vim/doc` (use `:helptags ~\vimfiles\doc` instead on Windows). Now try it out: Edit any file type supported by Exuberant Ctags and within ten seconds the plug-in should create/update your tags file (`~/.vimtags` on UNIX, `~/_vimtags` on Windows) with the tags defined in the file you just edited! This means that whatever file you're editing in Vim (as long as it's on the local file system), tags will always be available by the time you need them! -The functions defined here make it easier to deal with special Vim buffers -that contain text generated by a Vim plug-in. For example my [vim-notes -plug-in] [vim-notes] generates several such buffers: +Additionally if the file you just opened is an AWK, C#, C, C++, Objective-C, Java, Lua, PHP, Python, Ruby, Shell, Tcl or Vim source file you should also notice that the function and type names defined in the file have been syntax highlighted. -- [:RecentNotes] [RecentNotes] lists recently modified notes -- [:ShowTaggedNotes] [ShowTaggedNotes] lists notes grouped by tags -- etc. +The `easytags.vim` plug-in is intended to work automatically once it's installed, but if you want to change how it works there are several options you can change and commands you can execute from your own mappings and/or automatic commands. These are all documented below. -Because the text in these buffers is generated, Vim shouldn't bother with -swap files and it should never prompt the user whether to save changes to -the generated text. +Note that if the plug-in warns you `ctags` isn't installed you'll have to download it from its [homepage] [exctags], or if you're running Debian/Ubuntu you can install it by executing the following shell command: -[vim-notes]: http://peterodding.com/code/vim/notes/ -[RecentNotes]: http://peterodding.com/code/vim/notes/#recentnotes_command -[ShowTaggedNotes]: http://peterodding.com/code/vim/notes/#showtaggednotes_command + $ sudo apt-get install exuberant-ctags -#### The `xolox#misc#buffer#is_empty()` function +### A note about Windows -Checks if the current buffer is an empty, unchanged buffer which can be -reused. Returns 1 if an empty buffer is found, 0 otherwise. +On Windows the [system()] [system] function used by `easytags.vim` causes a command prompt window to pop up while Exuberant Ctags is executing. If this bothers you then you can install my [shell.vim] [shell] plug-in which includes a [DLL] [dll] that works around this issue. Once you've installed both plug-ins it should work out of the box! Please let me know if this doesn't work for you. -#### The `xolox#misc#buffer#prepare()` function +## Commands -Open a special buffer, i.e. a buffer that will hold generated contents, -not directly edited by the user. The buffer can be customized by passing a -dictionary with the following key/value pairs as the first argument: +### The `:UpdateTags` command -- **name** (required): The base name of the buffer (i.e. the base name of - the file loaded in the buffer, even though it isn't really a file and - nothing is really 'loaded' :-) -- **path** (required): The pathname of the buffer. May be relevant if - [:lcd] [lcd] or ['autochdir'] [acd] is being used. +This command executes [Exuberant Ctags] [exctags] from inside Vim to update the global tags file defined by `g:easytags_file`. When no arguments are given the tags for the current file are updated, otherwise the arguments are passed on to `ctags`. For example when you execute the Vim command `:UpdateTags -R ~/.vim` (or `:UpdateTags -R ~\vimfiles` on Windows) the plug-in will execute `ctags -R ~/.vim` for you (with some additional arguments, see the troubleshooting section "`:HighlightTags` only works for the tags file created by `:UpdateTags`" for more information). -[lcd]: http://vimdoc.sourceforge.net/htmldoc/editing.html#:lcd -[acd]: http://vimdoc.sourceforge.net/htmldoc/options.html#'autochdir' +When you execute this command like `:UpdateTags!` (including the bang!) then all tags whose files are missing will be filtered from the global tags file. -#### The `xolox#misc#buffer#lock()` function +Note that this command will be executed automatically every once in a while, assuming you haven't changed `g:easytags_on_cursorhold`. -Lock a special buffer so that its contents can no longer be edited. +### The `:HighlightTags` command -#### The `xolox#misc#buffer#unlock()` function +When you execute this command while editing one of the supported file types (see above) the relevant tags in the current file are highlighted. The tags to highlight are gathered from all tags files known to Vim (through the ['tags' option] [tags_opt]). -Unlock a special buffer so that its content can be updated. +Note that this command will be executed automatically every once in a while, assuming you haven't changed `g:easytags_on_cursorhold`. -### Compatibility checking +## Options -This Vim script defines a version number for the miscellaneous scripts. Each -of my plug-ins compares their expected version of the miscellaneous scripts -against the version number defined inside the miscellaneous scripts. +The easytags plug-in should work out of the box but if you don't like the default configuration you can change how it works by setting the variables documented below. Most of these variables can also be changed for specific files by setting a buffer local variable instead of the global variable. For example to disable automatic highlighting (enabled by default) only in Python files you can add the following line to your [vimrc script] [vimrc]: -The version number is incremented whenever a change in the miscellaneous -scripts breaks backwards compatibility. This enables my Vim plug-ins to fail -early when they detect an incompatible version, instead of breaking at the -worst possible moments :-). + :autocmd FileType python let b:easytags_auto_highlight = 0 -#### The `xolox#misc#compat#check()` function +Note that buffer local variables always override global variables, so if you want to undo this for a specific file you have to use [:unlet] [unlet]: -Expects two arguments: The name of a Vim plug-in and the version of the -miscellaneous scripts expected by the plug-in. When the active version of -the miscellaneous scripts has a different version, this will raise an -error message that explains what went wrong. + :unlet b:easytags_auto_highlight -### Tab completion for user defined commands +### The `g:easytags_cmd` option -#### The `xolox#misc#complete#keywords()` function +The plug-in will try to determine the location where Exuberant Ctags is installed on its own but this might not always work because any given executable named `ctags` in your `$PATH` might not in fact be Exuberant Ctags but some older, more primitive `ctags` implementation which doesn't support the same command line options and thus breaks the easytags plug-in. If this is the case you can set the global variable `g:easytags_cmd` to the location where you've installed Exuberant Ctags, e.g.: -This function can be used to perform keyword completion for user defined -Vim commands based on the contents of the current buffer. Here's an -example of how you would use it: + :let g:easytags_cmd = '/usr/local/bin/ctags' - :command -nargs=* -complete=customlist,xolox#misc#complete#keywords MyCmd call s:MyCmd(<f-args>) +If you rely entirely on language-specific configuration and don't have a general ctags program, set this to the empty string. -### String escaping functions +### The `g:easytags_languages` option -#### The `xolox#misc#escape#pattern()` function +Exuberant Ctags supports many languages and can be extended via regular expression patterns, but for some languages separate tools with ctags-compatible output exist (e.g. [jsctags] [jsctags] for Javascript). To use these, the executable and its arguments must be configured: -Takes a single string argument and converts it into a [:substitute] -[subcmd] / [substitute()] [subfun] pattern string that matches the given -string literally. + let g:easytags_languages = { + \ 'language': { + \ 'cmd': g:easytags_cmd, + \ 'args': [], + \ 'fileoutput_opt': '-f', + \ 'stdout_opt': '-f-', + \ 'recurse_flag': '-R' + \ } + \} -[subfun]: http://vimdoc.sourceforge.net/htmldoc/eval.html#substitute() -[subcmd]: http://vimdoc.sourceforge.net/htmldoc/change.html#:substitute +Each key is a special language definition. The key is in the notation of ctags in lowercase; you still need to use `xolox#easytags#map_filetypes()` to map this to Vim's filetypes, if necessary. -#### The `xolox#misc#escape#substitute()` function +Above snippets shows the defaults; you only need to specify options that differ. -Takes a single string argument and converts it into a [:substitute] -[subcmd] / [substitute()] [subfun] replacement string that inserts the -given string literally. +### The `g:easytags_file` option -#### The `xolox#misc#escape#shell()` function +As mentioned above the plug-in will store your tags in `~/.vimtags` on UNIX and `~/_vimtags` on Windows. To change the location of this file, set the global variable `g:easytags_file`, e.g.: -Takes a single string argument and converts it into a quoted command line -argument. + :let g:easytags_file = '~/.vim/tags' -I was going to add a long rant here about Vim's ['shellslash' option] -[shellslash], but really, it won't make any difference. Let's just suffice -to say that I have yet to encounter a single person out there who uses -this option for its intended purpose (running a UNIX style shell on -Microsoft Windows). +A leading `~` in the `g:easytags_file` variable is expanded to your current home directory (`$HOME` on UNIX, `%USERPROFILE%` on Windows). -[shellslash]: http://vimdoc.sourceforge.net/htmldoc/options.html#'shellslash' +### The `g:easytags_dynamic_files` option -### List handling functions +By default `:UpdateTags` only writes to the global tags file, but it can be configured to look for project specific tags files by adding the following lines to your [vimrc script] [vimrc]: -#### The `xolox#misc#list#unique()` function + :set tags=./tags; + :let g:easytags_dynamic_files = 1 -Remove duplicate values from the given list in-place (preserves order). +You can change the name of the tags file, the important thing is that it's relative to your working directory or the buffer (using a leading `./`). When `g:easytags_dynamic_files` is set to 1 the easytags plug-in will write to the first existing tags file seen by Vim (based on the ['tags' option] [tags_opt]). In other words: If a project specific tags file is found it will be used, otherwise the plug-in falls back to the global tags file (or a file type specific tags file). -#### The `xolox#misc#list#binsert()` function +If you set `g:easytags_dynamic_files` to 2 the easytags plug-in will automatically create project specific tags based on the first name in the 'tags' option. In this mode the the global tags file or file type specific tags files are only used for directories where you don't have write permissions. -Performs in-place binary insertion, which depending on your use case can -be more efficient than calling Vim's [sort()] [sort] function after each -insertion (in cases where a single, final sort is not an option). Expects -three arguments: +The ['tags' option] [tags_opt] is reevaluated each time the plug-in runs, so which tags file is selected can differ depending on the buffer and working directory. -1. A list -2. A value to insert -3. 1 (true) when case should be ignored, 0 (false) otherwise +### The `g:easytags_by_filetype` option -[sort]: http://vimdoc.sourceforge.net/htmldoc/eval.html#sort() +By default all tags are stored in a global tags file. When the tags file grows beyond a certain size Vim will be slowed down by the easytags plug-in because it has to read and process a large number of tags very frequently. -### Functions to interact with the user +To avoid this problem you can set `g:easytags_by_filetype` to the path of an existing directory. The easytags plug-in will create separate tags files for each file type in the configured directory. These tags files are automatically registered by the easytags plug-in when the file type of a buffer is set. -#### The `xolox#misc#msg#info()` function +Note that the `g:easytags_dynamic_files` option takes precedence over this option. -Show a formatted informational message to the user. This function has the -same argument handling as Vim's [printf()] [printf] function. +If you already have a global tags file you can create file type specific tags files from the global tags file using the command `:TagsByFileType`. -[printf]: http://vimdoc.sourceforge.net/htmldoc/eval.html#printf() +### The `g:easytags_always_enabled` option -#### The `xolox#misc#msg#warn()` function +By default the plug-in automatically generates and highlights tags when you stop typing for a few seconds (this works using the [CursorHold] [cursorhold] automatic command). This means that when you edit a file, the dynamic highlighting won't appear until you pause for a moment. If you don't like this you can configure the plug-in to always enable dynamic highlighting: -Show a formatted warning message to the user. This function has the same -argument handling as Vim's [printf()] [printf] function. + :let g:easytags_always_enabled = 1 -#### The `xolox#misc#msg#debug()` function +Be warned that after setting this option you'll probably notice why it's disabled by default: Every time you edit a file in Vim, the plug-in will first run Exuberant Ctags and then highlight the tags, and this slows Vim down quite a lot. I have some ideas on how to improve this latency by running Exuberant Ctags in the background so stay tuned! -Show a formatted debugging message to the user, if the user has enabled -increased verbosity by setting Vim's ['verbose'] [verbose] option to one -(1) or higher. This function has the same argument handling as Vim's -[printf()] [printf] function. +Note: If you change this option it won't apply until you restart Vim, so you'll have to set this option in your [vimrc script] [vimrc]. -[verbose]: http://vimdoc.sourceforge.net/htmldoc/options.html#'verbose' +### The `g:easytags_on_cursorhold` option -### Integration between Vim and its environment +As I explained above the plug-in by default doesn't update or highlight your tags until you stop typing for a moment. The plug-in tries hard to do the least amount of work possible in this break but it might still interrupt your workflow. If it does you can disable the periodic update: -#### The `xolox#misc#open#file()` function + :let g:easytags_on_cursorhold = 0 -Given a pathname as the first argument, this opens the file with the -program associated with the file type. So for example a text file might -open in Vim, an `*.html` file would probably open in your web browser and -a media file would open in a media player. +Note: Like the `g:easytags_always_enabled` option, if you change this option it won't apply until you restart Vim, so you'll have to set this option in your [vimrc script] [vimrc]. -This should work on Windows, Mac OS X and most Linux distributions. If -this fails to find a file association, you can pass one or more external -commands to try as additional arguments. For example: +### The `g:easytags_updatetime_min` option - :call xolox#misc#open#file('/path/to/my/file', 'firefox', 'google-chrome') +Vim's ['updatetime'] [updatetime] option controls how often the easytags plug-in is automatically executed. A lot of popular Vim plug-ins manipulate this option to control how often they are called. Unfortunately some of those plug-ins set ['updatetime'] [updatetime] to a very low value (less than a second) and this can break the easytags plug-in. -This generally shouldn't be necessary but it might come in handy now and -then. +Because of this the easytags plug-in compensates by keeping track of when it was last executed. You'll get one warning when the plug-in first notices a very low value of ['updatetime'] [updatetime], after that the plug-in will shut up (until you restart Vim) and simply compensate by not executing until its time has come. If you want to silence the warning message forever, see the `g:easytags_updatetime_warn` option. -#### The `xolox#misc#open#url()` function +The default value of Vim's ['updatetime] [updatetime] option *and* the `g:easytags_updatetime_min` option is 4000 milliseconds (4 seconds). -Given a URL as the first argument, this opens the URL in your preferred or -best available web browser: +If you know what you're doing and you really want the easytags plug-in to be executed more than once every 4 seconds you can lower the minimum acceptable updatetime by setting `g:easytags_updatetime_min` to the number of milliseconds (an integer). -- In GUI environments a graphical web browser will open (or a new tab will - be created in an existing window) -- In console Vim without a GUI environment, when you have any of `lynx`, - `links` or `w3m` installed it will launch a command line web browser in - front of Vim (temporarily suspending Vim) +Note that although `g:easytags_updatetime_min` counts in milliseconds, the easytags plug-in does not support subsecond granularity because it is limited by Vim's [localtime()] [localtime] function which has one-second resolution. -### Vim and plug-in option handling +### The `g:easytags_updatetime_warn` option -#### The `xolox#misc#option#get()` function +Since the easytags plug-in now compensates for low ['updatetime'] [updatetime] values (see the `g:easytags_updatetime_min` option above) the warning message shown by the easytags plug-in has become kind of redundant (and probably annoying?). For now it can be completely disabled by setting `g:easytags_updatetime_warn` to 0 (false). -Expects one or two arguments: 1. The name of a variable and 2. the default -value if the variable does not exist. +When the feature that compensates for low ['updatetime'] [updatetime] values has proven to be a reliable workaround I will probably remove the warning message and the `g:easytags_updatetime_warn` option. -Returns the value of the variable from a buffer local variable, global -variable or the default value, depending on which is defined. +### The `g:easytags_auto_update` option -This is used by some of my Vim plug-ins for option handling, so that users -can customize options for specific buffers. +By default the plug-in automatically updates and highlights your tags when you stop typing for a moment. If you want to disable automatic updating while keeping automatic highlighting enabled you can set this option to false: -#### The `xolox#misc#option#split()` function + :let g:easytags_auto_update = 0 -Given a multi-value Vim option like ['runtimepath'] [rtp] this returns a -list of strings. For example: +### The `g:easytags_auto_highlight` option - :echo xolox#misc#option#split(&runtimepath) - ['/home/peter/Projects/Vim/misc', - '/home/peter/Projects/Vim/colorscheme-switcher', - '/home/peter/Projects/Vim/easytags', - ...] +By default the plug-in automatically updates and highlights your tags when you stop typing for a moment. If you want to disable automatic highlighting while keeping automatic updating enabled you can set this option to false: -[rtp]: http://vimdoc.sourceforge.net/htmldoc/options.html#'runtimepath' + :let g:easytags_auto_highlight = 0 -#### The `xolox#misc#option#join()` function +### The `g:easytags_autorecurse` option -Given a list of strings like the ones returned by -`xolox#misc#option#split()`, this joins the strings together into a -single value that can be used to set a Vim option. +When the `:UpdateTags` command is executed automatically or without arguments, it defaults to updating just the tags for the current file. If you'd rather have it recursively scan everything below the directory of the current file then set this option to true (1): -#### The `xolox#misc#option#split_tags()` function + :let g:easytags_autorecurse = 1 -Customized version of `xolox#misc#option#split()` with specialized -handling for Vim's ['tags' option] [tags]. +You have to explicitly enable this option because it should only be used while navigating around small directory trees. Imagine always having this option enabled and then having to edit a file in e.g. the root of your home directory: The `easytags.vim` plug-in would freeze Vim for a long time while you'd have to wait for Exuberant Ctags to scan thousands of files... -[tags]: http://vimdoc.sourceforge.net/htmldoc/options.html#'tags' +Note that when you enable this option the `easytags.vim` plug-in might ignore other options like `g:easytags_resolve_links`. This is an implementation detail which I intend to fix. -#### The `xolox#misc#option#join_tags()` function +### The `g:easytags_include_members` option -Customized version of `xolox#misc#option#join()` with specialized -handling for Vim's ['tags' option] [tags]. +Exuberant Ctags knows how to generate tags for struct/class members in C++ and Java source code but doesn't do so by default because it can more than double the size of your tags files, thus taking much longer to read/write the tags file. When you enable the `g:easytags_include_members` option from your [vimrc script] [vimrc] (before the `easytags.vim` plug-in is loaded): -#### The `xolox#misc#option#eval_tags()` function + :let g:easytags_include_members = 1 -Evaluate Vim's ['tags' option] [tags] without looking at the file -system, i.e. this will report tags files that don't exist yet. Expects -the value of the ['tags' option] [tags] as the first argument. If the -optional second argument is 1 (true) only the first match is returned, -otherwise (so by default) a list with all matches is returned. +Exuberant Ctags will be instructed to include struct/class members using the `--extra=+q` command line argument and the `easytags.vim` plug-in will highlight them using the `cMember` highlighting group. Because most color schemes don't distinguish the [Identifier and Type] [syn_groups] highlighting groups all members will now probably look like type definitions. You can change that by executing either of the following Vim commands (from your vimrc script, a file type plug-in, etc.): -### Operating system interfaces + " If you like one of the existing styles you can link them: + highlight link cMember Special -#### The `xolox#misc#os#is_win()` function + " You can also define your own style if you want: + highlight cMember gui=italic -Returns 1 (true) when on Microsoft Windows, 0 (false) otherwise. +### The `g:easytags_resolve_links` option -#### The `xolox#misc#os#exec()` function +UNIX has [symbolic links] [slinks] and [hard links] [hlinks], both of which conflict with the concept of having one unique location for every identifier. With regards to hard links there's not much anyone can do, but because I use symbolic links quite a lot I've added this option. It's disabled by default since it has a small performance impact and might not do what unknowing users expect it to: When you enable this option the plug-in will resolve symbolic links in pathnames, which means your tags file will only contain entries with [canonical pathnames] [canon]. To enable this option (which I strongly suggest doing when you run UNIX and use symbolic links) execute the following Vim command: -Execute an external command (hiding the console on Microsoft Windows when -my [vim-shell plug-in] [vim-shell] is installed). + :let g:easytags_resolve_links = 1 -Expects a dictionary with the following key/value pairs as the first -argument: +### The `g:easytags_suppress_ctags_warning` option -- **command** (required): The command line to execute -- **async** (optional): set this to 1 (true) to execute the command in the - background (asynchronously) -- **stdin** (optional): a string or list of strings with the input for the - external command -- **check** (optional): set this to 0 (false) to disable checking of the - exit code of the external command (by default an exception will be - raised when the command fails) +If this is set and not false, it will suppress the warning on startup if ctags is not found or not recent enough. -Returns a dictionary with one or more of the following key/value pairs: + :let g:easytags_suppress_ctags_warning = 1 -- **command** (always available): the generated command line that was used - to run the external command -- **exit_code** (only in synchronous mode): the exit status of the - external command (an integer, zero on success) -- **stdout** (only in synchronous mode): the output of the command on the - standard output stream (a list of strings, one for each line) -- **stderr** (only in synchronous mode): the output of the command on the - standard error stream (as a list of strings, one for each line) +### The `g:easytags_ignored_syntax_groups` option -[vim-shell]: http://peterodding.com/code/vim/shell/ +This variable is a string of comma separated names of syntax groups in which dynamic highlighting is not applied. It defaults to `.*String.*,.*Comment.*,cIncluded`. -### Pathname manipulation functions +## Customizing the easytags plug-in -#### The `xolox#misc#path#which()` function +Advanced users may wish to customize how the easytags plug-in works beyond the point of changing configuration defaults. This section contains some hints about this. If you have suggestions, please feel free to submit them. -Scan the executable search path (`$PATH`) for one or more external -programs. Expects one or more string arguments with program names. Returns -a list with the absolute pathnames of all found programs. Here's an -example: +### Passing custom command line arguments to Exuberant Ctags - :echo xolox#misc#path#which('gvim', 'vim') - ['/usr/local/bin/gvim', - '/usr/bin/gvim', - '/usr/local/bin/vim', - '/usr/bin/vim'] +You may want to run Exuberant Ctags with specific command line options, for example the [code_complete] [code_complete] plug-in requires the signature field to be present. To do this you can create a configuration file for Exuberant Ctags, e.g. `~/.ctags` on UNIX or `%USERPROFILE%\ctags.cnf` on Windows. The file should contain one command line option per line. See the [Exuberant Ctags manual] [ctags_cfg] for details. -#### The `xolox#misc#path#split()` function +### Update & highlight tags immediately after save -Split a pathname (the first and only argument) into a list of pathname -components. +By default the easytags plug-in automatically updates & highlights tags for the current file after several seconds of inactivity. This is done to prevent the easytags plug-in from interrupting your workflow. -On Windows, pathnames starting with two slashes or backslashes are UNC -paths where the leading slashes are significant... In this case we split -like this: +If you want the easytags plug-in to automatically update & highlight tags for the current file right after you save the file, you can add the following line to your [vimrc script] [vimrc]: -- Input: `'//server/share/directory'` -- Result: `['//server', 'share', 'directory']` + :autocmd BufWritePost * call xolox#easytags#autoload('BufWritePost') -Everything except Windows is treated like UNIX until someone has a better -suggestion :-). In this case we split like this: +### How to customize the highlighting colors? -- Input: `'/foo/bar/baz'` -- Result: `['/', 'foo', 'bar', 'baz']` +The easytags plug-in defines new highlighting groups for dynamically highlighted tags. These groups are linked to Vim's default groups so that they're colored out of the box, but if you want you can change the styles. To do so use a `highlight` command such as the ones given a few paragraphs back. Of course you'll need to change the group name. Here are the group names used by the easytags plug-in: -To join a list of pathname components back into a single pathname string, -use the `xolox#misc#path#join()` function. + * **AWK**: `awkFunctionTag` + * **C#:** `csClassOrStructTag`, `csMethodTag` + * **C, C++, Objective C:** `cTypeTag`, `cEnumTag`, `cPreProcTag`, `cFunctionTag`, `cMemberTag` + * **Java:** `javaClassTag`, `javaMethodTag` + * **Lua:** `luaFuncTag` + * **PHP:** `phpFunctionsTag`, `phpClassesTag` + * **Python:** `pythonFunctionTag`, `pythonMethodTag`, `pythonClassTag` + * **Ruby:** `rubyModuleNameTag`, `rubyClassNameTag`, `rubyMethodNameTag` + * **Shell**: `shFunctionTag` + * **Tcl**: `tclCommandTag` + * **Vim:** `vimAutoGroupTag`, `vimCommandTag`, `vimFuncNameTag`, `vimScriptFuncNameTag` -#### The `xolox#misc#path#join()` function +As you can see each of these names ends in `Tag` to avoid conflicts with the syntax modes shipped with Vim. And about the singular/plural confusion: I've tried to match the existing highlighting groups defined by popular syntax modes (except of course for the `Tag` suffix). -Join a list of pathname components (the first and only argument) into a -single pathname string. This is the counterpart to the -`xolox#misc#path#split()` function and it expects a list of pathname -components as returned by `xolox#misc#path#split()`. +## Faster syntax highlighting using Python -#### The `xolox#misc#path#directory_separator()` function +The Vim script implementation of dynamic syntax highlighting is quite slow on large tags files. When the Python Interface to Vim is enabled the easytags plug-in will therefor automatically use a Python script that performs dynamic syntax highlighting about twice as fast as the Vim script implementation. The following options are available to change the default configuration. -Find the preferred directory separator for the platform and settings. +### The `g:easytags_python_enabled` option -#### The `xolox#misc#path#absolute()` function +To disable the Python implementation of dynamic syntax highlighting you can set this option to false (0). -Canonicalize and resolve a pathname, *regardless of whether it exists*. -This is intended to support string comparison to determine whether two -pathnames point to the same directory or file. +### The `g:easytags_python_script` option -#### The `xolox#misc#path#relative()` function +This option defines the pathname of the script that contains the Python implementation of dynamic syntax highlighting. -Make an absolute pathname (the first argument) relative to a directory -(the second argument). +## Troubleshooting -#### The `xolox#misc#path#merge()` function +### `:HighlightTags` only works for the tags file created by `:UpdateTags` -Join a directory pathname and filename into a single pathname. +If you want to create tags files and have their tags highlighted by the `easytags.vim` plug-in then you'll have to create the tags file with certain arguments to Exuberant Ctags: -#### The `xolox#misc#path#commonprefix()` function + $ ctags --fields=+l --c-kinds=+p --c++-kinds=+p ... -Find the common prefix of path components in a list of pathnames. +The `--fields=+l` argument makes sure that Exuberant Ctags includes a `language:...` property with each entry in the tags file. This is required by the `:HighlightTags` command so it can filter tags by their file type. The other two arguments make sure Exuberant Ctags generates tags for function prototypes in C/C++ source code. -#### The `xolox#misc#path#encode()` function +If you have the `g:easytags_include_members` option enabled (its off by default) then you'll also need to add the `--extra=+q` argument so that Exuberant Ctags generates tags for structure/class members. -Encode a pathname so it can be used as a filename. This uses URL encoding -to encode special characters. +### The plug-in complains that Exuberant Ctags isn't installed -#### The `xolox#misc#path#decode()` function +After a Mac OS X user found out the hard way that the `ctags` executable isn't always Exuberant Ctags and we spend a few hours debugging the problem I added proper version detection: The plug-in executes `ctags --version` when Vim is started to verify that Exuberant Ctags 5.5 or newer is installed. If it isn't Vim will show the following message on startup: -Decode a pathname previously encoded with `xolox#misc#path#encode()`. + easytags.vim: Plug-in not loaded because Exuberant Ctags isn't installed! + Please download & install Exuberant Ctags from http://ctags.sf.net -#### The `xolox#misc#path#is_relative()` function +If the installed Exuberant Ctags version is too old the plug-in will complain: -Returns true (1) when the pathname given as the first argument is -relative, false (0) otherwise. + easytags.vim: Plug-in not loaded because Exuberant Ctags 5.5 + or newer is required while you have version %s installed! -#### The `xolox#misc#path#tempdir()` function +If you have the right version of Exuberant Ctags installed but the plug-in still complains, try executing the following command from inside Vim: -Create a temporary directory and return the pathname of the directory. + :!which ctags -### String handling +If this doesn't print the location where you installed Exuberant Ctags it means your system already had a `ctags` executable but it isn't compatible with Exuberant Ctags 5.5 and you'll need to set the `g:easytags_cmd` option (see above) so the plug-in knows which `ctags` to run. -#### The `xolox#misc#str#compact()` function +### Vim locks up while the plug-in is running -Compact whitespace in the string given as the first argument. +Once or twice now in several years I've experienced Exuberant Ctags getting into an infinite loop when given garbage input. In my case this happened by accident a few days ago :-|. Because my plug-in executes `ctags` in the foreground this will block Vim indefinitely! If this happens you might be able to kill `ctags` by pressing [Control-C] [ctrl_c] but if that doesn't work you can also kill it without stopping Vim using a task manager or the `pkill` command (available on most UNIX systems): -#### The `xolox#misc#str#trim()` function + $ pkill -KILL ctags -Trim all whitespace from the start and end of the string given as the -first argument. +If Vim seems very slow and you suspect this plug-in might be the one to blame, increase Vim's verbosity level: -### Timing of long during operations + :set vbs=1 -#### The `xolox#misc#timer#start()` function +Every time the plug-in executes it will time how long the execution takes and add the results to Vim's message history, which you can view by executing the [:messages] [messages] command. -Start a timer. This returns a list which can later be passed to -`xolox#misc#timer#stop()`. +### Failed to highlight tags because pattern is too big! -#### The `xolox#misc#timer#stop()` function +If the `easytags.vim` plug-in fails to highlight your tags and the error message mentions that the pattern is too big, your tags file has grown too large for Vim to be able to highlight all tagged identifiers! I've had this happen to me with 50 KB patterns because I added most of the headers in `/usr/include/` to my tags file. Internally Vim raises the error [E339: Pattern too long] [e339] and unfortunately the only way to avoid this problem once it occurs is to reduce the number of tagged identifiers... -Show a formatted debugging message to the user, if the user has enabled -increased verbosity by setting Vim's ['verbose'] [verbose] option to one -(1) or higher. +In my case the solution was to move most of the tags from `/usr/include/` over to project specific tags files which are automatically loaded by Vim when I edit files in different projects because I've set the ['tags' option] [tags_opt] as follows: -This function has the same argument handling as Vim's [printf()] [printf] -function with one difference: At the point where you want the elapsed time -to be embedded, you write `%s` and you pass the list returned by -`xolox#misc#timer#start()` as an argument. + :set tags=./.tags;,~/.vimtags -[verbose]: http://vimdoc.sourceforge.net/htmldoc/options.html#'verbose' -[printf]: http://vimdoc.sourceforge.net/htmldoc/eval.html#printf() +Once you've executed the above command, Vim will automatically look for a file named `.tags` in the directory of the current file. Because of the `;` Vim also recurses upwards so that you can nest files arbitrarily deep under your project directories. -#### The `xolox#misc#timer#format_timespan()` function +### The plug-in doesn't seem to work in Cygwin -Format a time stamp (a string containing a formatted floating point -number) into a human friendly format, for example 70 seconds is phrased as -"1 minute and 10 seconds". - -## Management of changes to the miscellaneous scripts - -### How does it work? - -Here's how I merge the miscellaneous scripts into a Vim plug-in repository: - -1. Let git know about the `vim-misc` repository by adding the remote GitHub - repository: - - git remote add -f vim-misc https://github.com/xolox/vim-misc.git - -2. Merge the two directory trees without clobbering the `README.md` and/or - `.gitignore` files, thanks to the selected merge strategy and options: - - git checkout master - git merge --no-commit -s recursive -X ours vim-misc/master - git commit -m "Merge vim-misc repository as overlay" - -3. While steps 1 and 2 need to be done only once for a given repository, the - following commands are needed every time I want to pull and merge the latest - changes: - - git checkout master - git fetch vim-misc master - git merge --no-commit -s recursive -X ours vim-misc/master - git commit -m "Merged changes to miscellaneous scripts" - -### Why make things so complex? - -I came up with this solution after multiple years of back and forth between Vim -Online users, the GitHub crowd and my own sanity: - -1. When I started publishing my first Vim plug-ins (in June 2010) I would - prepare ZIP archives for Vim Online using makefiles. The makefiles would - make sure the miscellaneous scripts were included in the uploaded - distributions. This had two disadvantages: It lost git history and the - repositories on GitHub were not usable out of the box, so [I got complaints - from GitHub (Pathogen) users] [github-complaints]. - -2. My second attempt to solve the problem used git submodules which seemed like - the ideal solution until I actually started using them in March 2011: - Submodules are not initialized during a normal `git clone`, you need to use - `git clone --recursive` instead but Vim plug-in managers like [Pathogen] - [pathogen] and [Vundle] [vundle] don't do this (at least [they didn't when I - tried] [vundle-discussion]) so people would end up with broken checkouts. - -3. After finding out that git submodules were not going to solve my problems I - searched for other inclusion strategies supported by git. After a while I - came upon the [subtree merge strategy] [merge-strategy] which I started - using in May 2011 and stuck with for more than two years (because it - generally worked fine and seemed quite robust). - -4. In April 2013 the flat layout of the repository started bothering me because - it broke my personal workflow, so I changed it to the proper directory - layout of a Vim plug-in. Why did it break my workflow? Because I couldn't - get my [vim-reload] [reload] plug-in to properly reload miscellaneous - scripts without nasty hacks. Note to self: [Dropbox does not respect - symbolic links] [dropbox-vote-350] and Vim doesn't like them either ([E746] - [E746]). - -### Compatibility issues - -Regardless of the inclusion strategies discussed above, my current scheme has a -flaw: If more than one of my plug-ins are installed in a Vim profile using -[Pathogen] [pathogen] or [Vundle] [vundle], the miscellaneous autoload scripts -will all be loaded from the subdirectory of one single plug-in. - -This means that when I break compatibility in the miscellaneous scripts, I have -to make sure to merge the changes into all of my plug-ins. Even then, if a user -has more than one of my plug-ins installed but updates only one of them, the -other plug-ins (that are not yet up to date) can break (because of the -backwards incompatible change). - -The `xolox#misc#compat#check()` function makes sure that incompatibilities are -detected early so that the user knows which plug-in to update if -incompatibilities arise. +If you want to use the plug-in with Vim under [Cygwin] [cygwin], you need to have the Cygwin version of Ctags installed instead of the Windows version (thanks to Alex Zuroff for reporting this!). ## Contact -If you have questions, bug reports, suggestions, etc. the author can be -contacted at <peter@peterodding.com>. The latest version is available at -<http://peterodding.com/code/vim/misc> and <http://github.com/xolox/vim-misc>. +If you have questions, bug reports, suggestions, etc. the author can be contacted at <peter@peterodding.com>. The latest version is available at <http://peterodding.com/code/vim/easytags/> and <http://github.com/xolox/vim-easytags>. If you like this plug-in please vote for it on [Vim Online] [vim_online]. ## License -This software is licensed under the [MIT license] [mit]. +This software is licensed under the [MIT license](http://en.wikipedia.org/wiki/MIT_License). © 2013 Peter Odding <<peter@peterodding.com>>. -[dropbox-vote-350]: https://www.dropbox.com/votebox/350/preserve-implement-symlink-behaviour -[E746]: http://vimdoc.sourceforge.net/htmldoc/eval.html#E746 -[github-complaints]: https://github.com/xolox/vim-easytags/issues/1 -[merge-strategy]: http://www.kernel.org/pub/software/scm/git/docs/howto/using-merge-subtree.html -[mit]: http://en.wikipedia.org/wiki/MIT_License -[pathogen]: http://www.vim.org/scripts/script.php?script_id=2332 -[plugins]: http://peterodding.com/code/vim/ -[reload]: http://peterodding.com/code/vim/reload -[repository]: https://github.com/xolox/vim-misc -[vundle-discussion]: https://github.com/gmarik/vundle/pull/41 -[vundle]: https://github.com/gmarik/vundle +[canon]: http://en.wikipedia.org/wiki/Canonicalization +[code_complete]: http://www.vim.org/scripts/script.php?script_id=1764 +[ctags]: http://en.wikipedia.org/wiki/Ctags +[ctags_cfg]: http://ctags.sourceforge.net/ctags.html#FILES +[ctags_fts]: http://ctags.sourceforge.net/languages.html +[ctrl_c]: http://vimdoc.sourceforge.net/htmldoc/pattern.html#CTRL-C +[ctrl_mapping]: http://vimdoc.sourceforge.net/htmldoc/tagsrch.html#CTRL-] +[cursorhold]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#CursorHold +[cygwin]: http://en.wikipedia.org/wiki/Cygwin +[dll]: http://en.wikipedia.org/wiki/Dynamic-link_library +[download]: http://peterodding.com/code/vim/downloads/easytags.zip +[e339]: http://vimdoc.sourceforge.net/htmldoc/message.html#E339 +[exctags]: http://ctags.sourceforge.net/ +[hlinks]: http://en.wikipedia.org/wiki/Hard_link +[ide]: http://en.wikipedia.org/wiki/Integrated_development_environment +[jsctags]: https://npmjs.org/package/jsctags +[localtime]: http://vimdoc.sourceforge.net/htmldoc/eval.html#localtime() +[messages]: http://vimdoc.sourceforge.net/htmldoc/message.html#:messages +[neocomplcache]: http://www.vim.org/scripts/script.php?script_id=2620 +[shell]: http://peterodding.com/code/vim/shell/ +[slinks]: http://en.wikipedia.org/wiki/Symbolic_link +[syn_groups]: http://vimdoc.sourceforge.net/htmldoc/syntax.html#group-name +[system]: http://vimdoc.sourceforge.net/htmldoc/eval.html#system%28%29 +[tagfiles_fun]: http://vimdoc.sourceforge.net/htmldoc/eval.html#tagfiles%28%29 +[tags_opt]: http://vimdoc.sourceforge.net/htmldoc/options.html#%27tags%27 +[unlet]: http://vimdoc.sourceforge.net/htmldoc/eval.html#:unlet +[updatetime]: http://vimdoc.sourceforge.net/htmldoc/options.html#'updatetime' +[vim]: http://www.vim.org/ +[vim_fts]: http://ftp.vim.org/vim/runtime/syntax/ +[vim_online]: http://www.vim.org/scripts/script.php?script_id=3114 +[vimrc]: http://vimdoc.sourceforge.net/htmldoc/starting.html#vimrc @@ -0,0 +1,34 @@ +# To-do list for the easytags plug-in for Vim + +## New functionality + + * Automatically index C headers when `/usr/include/$name.h` exists? + + * Integration with my unreleased project plug-in so that when you edit any file in a project, all related files are automatically scanned for tags? + + * Make `g:easytags_autorecurse` accept the following values: 0 (only scan the current file), 1 (always scan all files in the same directory) and 2 (always recurse down the current directory)? + + * Several users have reported the plug-in locking Vim up and this was invariably caused by the plug-in trying to highlight the tags from a very large tags file. Maybe the plug-in should warn about this so the cause is immediately clear to users. It's also possible to temporarily change the `tags` option so that `taglist()` doesn't look at tags files that are bigger than a certain size but this feels like a hack and it may be better to go with the option below. + + * The functionality of the Python highlight script can just as well be implemented in Vim script (using `readfile()` instead of `taglist()`), the only notable difference being that Vim cannot read files line wise. This would remove the duplication of code between Vim script and Python and would mean all users get to enjoy a faster plug-in! I'm not sure whether a Vim script implementation of the same code would be equally fast though, so I should implement and benchmark! This would also easily enable the plug-in to ignore tags files that are too large (see above). + +## Possible bugs + + * Right now easytags is a messy combination of Vim script code and Python scripts. I plan to port the Python code back to Vim script. + + * On Microsoft Windows (tested on XP) GVim loses focus while `ctags` is running because Vim opens a command prompt window. Also the CursorHold event seems to fire repeatedly, contradicting my understanding of the automatic command and its behavior on UNIX?! This behavior doesn't occur when I use the integration with my `shell.vim` plug-in. + + * I might have found a bug in Vim: The tag `easytags#highlight_cmd` was correctly being highlighted by my plug-in (and was indeed included in my tags file) even though I couldn't jump to it using `Ctrl-]`, which caused: + + E426: tag not found: easytags#highlight_cmd + + But immediately after that error if I do: + + :echo taglist('easytags#highlight_cmd') + [{'cmd': '/^function! easytags#highlight_cmd() " {{{1$/', 'static': 0, + \ 'name': 'easytags#highlight_cmd', 'language': 'Vim', 'kind': 'f', + \ 'filename': '/home/peter/Development/Vim/vim-easytags/autoload.vim'}] + + It just works?! Some relevant context: I was editing `~/.vim/plugin/easytags.vim` at the time (a symbolic link to `~/Development/Vim/vim-easytags/easytags.vim`) and wanted to jump to the definition of the function `easytags#highlight_cmd` in `~/.vim/autoload/easytags.vim` (a symbolic link to `~/Development/Vim/vim-easytags/autoload.vim`). I was already editing `~/.vim/autoload/easytags.vim` in another Vim buffer. + +vim: ai nofen diff --git a/autoload/xolox/easytags.vim b/autoload/xolox/easytags.vim new file mode 100644 index 0000000..e877656 --- /dev/null +++ b/autoload/xolox/easytags.vim @@ -0,0 +1,1028 @@ +" Vim script +" Author: Peter Odding <peter@peterodding.com> +" Last Change: May 20, 2013 +" URL: http://peterodding.com/code/vim/easytags/ + +let g:xolox#easytags#version = '3.3.3' + +call xolox#misc#compat#check('easytags.vim', g:xolox#easytags#version, 7) + +" Public interface through (automatic) commands. {{{1 + +function! xolox#easytags#register(global) " {{{2 + " Parse the &tags option and get a list of all tags files *including + " non-existing files* (this is why we can't just call tagfiles()). + let tagfiles = xolox#misc#option#split_tags(&tags) + let expanded = map(copy(tagfiles), 'resolve(expand(v:val))') + " Add the filename to the &tags option when the user hasn't done so already. + let tagsfile = a:global ? g:easytags_file : xolox#easytags#get_tagsfile() + if index(expanded, xolox#misc#path#absolute(tagsfile)) == -1 + " This is a real mess because of bugs in Vim?! :let &tags = '...' doesn't + " work on UNIX and Windows, :set tags=... doesn't work on Windows. What I + " mean with "doesn't work" is that tagfiles() == [] after the :let/:set + " command even though the tags file exists! One easy way to confirm that + " this is a bug in Vim is to type :set tags= then press <Tab> followed by + " <CR>. Now you entered the exact same value that the code below also did + " but suddenly Vim sees the tags file and tagfiles() != [] :-S + call add(tagfiles, tagsfile) + let value = xolox#misc#option#join_tags(tagfiles) + let cmd = (a:global ? 'set' : 'setl') . ' tags=' . escape(value, '\ ') + if xolox#misc#os#is_win() && v:version < 703 + " TODO How to clear the expression from Vim's status line? + call feedkeys(":" . cmd . "|let &ro=&ro\<CR>", 'n') + else + execute cmd + endif + endif +endfunction + +" The localtime() when the CursorHold event last fired. +let s:last_automatic_run = 0 + +function! xolox#easytags#autoload(event) " {{{2 + try + let do_update = xolox#misc#option#get('easytags_auto_update', 1) + let do_highlight = xolox#misc#option#get('easytags_auto_highlight', 1) && &eventignore !~? '\<syntax\>' + " Don't execute this function for unsupported file types (doesn't load + " the list of file types if updates and highlighting are both disabled). + if (do_update || do_highlight) && !empty(xolox#easytags#select_supported_filetypes(&ft)) + if a:event =~? 'cursorhold' + " Only for the CursorHold automatic command: check for unreasonable + " &updatetime values. The minimum value 4000 is kind of arbitrary + " (apart from being Vim's default) so I made it configurable. + let updatetime_min = xolox#misc#option#get('easytags_updatetime_min', 4000) + if &updatetime < updatetime_min + if s:last_automatic_run == 0 + " Warn once about the low &updatetime value? + if xolox#misc#option#get('easytags_updatetime_warn', 1) + call xolox#misc#msg#warn("easytags.vim %s: The 'updatetime' option has an unreasonably low value, so I'll start compensating (see the easytags_updatetime_min option).", g:xolox#easytags#version) + endif + let s:last_automatic_run = localtime() + else + let next_scheduled_run = s:last_automatic_run + max([1, updatetime_min / 1000]) + if localtime() < next_scheduled_run + " It's not our time yet; wait for the next event. + call xolox#misc#msg#debug("easytags.vim %s: Skipping this beat of 'updatetime' to compensate for low value.", g:xolox#easytags#version) + " Shortcut to break out of xolox#easytags#autoload(). + return + else + call xolox#misc#msg#debug("easytags.vim %s: This is our beat of 'updatetime'!", g:xolox#easytags#version) + let s:last_automatic_run = localtime() + endif + endif + endif + endif + " Update entries for current file in tags file? + if do_update + let pathname = s:resolve(expand('%:p')) + if pathname != '' + let tags_outdated = getftime(pathname) > getftime(xolox#easytags#get_tagsfile()) + if tags_outdated || !xolox#easytags#file_has_tags(pathname) + call xolox#easytags#update(1, 0, []) + endif + endif + endif + " Apply highlighting of tags to current buffer? + if do_highlight + if !exists('b:easytags_last_highlighted') + call xolox#easytags#highlight() + else + for tagfile in tagfiles() + if getftime(tagfile) > b:easytags_last_highlighted + call xolox#easytags#highlight() + break + endif + endfor + endif + let b:easytags_last_highlighted = localtime() + endif + endif + catch + call xolox#misc#msg#warn("easytags.vim %s: %s (at %s)", g:xolox#easytags#version, v:exception, v:throwpoint) + endtry +endfunction + +function! xolox#easytags#update(silent, filter_tags, filenames) " {{{2 + try + let context = s:create_context() + let have_args = !empty(a:filenames) + let starttime = xolox#misc#timer#start() + let cfile = s:check_cfile(a:silent, a:filter_tags, have_args) + let tagsfile = xolox#easytags#get_tagsfile() + let firstrun = !filereadable(tagsfile) + let cmdline = s:prep_cmdline(cfile, tagsfile, firstrun, a:filenames, context) + let [output, has_updates] = s:run_ctags(starttime, cfile, tagsfile, firstrun, cmdline) + if !firstrun + if !has_updates + return 1 + endif + if have_args && !empty(g:easytags_by_filetype) + " TODO Get the headers from somewhere?! + call s:save_by_filetype(a:filter_tags, [], output, context) + else + let num_filtered = s:filter_merge_tags(a:filter_tags, tagsfile, output, context) + endif + if cfile != '' + let msg = "easytags.vim %s: Updated tags for %s in %s." + call xolox#misc#timer#stop(msg, g:xolox#easytags#version, expand('%:p:~'), starttime) + elseif have_args + let msg = "easytags.vim %s: Updated tags in %s." + call xolox#misc#timer#stop(msg, g:xolox#easytags#version, starttime) + else + let msg = "easytags.vim %s: Filtered %i invalid tags in %s." + call xolox#misc#timer#stop(msg, g:xolox#easytags#version, num_filtered, starttime) + endif + endif + " When :UpdateTags was executed manually we'll refresh the dynamic + " syntax highlighting so that new tags are immediately visible. + if !a:silent && xolox#misc#option#get('easytags_auto_highlight', 1) + HighlightTags + endif + return 1 + catch + call xolox#misc#msg#warn("easytags.vim %s: %s (at %s)", g:xolox#easytags#version, v:exception, v:throwpoint) + endtry +endfunction + +function! s:check_cfile(silent, filter_tags, have_args) " {{{3 + if a:have_args + return '' + endif + let silent = a:silent || a:filter_tags + if xolox#misc#option#get('easytags_autorecurse', 0) + let cdir = s:resolve(expand('%:p:h')) + if !isdirectory(cdir) + if silent | return '' | endif + throw "The directory of the current file doesn't exist yet!" + endif + return cdir + endif + let cfile = s:resolve(expand('%:p')) + if cfile == '' || !filereadable(cfile) + if silent | return '' | endif + throw "You'll need to save your file before using :UpdateTags!" + elseif g:easytags_ignored_filetypes != '' && &ft =~ g:easytags_ignored_filetypes + if silent | return '' | endif + throw "The " . string(&ft) . " file type is explicitly ignored." + elseif empty(xolox#easytags#select_supported_filetypes(&ft)) + if silent | return '' | endif + throw "Exuberant Ctags doesn't support the " . string(&ft) . " file type!" + endif + return cfile +endfunction + +function! s:prep_cmdline(cfile, tagsfile, firstrun, arguments, context) " {{{3 + let languages = xolox#misc#option#get('easytags_languages', {}) + let applicable_filetypes = xolox#easytags#select_supported_filetypes(&ft) + let ctags_language_name = xolox#easytags#to_ctags_ft(applicable_filetypes[0]) + let language = get(languages, ctags_language_name, {}) + if empty(language) + let program = xolox#misc#option#get('easytags_cmd') + let cmdline = [program, '--fields=+l', '--c-kinds=+p', '--c++-kinds=+p'] + if a:firstrun + call add(cmdline, xolox#misc#escape#shell('-f' . a:tagsfile)) + call add(cmdline, '--sort=' . (&ic ? 'foldcase' : 'yes')) + else + call add(cmdline, '--sort=no') + call add(cmdline, '-f-') + endif + if xolox#misc#option#get('easytags_include_members', 0) + call add(cmdline, '--extra=+q') + endif + else + let program = get(language, 'cmd', xolox#misc#option#get('easytags_cmd')) + if empty(program) + call xolox#misc#msg#warn("easytags.vim %s: No 'cmd' defined for language '%s', and also no global default!", g:xolox#easytags#version, ctags_language_name) + return + endif + let cmdline = [program] + get(language, 'args', []) + if a:firstrun + call add(cmdline, xolox#misc#escape#shell(get(language, 'fileoutput_opt', '-f') . a:tagsfile)) + else + call add(cmdline, xolox#misc#escape#shell(get(language, 'stdout_opt', '-f-'))) + endif + endif + let have_args = 0 + if a:cfile != '' + if xolox#misc#option#get('easytags_autorecurse', 0) + call add(cmdline, empty(language) ? '-R' : xolox#misc#escape#shell(get(language, 'recurse_flag', '-R'))) + call add(cmdline, xolox#misc#escape#shell(a:cfile)) + else + if empty(language) + " TODO Should --language-force distinguish between C and C++? + " TODO --language-force doesn't make sense for JavaScript tags in HTML files? + let filetype = xolox#easytags#to_ctags_ft(applicable_filetypes[0]) + call add(cmdline, xolox#misc#escape#shell('--language-force=' . filetype)) + endif + call add(cmdline, xolox#misc#escape#shell(a:cfile)) + endif + let have_args = 1 + else + for arg in a:arguments + if arg =~ '^-' + call add(cmdline, arg) + let have_args = 1 + else + let matches = split(expand(arg), "\n") + if !empty(matches) + call map(matches, 'xolox#misc#escape#shell(s:canonicalize(v:val, a:context))') + call extend(cmdline, matches) + let have_args = 1 + endif + endif + endfor + endif + " No need to run Exuberant Ctags without any filename arguments! + return have_args ? join(cmdline) : '' +endfunction + +function! s:run_ctags(starttime, cfile, tagsfile, firstrun, cmdline) " {{{3 + let lines = [] + let has_updates = 1 + if a:cmdline != '' + call xolox#misc#msg#debug("easytags.vim %s: Executing %s.", g:xolox#easytags#version, a:cmdline) + let lines = xolox#misc#os#exec({'command': a:cmdline})['stdout'] + let has_updates = a:firstrun || s:has_updates(a:cfile, join(lines, "\n")) + if a:firstrun + if a:cfile != '' + call xolox#misc#timer#stop("easytags.vim %s: Created tags for %s in %s.", g:xolox#easytags#version, expand('%:p:~'), a:starttime) + else + call xolox#misc#timer#stop("easytags.vim %s: Created tags in %s.", g:xolox#easytags#version, a:starttime) + endif + return [[], 0] + endif + endif + return [xolox#easytags#parse_entries(lines), has_updates] +endfunction + +" Vim 7.3 now has the sha256() function. We use it below to recognize when the +" tags haven't changed from the last time we ran Exuberant Ctags on a file; in +" this case the tags file doesn't have to be written to disk which makes the +" plug-in much faster for a very common case. + +let s:fingerprints = {} + +function! s:has_updates(cfile, output) + if empty(a:cfile) + " The cache doesn't work when tags aren't created for the current file. + return 1 + endif + let fingerprint = s:get_fingerprint(a:cfile, a:output) + call xolox#misc#msg#debug("easytags.vim %s: Fingerprint of tags in %s is %s.", g:xolox#easytags#version, a:cfile, string(fingerprint)) + if !empty(fingerprint) && get(s:fingerprints, a:cfile, '') ==# fingerprint + call xolox#misc#msg#debug("easytags.vim %s: The fingerprint didn't change! We can take a shortcut :-)", g:xolox#easytags#version) + return 0 + endif + let s:fingerprints[a:cfile] = fingerprint + return 1 +endfunction + +if exists('*sha256') + function! s:get_fingerprint(cfile, output) + return sha256(a:output) + endfunction +else + function! s:get_fingerprint(cfile, output) + " Don't want to re-implement a costly hashing function in Vimscript. Just + " handle files that never had any tags. + if empty(a:output) + return get(s:fingerprints, a:cfile, 1) + else + return '' + endif + endfunction +endif + +function! s:filter_merge_tags(filter_tags, tagsfile, output, context) " {{{3 + let [headers, entries] = xolox#easytags#read_tagsfile(a:tagsfile) + let filters = [] + " Filter old tags that are to be replaced with the tags in {output}. + let tagged_files = s:find_tagged_files(a:output, a:context) + if !empty(tagged_files) + call add(filters, '!has_key(tagged_files, s:canonicalize(v:val[1], a:context))') + endif + " Filter tags for non-existing files? + if a:filter_tags + call add(filters, 'filereadable(v:val[1])') + endif + let num_old_entries = len(entries) + if !empty(filters) + " Apply the filters. + call filter(entries, join(filters, ' && ')) + endif + let num_filtered = num_old_entries - len(entries) + " Merge the old and new tags. + call extend(entries, a:output) + " Since we've already read the tags file we might as well cache the tagged + " files. We do so before saving the tags file so that the items in {entries} + " are not yet flattened by xolox#easytags#write_tagsfile(). + let fname = s:canonicalize(a:tagsfile, a:context) + call s:cache_tagged_files_in(fname, getftime(fname), entries, a:context) + " Now we're ready to save the tags file. + if !xolox#easytags#write_tagsfile(a:tagsfile, headers, entries) + let msg = "Failed to write filtered tags file %s!" + throw printf(msg, fnamemodify(a:tagsfile, ':~')) + endif + return num_filtered +endfunction + +function! s:find_tagged_files(entries, context) " {{{3 + let tagged_files = {} + for entry in a:entries + let filename = s:canonicalize(entry[1], a:context) + if filename != '' + if !has_key(tagged_files, filename) + let tagged_files[filename] = 1 + endif + endif + endfor + return tagged_files +endfunction + +function! xolox#easytags#highlight() " {{{2 + " TODO This is a mess; Re-implement Python version in Vim script, benchmark, remove Python version. + try + " Treat C++ and Objective-C as plain C. + let filetype = get(s:canonical_aliases, &ft, &ft) + let tagkinds = get(s:tagkinds, filetype, []) + if exists('g:syntax_on') && !empty(tagkinds) && !exists('b:easytags_nohl') + let starttime = xolox#misc#timer#start() + let used_python = 0 + for tagkind in tagkinds + let hlgroup_tagged = tagkind.hlgroup . 'Tag' + " Define style on first run, clear highlighting on later runs. + if !hlexists(hlgroup_tagged) + execute 'highlight def link' hlgroup_tagged tagkind.hlgroup + else + execute 'syntax clear' hlgroup_tagged + endif + " Try to perform the highlighting using the fast Python script. + " TODO The tags files are read multiple times by the Python script + " within one run of xolox#easytags#highlight() + if s:highlight_with_python(hlgroup_tagged, tagkind) + let used_python = 1 + else + " Fall back to the slow and naive Vim script implementation. + if !exists('taglist') + " Get the list of tags when we need it and remember the results. + if !has_key(s:aliases, filetype) + let ctags_filetype = xolox#easytags#to_ctags_ft(filetype) + let taglist = filter(taglist('.'), "get(v:val, 'language', '') ==? ctags_filetype") + else + let aliases = s:aliases[&ft] + let taglist = filter(taglist('.'), "has_key(aliases, tolower(get(v:val, 'language', '')))") + endif + endif + " Filter a copy of the list of tags to the relevant kinds. + if has_key(tagkind, 'tagkinds') + let filter = 'v:val.kind =~ tagkind.tagkinds' + else + let filter = tagkind.vim_filter + endif + let matches = filter(copy(taglist), filter) + if matches != [] + " Convert matched tags to :syntax command and execute it. + let matches = xolox#misc#list#unique(map(matches, 'xolox#misc#escape#pattern(get(v:val, "name"))')) + let pattern = tagkind.pattern_prefix . '\%(' . join(matches, '\|') . '\)' . tagkind.pattern_suffix + let template = 'syntax match %s /%s/ containedin=ALLBUT,%s' + let command = printf(template, hlgroup_tagged, escape(pattern, '/'), xolox#misc#option#get('easytags_ignored_syntax_groups')) + call xolox#misc#msg#debug("easytags.vim %s: Executing command '%s'.", g:xolox#easytags#version, command) + try + execute command + catch /^Vim\%((\a\+)\)\=:E339/ + let msg = "easytags.vim %s: Failed to highlight %i %s tags because pattern is too big! (%i KB)" + call xolox#misc#msg#warn(msg, g:xolox#easytags#version, len(matches), tagkind.hlgroup, len(pattern) / 1024) + endtry + endif + endif + endfor + redraw + let bufname = expand('%:p:~') + if bufname == '' + let bufname = 'unnamed buffer #' . bufnr('%') + endif + let msg = "easytags.vim %s: Highlighted tags in %s in %s%s." + call xolox#misc#timer#stop(msg, g:xolox#easytags#version, bufname, starttime, used_python ? " (using Python)" : "") + return 1 + endif + catch + call xolox#misc#msg#warn("easytags.vim %s: %s (at %s)", g:xolox#easytags#version, v:exception, v:throwpoint) + endtry +endfunction + +function! xolox#easytags#by_filetype(undo) " {{{2 + try + if empty(g:easytags_by_filetype) + throw "Please set g:easytags_by_filetype before running :TagsByFileType!" + endif + let context = s:create_context() + let global_tagsfile = expand(g:easytags_file) + let disabled_tagsfile = global_tagsfile . '.disabled' + if !a:undo + let [headers, entries] = xolox#easytags#read_tagsfile(global_tagsfile) + call s:save_by_filetype(0, headers, entries, context) + call rename(global_tagsfile, disabled_tagsfile) + let msg = "easytags.vim %s: Finished copying tags from %s to %s! Note that your old tags file has been renamed to %s instead of deleting it, should you want to restore it." + call xolox#misc#msg#info(msg, g:xolox#easytags#version, g:easytags_file, g:easytags_by_filetype, disabled_tagsfile) + else + let headers = [] + let all_entries = [] + for tagsfile in split(glob(g:easytags_by_filetype . '/*'), '\n') + let [headers, entries] = xolox#easytags#read_tagsfile(tagsfile) + call extend(all_entries, entries) + endfor + call xolox#easytags#write_tagsfile(global_tagsfile, headers, all_entries) + call xolox#misc#msg#info("easytags.vim %s: Finished copying tags from %s to %s!", g:xolox#easytags#version, g:easytags_by_filetype, g:easytags_file) + endif + catch + call xolox#misc#msg#warn("easytags.vim %s: %s (at %s)", g:xolox#easytags#version, v:exception, v:throwpoint) + endtry +endfunction + +function! s:save_by_filetype(filter_tags, headers, entries, context) + let filetypes = {} + let num_invalid = 0 + for entry in a:entries + let ctags_ft = matchstr(entry[4], '^language:\zs\S\+$') + if empty(ctags_ft) + " TODO This triggers on entries where the pattern contains tabs. The interesting thing is that Vim reads these entries fine... Fix it in xolox#easytags#read_tagsfile()? + let num_invalid += 1 + if &vbs >= 1 + call xolox#misc#msg#debug("easytags.vim %s: Skipping tag without 'language:' field: %s", + \ g:xolox#easytags#version, string(entry)) + endif + else + let vim_ft = xolox#easytags#to_vim_ft(ctags_ft) + if !has_key(filetypes, vim_ft) + let filetypes[vim_ft] = [] + endif + call add(filetypes[vim_ft], entry) + endif + endfor + if num_invalid > 0 + call xolox#misc#msg#warn("easytags.vim %s: Skipped %i lines without 'language:' tag!", g:xolox#easytags#version, num_invalid) + endif + let directory = xolox#misc#path#absolute(g:easytags_by_filetype) + for vim_ft in keys(filetypes) + let tagsfile = xolox#misc#path#merge(directory, vim_ft) + let existing = filereadable(tagsfile) + call xolox#misc#msg#debug("easytags.vim %s: Writing %s tags to %s tags file %s.", + \ g:xolox#easytags#version, len(filetypes[vim_ft]), + \ existing ? "existing" : "new", tagsfile) + if !existing + call xolox#easytags#write_tagsfile(tagsfile, a:headers, filetypes[vim_ft]) + else + call s:filter_merge_tags(a:filter_tags, tagsfile, filetypes[vim_ft], a:context) + endif + endfor +endfunction + +" Public supporting functions (might be useful to others). {{{1 + +function! xolox#easytags#supported_filetypes() " {{{2 + if !exists('s:supported_filetypes') + let starttime = xolox#misc#timer#start() + let listing = [] + if !empty(g:easytags_cmd) + let command = g:easytags_cmd . ' --list-languages' + let listing = xolox#misc#os#exec({'command': command})['stdout'] + endif + let s:supported_filetypes = map(copy(listing) + keys(xolox#misc#option#get('easytags_languages', {})), 's:check_filetype(listing, v:val)') + let msg = "easytags.vim %s: Retrieved %i supported languages in %s." + call xolox#misc#timer#stop(msg, g:xolox#easytags#version, len(s:supported_filetypes), starttime) + endif + return s:supported_filetypes +endfunction + +function! s:check_filetype(listing, cline) + if a:cline !~ '^\w\S*$' + let msg = "Failed to get supported languages! (output: %s)" + throw printf(msg, strtrans(join(a:listing, "\n"))) + endif + return xolox#easytags#to_vim_ft(a:cline) +endfunction + +function! xolox#easytags#select_supported_filetypes(vim_ft) " {{{2 + let supported_filetypes = xolox#easytags#supported_filetypes() + let applicable_filetypes = [] + for ft in split(&filetype, '\.') + if index(supported_filetypes, ft) >= 0 + call add(applicable_filetypes, ft) + endif + endfor + return applicable_filetypes +endfunction + +function! xolox#easytags#read_tagsfile(tagsfile) " {{{2 + " I'm not sure whether this is by design or an implementation detail but + " it's possible for the "!_TAG_FILE_SORTED" header to appear after one or + " more tags and Vim will apparently still use the header! For this reason + " the xolox#easytags#write_tagsfile() function should also recognize it, + " otherwise Vim might complain with "E432: Tags file not sorted". + let headers = [] + let entries = [] + let num_invalid = 0 + for line in readfile(a:tagsfile) + if line =~# '^!_TAG_' + call add(headers, line) + else + let entry = xolox#easytags#parse_entry(line) + if !empty(entry) + call add(entries, entry) + else + let num_invalid += 1 + endif + endif + endfor + if num_invalid > 0 + call xolox#misc#msg#warn("easytags.vim %s: Ignored %i invalid line(s) in %s!", g:xolox#easytags#version, num_invalid, a:tagsfile) + endif + return [headers, entries] +endfunction + +function! xolox#easytags#parse_entry(line) " {{{2 + let fields = split(a:line, '\t') + return len(fields) >= 3 ? fields : [] +endfunction + +function! xolox#easytags#parse_entries(lines) " {{{2 + call map(a:lines, 'xolox#easytags#parse_entry(v:val)') + return filter(a:lines, '!empty(v:val)') +endfunction + +function! xolox#easytags#write_tagsfile(tagsfile, headers, entries) " {{{2 + " This function always sorts the tags file but understands "foldcase". + let sort_order = 1 + for line in a:headers + if match(line, '^!_TAG_FILE_SORTED\t2') == 0 + let sort_order = 2 + endif + endfor + call map(a:entries, 's:join_entry(v:val)') + if sort_order == 1 + call sort(a:entries) + else + call sort(a:entries, function('s:foldcase_compare')) + endif + let lines = [] + if xolox#misc#os#is_win() + " Exuberant Ctags on Windows requires \r\n but Vim's writefile() doesn't add them! + for line in a:headers + call add(lines, line . "\r") + endfor + for line in a:entries + call add(lines, line . "\r") + endfor + else + call extend(lines, a:headers) + call extend(lines, a:entries) + endif + let tempname = a:tagsfile . '.easytags.tmp' + return writefile(lines, tempname) == 0 && rename(tempname, a:tagsfile) == 0 +endfunction + +function! s:join_entry(value) + return type(a:value) == type([]) ? join(a:value, "\t") : a:value +endfunction + +function! s:foldcase_compare(a, b) + let a = toupper(a:a) + let b = toupper(a:b) + return a == b ? 0 : a ># b ? 1 : -1 +endfunction + +function! xolox#easytags#file_has_tags(filename) " {{{2 + " Check whether the given source file occurs in one of the tags files known + " to Vim. This function might not always give the right answer because of + " caching, but for the intended purpose that's no problem: When editing an + " existing file which has no tags defined the plug-in will run Exuberant + " Ctags to update the tags, *unless the file has already been tagged*. + call s:cache_tagged_files(s:create_context()) + return has_key(s:tagged_files, s:resolve(a:filename)) +endfunction + +if !exists('s:tagged_files') + let s:tagged_files = {} + let s:known_tagfiles = {} +endif + +function! s:cache_tagged_files(context) " {{{3 + if empty(s:tagged_files) + " Initialize the cache of tagged files on first use. After initialization + " we'll only update the cache when we're reading a tags file from disk for + " other purposes anyway (so the cache doesn't introduce too much overhead). + let starttime = xolox#misc#timer#start() + for tagsfile in tagfiles() + if !filereadable(tagsfile) + call xolox#misc#msg#warn("easytags.vim %s: Skipping unreadable tags file %s!", g:xolox#easytags#version, tagsfile) + else + let fname = s:canonicalize(tagsfile, a:context) + let ftime = getftime(fname) + if get(s:known_tagfiles, fname, 0) != ftime + let [headers, entries] = xolox#easytags#read_tagsfile(fname) + call s:cache_tagged_files_in(fname, ftime, entries, a:context) + endif + endif + endfor + call xolox#misc#timer#stop("easytags.vim %s: Initialized cache of tagged files in %s.", g:xolox#easytags#version, starttime) + endif +endfunction + +function! s:cache_tagged_files_in(fname, ftime, entries, context) " {{{3 + for entry in a:entries + let filename = s:canonicalize(entry[1], a:context) + if filename != '' + let s:tagged_files[filename] = 1 + endif + endfor + let s:known_tagfiles[a:fname] = a:ftime +endfunction + +function! xolox#easytags#get_tagsfile() " {{{2 + let tagsfile = '' + " Look for a suitable project specific tags file? + let dynamic_files = xolox#misc#option#get('easytags_dynamic_files', 0) + if dynamic_files == 1 + let tagsfile = get(tagfiles(), 0, '') + elseif dynamic_files == 2 + let tagsfile = xolox#misc#option#eval_tags(&tags, 1) + let directory = fnamemodify(tagsfile, ':h') + if filewritable(directory) != 2 + " If the directory of the dynamic tags file is not writable, we fall + " back to a file type specific tags file or the global tags file. + call xolox#misc#msg#warn("easytags.vim %s: Dynamic tags files enabled but %s not writable so falling back.", g:xolox#easytags#version, directory) + let tagsfile = '' + endif + endif + " Check if a file type specific tags file is useful? + let applicable_filetypes = xolox#easytags#select_supported_filetypes(&ft) + if empty(tagsfile) && !empty(g:easytags_by_filetype) && !empty(applicable_filetypes) + let directory = xolox#misc#path#absolute(g:easytags_by_filetype) + let tagsfile = xolox#misc#path#merge(directory, applicable_filetypes[0]) + endif + " Default to the global tags file? + if empty(tagsfile) + let tagsfile = expand(xolox#misc#option#get('easytags_file')) + endif + " If the tags file exists, make sure it is writable! + if filereadable(tagsfile) && filewritable(tagsfile) != 1 + let message = "The tags file %s isn't writable!" + throw printf(message, fnamemodify(tagsfile, ':~')) + endif + return tagsfile +endfunction + +" Public API for definition of file type specific dynamic syntax highlighting. {{{1 + +function! xolox#easytags#define_tagkind(object) " {{{2 + if !has_key(a:object, 'pattern_prefix') + let a:object.pattern_prefix = '\C\<' + endif + if !has_key(a:object, 'pattern_suffix') + let a:object.pattern_suffix = '\>' + endif + if !has_key(s:tagkinds, a:object.filetype) + let s:tagkinds[a:object.filetype] = [] + endif + call add(s:tagkinds[a:object.filetype], a:object) +endfunction + +function! xolox#easytags#map_filetypes(vim_ft, ctags_ft) " {{{2 + call add(s:vim_filetypes, a:vim_ft) + call add(s:ctags_filetypes, a:ctags_ft) +endfunction + +function! xolox#easytags#alias_filetypes(...) " {{{2 + " TODO Simplify alias handling, this much complexity really isn't needed! + for type in a:000 + let s:canonical_aliases[type] = a:1 + if !has_key(s:aliases, type) + let s:aliases[type] = {} + endif + endfor + for i in range(a:0) + for j in range(a:0) + let vimft1 = a:000[i] + let ctagsft1 = xolox#easytags#to_ctags_ft(vimft1) + let vimft2 = a:000[j] + let ctagsft2 = xolox#easytags#to_ctags_ft(vimft2) + if !has_key(s:aliases[vimft1], ctagsft2) + let s:aliases[vimft1][ctagsft2] = 1 + endif + if !has_key(s:aliases[vimft2], ctagsft1) + let s:aliases[vimft2][ctagsft1] = 1 + endif + endfor + endfor +endfunction + +function! xolox#easytags#to_vim_ft(ctags_ft) " {{{2 + let type = tolower(a:ctags_ft) + let index = index(s:ctags_filetypes, type) + return index >= 0 ? s:vim_filetypes[index] : type +endfunction + +function! xolox#easytags#to_ctags_ft(vim_ft) " {{{2 + let type = tolower(a:vim_ft) + let index = index(s:vim_filetypes, type) + return index >= 0 ? s:ctags_filetypes[index] : type +endfunction + +" Miscellaneous script-local functions. {{{1 + +function! s:create_context() " {{{2 + return {'cache': {}} +endfunction + +function! s:resolve(filename) " {{{2 + if xolox#misc#option#get('easytags_resolve_links', 0) + return resolve(a:filename) + else + return a:filename + endif +endfunction + +function! s:canonicalize(filename, context) " {{{2 + if a:filename != '' + if has_key(a:context.cache, a:filename) + return a:context.cache[a:filename] + else + let canonical = s:resolve(fnamemodify(a:filename, ':p')) + let a:context.cache[a:filename] = canonical + return canonical + endif + endif + return '' +endfunction + +function! s:python_available() " {{{2 + if !exists('s:is_python_available') + try + execute 'pyfile' fnameescape(g:easytags_python_script) + redir => output + silent python easytags_ping() + redir END + let s:is_python_available = (output =~ 'it works!') + catch + let s:is_python_available = 0 + endtry + endif + return s:is_python_available +endfunction + +function! s:highlight_with_python(syntax_group, tagkind) " {{{2 + if xolox#misc#option#get('easytags_python_enabled', 1) && s:python_available() + " Gather arguments for Python function. + let context = {} + let context['tagsfiles'] = tagfiles() + let context['syntaxgroup'] = a:syntax_group + let applicable_filetypes = xolox#easytags#select_supported_filetypes(&ft) + let context['filetype'] = xolox#easytags#to_ctags_ft(applicable_filetypes[0]) + let context['tagkinds'] = get(a:tagkind, 'tagkinds', '') + let context['prefix'] = get(a:tagkind, 'pattern_prefix', '') + let context['suffix'] = get(a:tagkind, 'pattern_suffix', '') + let context['filters'] = get(a:tagkind, 'python_filter', {}) + let context['ignoresyntax'] = xolox#misc#option#get('easytags_ignored_syntax_groups') + " Call the Python function and intercept the output. + try + redir => commands + python import vim + silent python print easytags_gensyncmd(**vim.eval('context')) + redir END + execute commands + return 1 + catch + redir END + " If the Python script raised an error, don't run it again. + let g:easytags_python_enabled = 0 + endtry + endif + return 0 +endfunction + +" Built-in file type & tag kind definitions. {{{1 + +" Don't bother redefining everything below when this script is sourced again. +if exists('s:tagkinds') + finish +endif + +let s:tagkinds = {} + +" Define the built-in Vim <=> Ctags file-type mappings. +let s:vim_filetypes = [] +let s:ctags_filetypes = [] +call xolox#easytags#map_filetypes('cpp', 'c++') +call xolox#easytags#map_filetypes('cs', 'c#') +call xolox#easytags#map_filetypes(exists('g:filetype_asp') ? g:filetype_asp : 'aspvbs', 'asp') + +" Define the Vim file-types that are aliased by default. +let s:aliases = {} +let s:canonical_aliases = {} +call xolox#easytags#alias_filetypes('c', 'cpp', 'objc', 'objcpp') +call xolox#easytags#alias_filetypes('html', 'htmldjango') + +" Enable line continuation. +let s:cpo_save = &cpo +set cpo&vim + +" Lua. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'lua', + \ 'hlgroup': 'luaFunc', + \ 'tagkinds': 'f'}) + +" C. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'c', + \ 'hlgroup': 'cType', + \ 'tagkinds': '[cgstu]'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'c', + \ 'hlgroup': 'cEnum', + \ 'tagkinds': 'e'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'c', + \ 'hlgroup': 'cPreProc', + \ 'tagkinds': 'd'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'c', + \ 'hlgroup': 'cFunction', + \ 'tagkinds': '[fp]'}) + +highlight def link cEnum Identifier +highlight def link cFunction Function + +if xolox#misc#option#get('easytags_include_members', 0) + call xolox#easytags#define_tagkind({ + \ 'filetype': 'c', + \ 'hlgroup': 'cMember', + \ 'tagkinds': 'm'}) + highlight def link cMember Identifier +endif + +" PHP. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'php', + \ 'hlgroup': 'phpFunctions', + \ 'tagkinds': 'f', + \ 'pattern_suffix': '(\@='}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'php', + \ 'hlgroup': 'phpClasses', + \ 'tagkinds': 'c'}) + +" Vim script. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'vim', + \ 'hlgroup': 'vimAutoGroup', + \ 'tagkinds': 'a'}) + +highlight def link vimAutoGroup vimAutoEvent + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'vim', + \ 'hlgroup': 'vimCommand', + \ 'tagkinds': 'c', + \ 'pattern_prefix': '\(\(^\|\s\):\?\)\@<=', + \ 'pattern_suffix': '\(!\?\(\s\|$\)\)\@='}) + +" Exuberant Ctags doesn't mark script local functions in Vim scripts as +" "static". When your tags file contains search patterns this plug-in can use +" those search patterns to check which Vim script functions are defined +" globally and which script local. + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'vim', + \ 'hlgroup': 'vimFuncName', + \ 'vim_filter': 'v:val.kind ==# "f" && get(v:val, "cmd", "") !~? ''<sid>\w\|\<s:\w''', + \ 'python_filter': { 'kind': 'f', 'nomatch': '(?i)(<sid>\w|\bs:\w)' }, + \ 'pattern_prefix': '\C\%(\<s:\|<[sS][iI][dD]>\)\@<!\<'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'vim', + \ 'hlgroup': 'vimScriptFuncName', + \ 'vim_filter': 'v:val.kind ==# "f" && get(v:val, "cmd", "") =~? ''<sid>\w\|\<s:\w''', + \ 'python_filter': { 'kind': 'f', 'match': '(?i)(<sid>\w|\bs:\w)' }, + \ 'pattern_prefix': '\C\%(\<s:\|<[sS][iI][dD]>\)'}) + +highlight def link vimScriptFuncName vimFuncName + +" Python. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'python', + \ 'hlgroup': 'pythonFunction', + \ 'tagkinds': 'f', + \ 'pattern_prefix': '\%(\<def\s\+\)\@<!\<'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'python', + \ 'hlgroup': 'pythonMethod', + \ 'tagkinds': 'm', + \ 'pattern_prefix': '\.\@<='}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'python', + \ 'hlgroup': 'pythonClass', + \ 'tagkinds': 'c'}) + +highlight def link pythonMethodTag pythonFunction +highlight def link pythonClassTag pythonFunction + +" Java. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'java', + \ 'hlgroup': 'javaClass', + \ 'tagkinds': 'c'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'java', + \ 'hlgroup': 'javaMethod', + \ 'tagkinds': 'm'}) + +highlight def link javaClass Identifier +highlight def link javaMethod Function + +" C#. {{{2 + +" TODO C# name spaces, interface names, enumeration member names, structure names? + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'cs', + \ 'hlgroup': 'csClassOrStruct', + \ 'tagkinds': 'c'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'cs', + \ 'hlgroup': 'csMethod', + \ 'tagkinds': '[ms]'}) + +highlight def link csClassOrStruct Identifier +highlight def link csMethod Function + +" Ruby. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'ruby', + \ 'hlgroup': 'rubyModuleName', + \ 'tagkinds': 'm'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'ruby', + \ 'hlgroup': 'rubyClassName', + \ 'tagkinds': 'c'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'ruby', + \ 'hlgroup': 'rubyMethodName', + \ 'tagkinds': '[fF]'}) + +highlight def link rubyModuleName Type +highlight def link rubyClassName Type +highlight def link rubyMethodName Function + +" Awk. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'awk', + \ 'hlgroup': 'awkFunctionTag', + \ 'tagkinds': 'f'}) + +highlight def link awkFunctionTag Function + +" Shell. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'sh', + \ 'hlgroup': 'shFunctionTag', + \ 'tagkinds': 'f', + \ 'pattern_suffix': '\(\w\|\s*()\)\@!'}) + +highlight def link shFunctionTag Operator + +" Tcl. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'tcl', + \ 'hlgroup': 'tclCommandTag', + \ 'tagkinds': 'p'}) + +highlight def link tclCommandTag Operator + +" }}} + +" Restore "cpoptions". +let &cpo = s:cpo_save +unlet s:cpo_save + +" vim: ts=2 sw=2 et diff --git a/doc/easytags.txt b/doc/easytags.txt new file mode 100644 index 0000000..f6edef1 --- /dev/null +++ b/doc/easytags.txt @@ -0,0 +1,659 @@ +*easytags.txt* Automated tag generation and syntax highlighting in Vim + +=============================================================================== + *easytags-contents* +Contents ~ + + 1. Introduction |easytags-introduction| + 2. Installation |easytags-installation| + 1. A note about Windows |easytags-a-note-about-windows| + 3. Commands |easytags-commands| + 1. The |:UpdateTags| command + 2. The |:HighlightTags| command + 4. Options |easytags-options| + 1. The |g:easytags_cmd| option + 2. The |g:easytags_languages| option + 3. The |g:easytags_file| option + 4. The |g:easytags_dynamic_files| option + 5. The |g:easytags_by_filetype| option + 6. The |g:easytags_always_enabled| option + 7. The |g:easytags_on_cursorhold| option + 8. The |g:easytags_updatetime_min| option + 9. The |g:easytags_updatetime_warn| option + 10. The |g:easytags_auto_update| option + 11. The |g:easytags_auto_highlight| option + 12. The |g:easytags_autorecurse| option + 13. The |g:easytags_include_members| option + 14. The |g:easytags_resolve_links| option + 15. The |g:easytags_suppress_ctags_warning| option + 16. The |g:easytags_ignored_syntax_groups| option + 5. Customizing the easytags plug-in |customizing-easytags-plug-in| + 1. Passing custom command line arguments to Exuberant Ctags + 2. Update & highlight tags immediately after save + 3. How to customize the highlighting colors? + 6. Faster syntax highlighting using Python |easytags-faster-syntax-highlighting-using-python| + 1. The |g:easytags_python_enabled| option + 2. The |g:easytags_python_script| option + 7. Troubleshooting |easytags-troubleshooting| + 1. |:HighlightTags| only works for the tags file created by |:UpdateTags| + 2. The plug-in complains that Exuberant Ctags isn't installed + 3. Vim locks up while the plug-in is running + 4. Failed to highlight tags because pattern is too big! + 5. The plug-in doesn't seem to work in Cygwin + 8. Contact |easytags-contact| + 9. License |easytags-license| + +=============================================================================== + *easytags-introduction* +Introduction ~ + +Vim has long been my favorite text editor and combined with Exuberant Ctags +[1] it has the potential to provide most of what I expect from an integrated +development environment [2]. Exuberant Ctags is the latest incarnation of a +family of computer programs [3] that scan source code files to create an index +of identifiers (tags) and where they are defined. Vim uses this index (a +so-called tags file) to enable you to jump to the definition of any identifier +using the Control-] (see |CTRL-]|) mapping. + +When you're familiar with integrated development environments you may +recognize this feature as "Go-to definition". One advantage of the combination +of Vim and Exuberant Ctags over integrated development environments is that +Vim supports syntax highlighting for over 500 file types [4] (!) and Exuberant +Ctags can generate tags for over 40 file types [5] as well... + +There's just one problem: You have to manually keep your tags files up-to-date +and this turns out to be a royal pain in the ass! So I set out to write a Vim +plug-in that would do this boring work for me. When I finished the plug-in's +basic functionality (one automatic command and a call to |system()| later) I +became interested in dynamic syntax highlighting, so I added that as well to +see if it would work -- surprisingly well I'm happy to report! + +=============================================================================== + *easytags-installation* +Installation ~ + +Unzip the most recent ZIP archive [6] file inside your Vim profile directory +(usually this is '~/.vim' on UNIX and '%USERPROFILE%\vimfiles' on Windows), +restart Vim and execute the command ':helptags ~/.vim/doc' (use ':helptags +~\vimfiles\doc' instead on Windows). Now try it out: Edit any file type +supported by Exuberant Ctags and within ten seconds the plug-in should +create/update your tags file ('~/.vimtags' on UNIX, '~/_vimtags' on Windows) +with the tags defined in the file you just edited! This means that whatever +file you're editing in Vim (as long as it's on the local file system), tags +will always be available by the time you need them! + +Additionally if the file you just opened is an AWK, C#, C, C++, Objective-C, +Java, Lua, PHP, Python, Ruby, Shell, Tcl or Vim source file you should also +notice that the function and type names defined in the file have been syntax +highlighted. + +The 'easytags.vim' plug-in is intended to work automatically once it's +installed, but if you want to change how it works there are several options +you can change and commands you can execute from your own mappings and/or +automatic commands. These are all documented below. + +Note that if the plug-in warns you 'ctags' isn't installed you'll have to +download it from its homepage [1], or if you're running Debian/Ubuntu you can +install it by executing the following shell command: +> + $ sudo apt-get install exuberant-ctags + +------------------------------------------------------------------------------- + *easytags-a-note-about-windows* +A note about Windows ~ + +On Windows the |system()| function used by 'easytags.vim' causes a command +prompt window to pop up while Exuberant Ctags is executing. If this bothers +you then you can install my shell.vim [7] plug-in which includes a DLL [8] +that works around this issue. Once you've installed both plug-ins it should +work out of the box! Please let me know if this doesn't work for you. + +=============================================================================== + *easytags-commands* +Commands ~ + +------------------------------------------------------------------------------- +The *:UpdateTags* command + +This command executes Exuberant Ctags [1] from inside Vim to update the global +tags file defined by |g:easytags_file|. When no arguments are given the tags +for the current file are updated, otherwise the arguments are passed on to +'ctags'. For example when you execute the Vim command ':UpdateTags -R ~/.vim' +(or ':UpdateTags -R ~\vimfiles' on Windows) the plug-in will execute 'ctags -R +~/.vim' for you (with some additional arguments, see the troubleshooting +section "|:HighlightTags| only works for the tags file created by +|:UpdateTags|" for more information). + +When you execute this command like ':UpdateTags!' (including the bang!) then +all tags whose files are missing will be filtered from the global tags file. + +Note that this command will be executed automatically every once in a while, +assuming you haven't changed |g:easytags_on_cursorhold|. + +------------------------------------------------------------------------------- +The *:HighlightTags* command + +When you execute this command while editing one of the supported file types +(see above) the relevant tags in the current file are highlighted. The tags to +highlight are gathered from all tags files known to Vim (through the |'tags'| +option). + +Note that this command will be executed automatically every once in a while, +assuming you haven't changed |g:easytags_on_cursorhold|. + +=============================================================================== + *easytags-options* +Options ~ + +The easytags plug-in should work out of the box but if you don't like the +default configuration you can change how it works by setting the variables +documented below. Most of these variables can also be changed for specific +files by setting a buffer local variable instead of the global variable. For +example to disable automatic highlighting (enabled by default) only in Python +files you can add the following line to your |vimrc| script: +> + :autocmd FileType python let b:easytags_auto_highlight = 0 + +Note that buffer local variables always override global variables, so if you +want to undo this for a specific file you have to use |:unlet|: +> + :unlet b:easytags_auto_highlight + +------------------------------------------------------------------------------- +The *g:easytags_cmd* option + +The plug-in will try to determine the location where Exuberant Ctags is +installed on its own but this might not always work because any given +executable named 'ctags' in your '$PATH' might not in fact be Exuberant Ctags +but some older, more primitive 'ctags' implementation which doesn't support +the same command line options and thus breaks the easytags plug-in. If this is +the case you can set the global variable |g:easytags_cmd| to the location +where you've installed Exuberant Ctags, e.g.: +> + :let g:easytags_cmd = '/usr/local/bin/ctags' + +If you rely entirely on language-specific configuration and don't have a +general ctags program, set this to the empty string. + +------------------------------------------------------------------------------- +The *g:easytags_languages* option + +Exuberant Ctags supports many languages and can be extended via regular +expression patterns, but for some languages separate tools with +ctags-compatible output exist (e.g. jsctags [9] for Javascript). To use these, +the executable and its arguments must be configured: +> + let g:easytags_languages = { + \ 'language': { + \ 'cmd': g:easytags_cmd, + \ 'args': [], + \ 'fileoutput_opt': '-f', + \ 'stdout_opt': '-f-', + \ 'recurse_flag': '-R' + \ } + \} + +Each key is a special language definition. The key is in the notation of ctags +in lowercase; you still need to use 'xolox#easytags#map_filetypes()' to map +this to Vim's filetypes, if necessary. + +Above snippets shows the defaults; you only need to specify options that +differ. + +------------------------------------------------------------------------------- +The *g:easytags_file* option + +As mentioned above the plug-in will store your tags in '~/.vimtags' on UNIX +and '~/_vimtags' on Windows. To change the location of this file, set the +global variable |g:easytags_file|, e.g.: +> + :let g:easytags_file = '~/.vim/tags' + +A leading '~' in the |g:easytags_file| variable is expanded to your current +home directory ('$HOME' on UNIX, '%USERPROFILE%' on Windows). + +------------------------------------------------------------------------------- +The *g:easytags_dynamic_files* option + +By default |:UpdateTags| only writes to the global tags file, but it can be +configured to look for project specific tags files by adding the following +lines to your |vimrc| script: +> + :set tags=./tags; + :let g:easytags_dynamic_files = 1 + +You can change the name of the tags file, the important thing is that it's +relative to your working directory or the buffer (using a leading './'). When +|g:easytags_dynamic_files| is set to 1 the easytags plug-in will write to the +first existing tags file seen by Vim (based on the |'tags'| option). In other +words: If a project specific tags file is found it will be used, otherwise the +plug-in falls back to the global tags file (or a file type specific tags +file). + +If you set |g:easytags_dynamic_files| to 2 the easytags plug-in will +automatically create project specific tags based on the first name in the +'tags' option. In this mode the the global tags file or file type specific +tags files are only used for directories where you don't have write +permissions. + +The |'tags'| option is reevaluated each time the plug-in runs, so which tags +file is selected can differ depending on the buffer and working directory. + +------------------------------------------------------------------------------- +The *g:easytags_by_filetype* option + +By default all tags are stored in a global tags file. When the tags file grows +beyond a certain size Vim will be slowed down by the easytags plug-in because +it has to read and process a large number of tags very frequently. + +To avoid this problem you can set |g:easytags_by_filetype| to the path of an +existing directory. The easytags plug-in will create separate tags files for +each file type in the configured directory. These tags files are automatically +registered by the easytags plug-in when the file type of a buffer is set. + +Note that the |g:easytags_dynamic_files| option takes precedence over this +option. + +If you already have a global tags file you can create file type specific tags +files from the global tags file using the command ':TagsByFileType'. + +------------------------------------------------------------------------------- +The *g:easytags_always_enabled* option + +By default the plug-in automatically generates and highlights tags when you +stop typing for a few seconds (this works using the |CursorHold| automatic +command). This means that when you edit a file, the dynamic highlighting won't +appear until you pause for a moment. If you don't like this you can configure +the plug-in to always enable dynamic highlighting: +> + :let g:easytags_always_enabled = 1 + +Be warned that after setting this option you'll probably notice why it's +disabled by default: Every time you edit a file in Vim, the plug-in will first +run Exuberant Ctags and then highlight the tags, and this slows Vim down quite +a lot. I have some ideas on how to improve this latency by running Exuberant +Ctags in the background so stay tuned! + +Note: If you change this option it won't apply until you restart Vim, so +you'll have to set this option in your |vimrc| script. + +------------------------------------------------------------------------------- +The *g:easytags_on_cursorhold* option + +As I explained above the plug-in by default doesn't update or highlight your +tags until you stop typing for a moment. The plug-in tries hard to do the +least amount of work possible in this break but it might still interrupt your +workflow. If it does you can disable the periodic update: +> + :let g:easytags_on_cursorhold = 0 + +Note: Like the |g:easytags_always_enabled| option, if you change this option +it won't apply until you restart Vim, so you'll have to set this option in +your |vimrc| script. + +------------------------------------------------------------------------------- +The *g:easytags_updatetime_min* option + +Vim's |'updatetime'| option controls how often the easytags plug-in is +automatically executed. A lot of popular Vim plug-ins manipulate this option +to control how often they are called. Unfortunately some of those plug-ins set +|'updatetime'| to a very low value (less than a second) and this can break the +easytags plug-in. + +Because of this the easytags plug-in compensates by keeping track of when it +was last executed. You'll get one warning when the plug-in first notices a +very low value of |'updatetime'|, after that the plug-in will shut up (until you +restart Vim) and simply compensate by not executing until its time has come. +If you want to silence the warning message forever, see the |g:easytags_updatetime_warn| +option. + +The default value of Vim's 'updatetime (see |'updatetime'|) option and the +|g:easytags_updatetime_min| option is 4000 milliseconds (4 seconds). + +If you know what you're doing and you really want the easytags plug-in to be +executed more than once every 4 seconds you can lower the minimum acceptable +updatetime by setting |g:easytags_updatetime_min| to the number of +milliseconds (an integer). + +Note that although |g:easytags_updatetime_min| counts in milliseconds, the +easytags plug-in does not support subsecond granularity because it is limited +by Vim's |localtime()| function which has one-second resolution. + +------------------------------------------------------------------------------- +The *g:easytags_updatetime_warn* option + +Since the easytags plug-in now compensates for low |'updatetime'| values (see +the |g:easytags_updatetime_min| option above) the warning message shown by the +easytags plug-in has become kind of redundant (and probably annoying?). For +now it can be completely disabled by setting |g:easytags_updatetime_warn| to 0 +(false). + +When the feature that compensates for low |'updatetime'| values has proven to be +a reliable workaround I will probably remove the warning message and the +|g:easytags_updatetime_warn| option. + +------------------------------------------------------------------------------- +The *g:easytags_auto_update* option + +By default the plug-in automatically updates and highlights your tags when you +stop typing for a moment. If you want to disable automatic updating while +keeping automatic highlighting enabled you can set this option to false: +> + :let g:easytags_auto_update = 0 + +------------------------------------------------------------------------------- +The *g:easytags_auto_highlight* option + +By default the plug-in automatically updates and highlights your tags when you +stop typing for a moment. If you want to disable automatic highlighting while +keeping automatic updating enabled you can set this option to false: +> + :let g:easytags_auto_highlight = 0 + +------------------------------------------------------------------------------- +The *g:easytags_autorecurse* option + +When the |:UpdateTags| command is executed automatically or without arguments, +it defaults to updating just the tags for the current file. If you'd rather +have it recursively scan everything below the directory of the current file +then set this option to true (1): +> + :let g:easytags_autorecurse = 1 + +You have to explicitly enable this option because it should only be used while +navigating around small directory trees. Imagine always having this option +enabled and then having to edit a file in e.g. the root of your home +directory: The 'easytags.vim' plug-in would freeze Vim for a long time while +you'd have to wait for Exuberant Ctags to scan thousands of files... + +Note that when you enable this option the 'easytags.vim' plug-in might ignore +other options like |g:easytags_resolve_links|. This is an implementation +detail which I intend to fix. + +------------------------------------------------------------------------------- +The *g:easytags_include_members* option + +Exuberant Ctags knows how to generate tags for struct/class members in C++ and +Java source code but doesn't do so by default because it can more than double +the size of your tags files, thus taking much longer to read/write the tags +file. When you enable the |g:easytags_include_members| option from your |vimrc| +script (before the 'easytags.vim' plug-in is loaded): +> + :let g:easytags_include_members = 1 + +Exuberant Ctags will be instructed to include struct/class members using the +'--extra=+q' command line argument and the 'easytags.vim' plug-in will +highlight them using the 'cMember' highlighting group. Because most color +schemes don't distinguish the Identifier and Type (see |group-name|) +highlighting groups all members will now probably look like type definitions. +You can change that by executing either of the following Vim commands (from +your vimrc script, a file type plug-in, etc.): +> + " If you like one of the existing styles you can link them: + highlight link cMember Special + + " You can also define your own style if you want: + highlight cMember gui=italic + +------------------------------------------------------------------------------- +The *g:easytags_resolve_links* option + +UNIX has symbolic links [10] and hard links [11], both of which conflict with +the concept of having one unique location for every identifier. With regards +to hard links there's not much anyone can do, but because I use symbolic links +quite a lot I've added this option. It's disabled by default since it has a +small performance impact and might not do what unknowing users expect it to: +When you enable this option the plug-in will resolve symbolic links in +pathnames, which means your tags file will only contain entries with canonical +pathnames [12]. To enable this option (which I strongly suggest doing when you +run UNIX and use symbolic links) execute the following Vim command: +> + :let g:easytags_resolve_links = 1 + +------------------------------------------------------------------------------- +The *g:easytags_suppress_ctags_warning* option + +If this is set and not false, it will suppress the warning on startup if ctags +is not found or not recent enough. +> + :let g:easytags_suppress_ctags_warning = 1 + +------------------------------------------------------------------------------- +The *g:easytags_ignored_syntax_groups* option + +This variable is a string of comma separated names of syntax groups in which +dynamic highlighting is not applied. It defaults to '.*String.*,.*Comment.*,cIncluded'. + +=============================================================================== + *customizing-easytags-plug-in* +Customizing the easytags plug-in ~ + +Advanced users may wish to customize how the easytags plug-in works beyond the +point of changing configuration defaults. This section contains some hints +about this. If you have suggestions, please feel free to submit them. + +------------------------------------------------------------------------------- +Passing custom command line arguments to Exuberant Ctags ~ + +You may want to run Exuberant Ctags with specific command line options, for +example the code_complete [13] plug-in requires the signature field to be +present. To do this you can create a configuration file for Exuberant Ctags, +e.g. '~/.ctags' on UNIX or '%USERPROFILE%\ctags.cnf' on Windows. The file +should contain one command line option per line. See the Exuberant Ctags +manual [14] for details. + +------------------------------------------------------------------------------- +Update & highlight tags immediately after save ~ + +By default the easytags plug-in automatically updates & highlights tags for +the current file after several seconds of inactivity. This is done to prevent +the easytags plug-in from interrupting your workflow. + +If you want the easytags plug-in to automatically update & highlight tags for +the current file right after you save the file, you can add the following line +to your |vimrc| script: +> + :autocmd BufWritePost * call xolox#easytags#autoload('BufWritePost') + +------------------------------------------------------------------------------- +How to customize the highlighting colors? ~ + +The easytags plug-in defines new highlighting groups for dynamically +highlighted tags. These groups are linked to Vim's default groups so that +they're colored out of the box, but if you want you can change the styles. To +do so use a 'highlight' command such as the ones given a few paragraphs back. +Of course you'll need to change the group name. Here are the group names used +by the easytags plug-in: + + - AWK: 'awkFunctionTag' + + - C#: 'csClassOrStructTag', 'csMethodTag' + + - C, C++, Objective C: 'cTypeTag', 'cEnumTag', 'cPreProcTag', 'cFunctionTag', + 'cMemberTag' + + - Java: 'javaClassTag', 'javaMethodTag' + + - Lua: 'luaFuncTag' + + - PHP: 'phpFunctionsTag', 'phpClassesTag' + + - Python: 'pythonFunctionTag', 'pythonMethodTag', 'pythonClassTag' + + - Ruby: 'rubyModuleNameTag', 'rubyClassNameTag', 'rubyMethodNameTag' + + - Shell: 'shFunctionTag' + + - Tcl: 'tclCommandTag' + + - Vim: 'vimAutoGroupTag', 'vimCommandTag', 'vimFuncNameTag', + 'vimScriptFuncNameTag' + +As you can see each of these names ends in 'Tag' to avoid conflicts with the +syntax modes shipped with Vim. And about the singular/plural confusion: I've +tried to match the existing highlighting groups defined by popular syntax +modes (except of course for the 'Tag' suffix). + +=============================================================================== + *easytags-faster-syntax-highlighting-using-python* +Faster syntax highlighting using Python ~ + +The Vim script implementation of dynamic syntax highlighting is quite slow on +large tags files. When the Python Interface to Vim is enabled the easytags +plug-in will therefor automatically use a Python script that performs dynamic +syntax highlighting about twice as fast as the Vim script implementation. The +following options are available to change the default configuration. + +------------------------------------------------------------------------------- +The *g:easytags_python_enabled* option + +To disable the Python implementation of dynamic syntax highlighting you can +set this option to false (0). + +------------------------------------------------------------------------------- +The *g:easytags_python_script* option + +This option defines the pathname of the script that contains the Python +implementation of dynamic syntax highlighting. + +=============================================================================== + *easytags-troubleshooting* +Troubleshooting ~ + +------------------------------------------------------------------------------- +|:HighlightTags| only works for the tags file created by |:UpdateTags| ~ + +If you want to create tags files and have their tags highlighted by the +'easytags.vim' plug-in then you'll have to create the tags file with certain +arguments to Exuberant Ctags: +> + $ ctags --fields=+l --c-kinds=+p --c++-kinds=+p ... + +The '--fields=+l' argument makes sure that Exuberant Ctags includes a +'language:...' property with each entry in the tags file. This is required by +the |:HighlightTags| command so it can filter tags by their file type. The +other two arguments make sure Exuberant Ctags generates tags for function +prototypes in C/C++ source code. + +If you have the |g:easytags_include_members| option enabled (its off by +default) then you'll also need to add the '--extra=+q' argument so that +Exuberant Ctags generates tags for structure/class members. + +------------------------------------------------------------------------------- +The plug-in complains that Exuberant Ctags isn't installed ~ + +After a Mac OS X user found out the hard way that the 'ctags' executable isn't +always Exuberant Ctags and we spend a few hours debugging the problem I added +proper version detection: The plug-in executes 'ctags --version' when Vim is +started to verify that Exuberant Ctags 5.5 or newer is installed. If it isn't +Vim will show the following message on startup: +> + easytags.vim: Plug-in not loaded because Exuberant Ctags isn't installed! + Please download & install Exuberant Ctags from http://ctags.sf.net + +If the installed Exuberant Ctags version is too old the plug-in will complain: +> + easytags.vim: Plug-in not loaded because Exuberant Ctags 5.5 + or newer is required while you have version %s installed! + +If you have the right version of Exuberant Ctags installed but the plug-in +still complains, try executing the following command from inside Vim: +> + :!which ctags + +If this doesn't print the location where you installed Exuberant Ctags it +means your system already had a 'ctags' executable but it isn't compatible +with Exuberant Ctags 5.5 and you'll need to set the |g:easytags_cmd| option +(see above) so the plug-in knows which 'ctags' to run. + +------------------------------------------------------------------------------- +Vim locks up while the plug-in is running ~ + +Once or twice now in several years I've experienced Exuberant Ctags getting +into an infinite loop when given garbage input. In my case this happened by +accident a few days ago :-|. Because my plug-in executes 'ctags' in the +foreground this will block Vim indefinitely! If this happens you might be able +to kill 'ctags' by pressing Control-C (see |CTRL-C|) but if that doesn't work +you can also kill it without stopping Vim using a task manager or the 'pkill' +command (available on most UNIX systems): +> + $ pkill -KILL ctags + +If Vim seems very slow and you suspect this plug-in might be the one to blame, +increase Vim's verbosity level: +> + :set vbs=1 + +Every time the plug-in executes it will time how long the execution takes and +add the results to Vim's message history, which you can view by executing the +|:messages| command. + +------------------------------------------------------------------------------- +Failed to highlight tags because pattern is too big! ~ + +If the 'easytags.vim' plug-in fails to highlight your tags and the error +message mentions that the pattern is too big, your tags file has grown too +large for Vim to be able to highlight all tagged identifiers! I've had this +happen to me with 50 KB patterns because I added most of the headers in +'/usr/include/' to my tags file. Internally Vim raises the error |E339|: Pattern +too long and unfortunately the only way to avoid this problem once it occurs +is to reduce the number of tagged identifiers... + +In my case the solution was to move most of the tags from '/usr/include/' over +to project specific tags files which are automatically loaded by Vim when I +edit files in different projects because I've set the |'tags'| option as +follows: +> + :set tags=./.tags;,~/.vimtags + +Once you've executed the above command, Vim will automatically look for a file +named '.tags' in the directory of the current file. Because of the ';' Vim +also recurses upwards so that you can nest files arbitrarily deep under your +project directories. + +------------------------------------------------------------------------------- +The plug-in doesn't seem to work in Cygwin ~ + +If you want to use the plug-in with Vim under Cygwin [15], you need to have +the Cygwin version of Ctags installed instead of the Windows version (thanks +to Alex Zuroff for reporting this!). + +=============================================================================== + *easytags-contact* +Contact ~ + +If you have questions, bug reports, suggestions, etc. the author can be +contacted at peter@peterodding.com. The latest version is available at +http://peterodding.com/code/vim/easytags/ and http://github.com/xolox/vim-easytags. +If you like this plug-in please vote for it on Vim Online [16]. + +=============================================================================== + *easytags-license* +License ~ + +This software is licensed under the MIT license [17]. Š 2013 Peter Odding +<peter@peterodding.com>. + +=============================================================================== + *easytags-references* +References ~ + +[1] http://ctags.sourceforge.net/ +[2] http://en.wikipedia.org/wiki/Integrated_development_environment +[3] http://en.wikipedia.org/wiki/Ctags +[4] http://ftp.vim.org/vim/runtime/syntax/ +[5] http://ctags.sourceforge.net/languages.html +[6] http://peterodding.com/code/vim/downloads/easytags.zip +[7] http://peterodding.com/code/vim/shell/ +[8] http://en.wikipedia.org/wiki/Dynamic-link_library +[9] https://npmjs.org/package/jsctags +[10] http://en.wikipedia.org/wiki/Symbolic_link +[11] http://en.wikipedia.org/wiki/Hard_link +[12] http://en.wikipedia.org/wiki/Canonicalization +[13] http://www.vim.org/scripts/script.php?script_id=1764 +[14] http://ctags.sourceforge.net/ctags.html#FILES +[15] http://en.wikipedia.org/wiki/Cygwin +[16] http://www.vim.org/scripts/script.php?script_id=3114 +[17] http://en.wikipedia.org/wiki/MIT_License + +vim: ft=help diff --git a/misc/easytags/highlight.py b/misc/easytags/highlight.py new file mode 100644 index 0000000..154854e --- /dev/null +++ b/misc/easytags/highlight.py @@ -0,0 +1,55 @@ +''' +This Python script is part of the easytags plug-in for the Vim text editor. The +Python Interface to Vim is used to load this script which accelerates dynamic +syntax highlighting by reimplementing tag file reading and :syntax command +generation in Python with a focus on doing the least amount of work. + +Author: Peter Odding <peter@peterodding.com> +Last Change: October 29, 2011 +URL: http://peterodding.com/code/vim/easytags +''' + +# TODO Cache the contents of tags files to further improve performance? + +import re +import vim +import sys + +def easytags_ping(): + print 'it works!' + +def easytags_gensyncmd(tagsfiles, filetype, tagkinds, syntaxgroup, prefix, suffix, filters, ignoresyntax): + # Get arguments from Vim. + if filters: + tagkinds = filters['kind'] + # Shallow parse tags files for matching identifiers. + pattern = '^([^\t]+)\t[^\t]+\t[^\t]+\t' + tagkinds + '\tlanguage:' + filetype + compiled_pattern = re.compile(pattern, re.IGNORECASE) + matches = {} + for fname in tagsfiles: + handle = open(fname) + for line in handle: + m = compiled_pattern.match(line) + if m and ('match' not in filters or re.search(filters['match'], line)) \ + and ('nomatch' not in filters or not re.search(filters['nomatch'], line)): + matches[m.group(1)] = True + handle.close() + # Generate Vim :syntax command to highlight identifiers. + patterns, commands = [], [] + counter, limit = 0, 1024 * 20 + to_escape = re.compile(r'[.*^$/\\~\[\]]') + for ident in matches.keys(): + escaped = to_escape.sub(r'\\\0', ident) + patterns.append(escaped) + counter += len(escaped) + if counter > limit: + commands.append(_easytags_makecmd(syntaxgroup, prefix, suffix, patterns, ignoresyntax)) + patterns = [] + counter = 0 + if patterns: + commands.append(_easytags_makecmd(syntaxgroup, prefix, suffix, patterns, ignoresyntax)) + return ' | '.join(commands) + +def _easytags_makecmd(syntaxgroup, prefix, suffix, patterns, ignoresyntax): + template = r'syntax match %s /%s\%%(%s\)%s/ containedin=ALLBUT,%s' + return template % (syntaxgroup, prefix, r'\|'.join(patterns), suffix, ignoresyntax) diff --git a/misc/easytags/normalize-tags.py b/misc/easytags/normalize-tags.py new file mode 100755 index 0000000..a96ed3f --- /dev/null +++ b/misc/easytags/normalize-tags.py @@ -0,0 +1,80 @@ +#!/usr/bin/python + +''' +Resolve symbolic links in tags files and remove duplicate entries from the +resulting list of tags. If your tags files contain symbolic links as well as +canonical filenames this can significantly reduce the size of your tags file. +This script makes a backup of the tags file in case something goes wrong. + +Author: Peter Odding <peter@peterodding.com> +Last Change: September 4, 2011 +URL: https://github.com/xolox/vim-easytags/blob/master/normalize-tags.py +''' + +import os, sys, time + +def main(arguments): + for tagsfile in arguments or [os.path.expanduser('~/.vimtags')]: + normalize(tagsfile) + print "Done!" + +def normalize(tagsfile): + + # Setup. + tempname = '%s-new-%d' % (tagsfile, time.time()) + results, cache = {}, {} + infile = open(tagsfile) + outfile = open(tempname, 'w') + nprocessed = 0 + fold_case = False + + # Read tags file. + for line in infile: + line = line.rstrip() + fields = line.split('\t') + if line.startswith('!_TAG_'): + results[line] = True + if line.startswith('!_TAG_FILE_SORTED\t2'): + fold_case = True + else: + pathname = fields[1] + if pathname not in cache: + if os.path.exists(pathname): + cache[pathname] = os.path.realpath(pathname) + else: + cache[pathname] = '' + if cache[pathname]: + fields[1] = cache[pathname] + results['\t'.join(fields)] = True + nprocessed += 1 + infile.close() + + # Sort tags. + lines = results.keys() + if fold_case: + lines.sort(key=str.lower) + else: + lines.sort() + + # Write tags file. + outfile.write('\n'.join(lines)) + outfile.write('\n') + outfile.close() + + # Backup old tags file. + backup = '%s-backup-%d' % (tagsfile, time.time()) + print "Making a backup of %s as %s" % (tagsfile, backup) + os.rename(tagsfile, backup) + + # Replace tags file. + print "Replacing old", tagsfile, "with new one" + os.rename(tempname, tagsfile) + + # Report results. + nfiltered = nprocessed - len(lines) + print "Filtered %d out of %d entries" % (nfiltered, nprocessed) + +if __name__ == '__main__': + main(sys.argv[1:]) + +# vim: ts=2 sw=2 et diff --git a/misc/easytags/why-so-slow.py b/misc/easytags/why-so-slow.py new file mode 100755 index 0000000..ead62f2 --- /dev/null +++ b/misc/easytags/why-so-slow.py @@ -0,0 +1,39 @@ +#!/usr/bin/python + +''' +Determine which files are contributing the most to the size of a tags file. You +can specify the location of the tags file as a command line argument. If you +pass a numeric argument, no more than that many files will be reported. + +Author: Peter Odding <peter@peterodding.com> +Last Change: May 11, 2011 +URL: https://github.com/xolox/vim-easytags/blob/master/why-so-slow.py +''' + +import os, sys + +tagsfile = '~/.vimtags' +topfiles = 10 + +for arg in sys.argv[1:]: + if os.path.isfile(arg): + tagsfile = arg + else: + topfiles = int(arg) + +infile = open(os.path.expanduser(tagsfile)) +counters = {} + +for line in infile: + fields = line.split('\t') + filename = fields[1] + counters[filename] = counters.get(filename, 0) + len(line) +infile.close() + +sortedfiles = sorted([(s, n) for (n, s) in counters.iteritems()], reverse=True) +for filesize, filename in sortedfiles[:topfiles]: + if filename.startswith(os.environ['HOME']): + filename = filename.replace(os.environ['HOME'], '~') + print '%i KB - %s' % (filesize / 1024, filename) + +# vim: ts=2 sw=2 et diff --git a/plugin/easytags.vim b/plugin/easytags.vim new file mode 100644 index 0000000..64361a7 --- /dev/null +++ b/plugin/easytags.vim @@ -0,0 +1,181 @@ +" Vim plug-in +" Author: Peter Odding <peter@peterodding.com> +" Last Change: May 13, 2013 +" URL: http://peterodding.com/code/vim/easytags/ +" Requires: Exuberant Ctags (http://ctags.sf.net) + +" Support for automatic update using the GLVS plug-in. +" GetLatestVimScripts: 3114 1 :AutoInstall: easytags.zip + +" Don't source the plug-in when it's already been loaded or &compatible is set. +if &cp || exists('g:loaded_easytags') + finish +endif + +" Configuration defaults and initialization. {{{1 + +if !exists('g:easytags_file') + if xolox#misc#os#is_win() + let g:easytags_file = '~\_vimtags' + else + let g:easytags_file = '~/.vimtags' + endif +endif + +if !exists('g:easytags_by_filetype') + let g:easytags_by_filetype = '' +endif + +if !exists('g:easytags_events') + let g:easytags_events = [] + if !exists('g:easytags_on_cursorhold') || g:easytags_on_cursorhold + call extend(g:easytags_events, ['CursorHold', 'CursorHoldI']) + endif + if exists('g:easytags_always_enabled') && g:easytags_always_enabled + call extend(g:easytags_events, ['BufReadPost', 'BufWritePost', 'FocusGained', 'ShellCmdPost', 'ShellFilterPost']) + endif +endif + +if !exists('g:easytags_ignored_filetypes') + let g:easytags_ignored_filetypes = '^tex$' +endif + +if !exists('g:easytags_ignored_syntax_groups') + let g:easytags_ignored_syntax_groups = '.*String.*,.*Comment.*,cIncluded' +endif + +if !exists('g:easytags_python_script') + let g:easytags_python_script = expand('<sfile>:p:h') . '/../misc/easytags/highlight.py' +endif + +function! s:InitEasyTags(version) + " Check that the location of Exuberant Ctags has been configured or that the + " correct version of the program exists in one of its default locations. + if exists('g:easytags_cmd') && s:CheckCtags(g:easytags_cmd, a:version) + return 1 + endif + if xolox#misc#os#is_win() + " FIXME The code below that searches the $PATH is not used on Windows at + " the moment because xolox#misc#path#which() generally produces absolute + " paths and on Windows these absolute paths tend to contain spaces which + " makes xolox#shell#execute_with_dll() fail. I've tried quoting the + " program name with double quotes but it fails just the same (it works + " with system() though). Anyway the problem of having multiple conflicting + " versions of Exuberant Ctags installed is not that relevant to Windows + " since it doesn't have a package management system. I still want to fix + " xolox#shell#execute_with_dll() though. + if s:CheckCtags('ctags', a:version) + let g:easytags_cmd = 'ctags' + return 1 + endif + else + " Exuberant Ctags can be installed under multiple names: + " - On Ubuntu Linux, Exuberant Ctags is installed as `ctags-exuberant' + " (and possibly `ctags' but that one can't be trusted :-) + " - On Debian Linux, Exuberant Ctags is installed as `exuberant-ctags'. + " - On Free-BSD, Exuberant Ctags is installed as `exctags'. + " IIUC on Mac OS X the program /usr/bin/ctags is installed by default but + " unusable and when the user installs Exuberant Ctags in an alternative + " location, it doesn't come before /usr/bin/ctags in the search path. To + " solve this problem in a general way and to save every Mac user out there + " some frustration the plug-in will search the path and consider every + " possible location, meaning that as long as Exuberant Ctags is installed + " in the $PATH the plug-in should find it automatically. + for program in xolox#misc#path#which('exuberant-ctags', 'ctags-exuberant', 'ctags', 'exctags') + if s:CheckCtags(program, a:version) + let g:easytags_cmd = program + return 1 + endif + endfor + endif +endfunction + +function! s:CheckCtags(name, version) + " Not every executable out there named `ctags' is in fact Exuberant Ctags. + " This function makes sure it is because the easytags plug-in requires the + " --list-languages option (and more). + if executable(a:name) + let command = a:name . ' --version' + let result = xolox#misc#os#exec({'command': command, 'check': 0}) + if result['exit_code'] == 0 + let pattern = 'Exuberant Ctags \zs\(\d\+\(\.\d\+\)*\|Development\)' + let g:easytags_ctags_version = matchstr(result['stdout'][0], pattern) + if g:easytags_ctags_version == 'Development' + return 1 + else + return s:VersionToNumber(g:easytags_ctags_version) >= a:version + endif + endif + endif +endfunction + +function! s:VersionToNumber(s) + let values = split(a:s, '\.') + if len(values) == 1 + return values[0] * 10 + elseif len(values) >= 2 + return values[0] * 10 + values[1][0] + endif +endfunction + +if !s:InitEasyTags(55) + if exists('g:easytags_suppress_ctags_warning') && g:easytags_suppress_ctags_warning + finish + endif + if !exists('g:easytags_ctags_version') || empty(g:easytags_ctags_version) + let s:msg = "easytags.vim %s: Plug-in not loaded because Exuberant Ctags isn't installed!" + if executable('apt-get') + let s:msg .= " On Ubuntu & Debian you can install Exuberant Ctags by" + let s:msg .= " installing the package named `exuberant-ctags':" + let s:msg .= " sudo apt-get install exuberant-ctags" + else + let s:msg .= " Please download & install Exuberant Ctags from http://ctags.sf.net" + endif + echomsg printf(s:msg, g:xolox#easytags#version) + else + let s:msg = "easytags.vim %s: Plug-in not loaded because Exuberant Ctags 5.5" + let s:msg .= " or newer is required while you have version %s installed!" + echomsg printf(s:msg, g:xolox#easytags#version, g:easytags_ctags_version) + endif + unlet s:msg + finish +endif + +" The plug-in initializes the &tags option as soon as possible so that the +" global tags file is available when using "vim -t some_tag". If &tags is +" reset, we'll try again on the "VimEnter" automatic command event (below). +call xolox#easytags#register(1) + +" The :UpdateTags and :HighlightTags commands. {{{1 + +command! -bar -bang -nargs=* -complete=file UpdateTags call xolox#easytags#update(0, <q-bang> == '!', [<f-args>]) +command! -bar HighlightTags call xolox#easytags#highlight() +command! -bang TagsByFileType call xolox#easytags#by_filetype(<q-bang> == '!') + +" Automatic commands. {{{1 + +augroup PluginEasyTags + autocmd! + " This is the alternative way of registering the global tags file using + " the automatic command event "VimEnter". Apparently this makes the + " plug-in behave better when used together with tplugin? + autocmd VimEnter * call xolox#easytags#register(1) + " Define the automatic commands to perform updating/highlighting. + for s:eventname in g:easytags_events + execute 'autocmd' s:eventname '* call xolox#easytags#autoload(' string(s:eventname) ')' + endfor + " Define an automatic command to register file type specific tags files? + if !empty(g:easytags_by_filetype) + autocmd FileType * call xolox#easytags#register(0) + endif + " After reloading a buffer the dynamic syntax highlighting is lost. The + " following code makes sure the highlighting is refreshed afterwards. + autocmd BufReadPost * unlet! b:easytags_last_highlighted +augroup END + +" }}}1 + +" Make sure the plug-in is only loaded once. +let g:loaded_easytags = 1 + +" vim: ts=2 sw=2 et |