diff options
| -rw-r--r-- | INSTALL.md | 3 | ||||
| -rw-r--r-- | README.md | 209 | ||||
| -rw-r--r-- | TODO.md | 26 | ||||
| -rw-r--r-- | autoload/xolox/easytags.vim | 658 | ||||
| -rw-r--r-- | autoload/xolox/misc/README.md | 13 | ||||
| -rw-r--r-- | autoload/xolox/misc/complete.vim (renamed from complete.vim) | 0 | ||||
| -rw-r--r-- | autoload/xolox/misc/escape.vim (renamed from escape.vim) | 0 | ||||
| -rw-r--r-- | autoload/xolox/misc/list.vim (renamed from list.vim) | 0 | ||||
| -rw-r--r-- | autoload/xolox/misc/msg.vim (renamed from msg.vim) | 0 | ||||
| -rw-r--r-- | autoload/xolox/misc/option.vim (renamed from option.vim) | 0 | ||||
| -rw-r--r-- | autoload/xolox/misc/os.vim (renamed from os.vim) | 0 | ||||
| -rw-r--r-- | autoload/xolox/misc/path.vim (renamed from path.vim) | 0 | ||||
| -rw-r--r-- | autoload/xolox/misc/str.vim (renamed from str.vim) | 0 | ||||
| -rw-r--r-- | autoload/xolox/misc/timer.vim (renamed from timer.vim) | 0 | ||||
| -rw-r--r-- | doc/easytags.txt | 416 | ||||
| -rwxr-xr-x | normalize-tags.py | 62 | ||||
| -rw-r--r-- | plugin/easytags.vim | 202 | ||||
| -rwxr-xr-x | why-so-slow.py | 39 |
18 files changed, 1618 insertions, 10 deletions
diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..e61b168 --- /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) 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) and want to keep the plug-in up to date using git, you can use the GitHub repository directly, just make sure to use `git clone --recursive` when you clone the repository so that the submodule with autoload scripts is included (the plug-in will give you a hint if you forget this). @@ -1,13 +1,202 @@ -# Miscellaneous auto-load Vim scripts +# Automated tag generation and syntax highlighting in Vim -The git repository at <http://github.com/xolox/vim-misc> 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. I'm hoping to include this repository as a -git submodule in my other repositories so that I only have to maintain these -files in one place. +[Vim](http://www.vim.org/) has long been my favorite text editor and combined with [Exuberant Ctags] [exuberant_ctags] it has the potential to provide most of what I expect from an [integrated development environment](http://en.wikipedia.org/wiki/Integrated_development_environment). Exuberant Ctags is the latest incarnation of a [family of computer programs](http://en.wikipedia.org/wiki/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-]](http://vimdoc.sourceforge.net/htmldoc/tagsrch.html#CTRL-]) mapping. -For lack of a better place: I hereby release these scripts under the MIT -license, in other words feel free to do with them as you please but don't -misrepresent this work as your own. +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](http://ftp.vim.org/vim/runtime/syntax/) (!) and Exuberant Ctags can generate tags for [over 40 file types](http://ctags.sourceforge.net/languages.html) as well... -[plugins]: http://peterodding.com/code/vim/ +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! + +## Install & usage + +Unzip the most recent [ZIP archive](http://peterodding.com/code/vim/downloads/easytags.zip) 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 a C, C++, Objective-C, Java, Lua, Python, PHP, Ruby 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] [exuberant_ctags], or if you're running Debian/Ubuntu you can install it by executing the following shell command: + + $ sudo apt-get install exuberant-ctags + +### If you're using Windows + +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](http://peterodding.com/code/vim/shell/) plug-in which includes a [DLL](http://en.wikipedia.org/wiki/Dynamic-link_library) 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 `:UpdateTags` command + +This command executes [Exuberant Ctags] [exuberant_ctags] 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](http://vimdoc.sourceforge.net/htmldoc/options.html#%27tags%27)). + +Note that this command will be executed automatically every once in a while, assuming you haven't changed `g:easytags_on_cursorhold`. + +### 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.vim` 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' + +### 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. If you use the following setting to enable project specific tags files: + + :set tags=./tags; + +You can enable this option so that the project specific tags files are written instead of the global tags file: + + :let g:easytags_dynamic_files = 1 + +When you enable this option, the easytags plug-in will use the first filename returned by [tagfiles()](http://vimdoc.sourceforge.net/htmldoc/eval.html#tagfiles%28%29) as the tags file to write. Note that `tagfiles()` is reevaluated every time the plug-in runs. + +### 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](http://vimdoc.sourceforge.net/htmldoc/autocmd.html#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][vimrc]. + +### 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][vimrc]. + +### 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 Cags 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][vimrc] (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](http://vimdoc.sourceforge.net/htmldoc/syntax.html#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](http://en.wikipedia.org/wiki/Symbolic_link) and [hard links](http://en.wikipedia.org/wiki/Hard_link), 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](http://en.wikipedia.org/wiki/Canonicalization). 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 + +### 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: + + * **Lua:** `luaFuncTag` + * **C:** `cTypeTag`, `cEnumTag`, `cPreProcTag`, `cFunctionTag`, `cMemberTag` + * **PHP:** `phpFunctionsTag`, `phpClassesTag` + * **Vim:** `vimAutoGroupTag`, `vimCommandTag`, `vimFuncNameTag`, `vimScriptFuncNameTag` + * **Python:** `pythonFunctionTag`, `pythonMethodTag`, `pythonClassTag` + * **Java:** `javaClassTag`, `javaMethodTag` + * **C#:** `csClassOrStructTag`, `csMethodTag` + * **Ruby:** `rubyModuleNameTag`, `rubyClassNameTag`, `rubyMethodNameTag` + +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). + +## 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](http://vimdoc.sourceforge.net/htmldoc/pattern.html#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](http://vimdoc.sourceforge.net/htmldoc/message.html#: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](http://vimdoc.sourceforge.net/htmldoc/message.html#E339) 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](http://vimdoc.sourceforge.net/htmldoc/options.html#%27tags%27) 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](http://en.wikipedia.org/wiki/Cygwin) + +If you want to use the plug-in with Vim under 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/easytags/> and <http://github.com/xolox/vim-easytags>. If you like this plug-in please vote for it on [Vim Online](http://www.vim.org/scripts/script.php?script_id=3114). + +## License + +This software is licensed under the [MIT license](http://en.wikipedia.org/wiki/MIT_License). +© 2010 Peter Odding <<peter@peterodding.com>>. + + +[exuberant_ctags]: http://ctags.sourceforge.net/ +[system]: http://vimdoc.sourceforge.net/htmldoc/eval.html#system%28%29 +[vimrc]: http://vimdoc.sourceforge.net/htmldoc/starting.html#vimrc @@ -0,0 +1,26 @@ +# Long term plans for the easytags Vim plug-in + + * 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? + + * Use separate tags files for each language stored in ~/.vim/tags/ to increase performance because a single, global tags file quickly grows to a megabyte? + + * 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)? + + * 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..4928ef5 --- /dev/null +++ b/autoload/xolox/easytags.vim @@ -0,0 +1,658 @@ +" Vim script +" Author: Peter Odding <peter@peterodding.com> +" Last Change: May 23, 2011 +" URL: http://peterodding.com/code/vim/easytags/ + +let s:script = expand('<sfile>:p:~') + +" Public interface through (automatic) commands. {{{1 + +function! xolox#easytags#autoload() " {{{2 + try + " Update the entries for the current file in the global tags file? + 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 + " Apply highlighting of tags in global tags file to current buffer? + if &eventignore !~? '\<syntax\>' + 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 + catch + call xolox#misc#msg#warn("%s: %s (at %s)", s:script, v:exception, v:throwpoint) + endtry +endfunction + +function! xolox#easytags#update(silent, filter_tags, filenames) " {{{2 + try + let s:cached_filenames = {} + let starttime = xolox#misc#timer#start() + let cfile = s:check_cfile(a:silent, a:filter_tags, !empty(a:filenames)) + let tagsfile = xolox#easytags#get_tagsfile() + let firstrun = !filereadable(tagsfile) + let cmdline = s:prep_cmdline(cfile, tagsfile, firstrun, a:filenames) + let output = s:run_ctags(starttime, cfile, tagsfile, firstrun, cmdline) + if !firstrun + let num_filtered = s:filter_merge_tags(a:filter_tags, tagsfile, output) + if cfile != '' + let msg = "%s: Updated tags for %s in %s." + call xolox#misc#timer#stop(msg, s:script, expand('%:p:~'), starttime) + elseif a:0 > 0 + let msg = "%s: Updated tags in %s." + call xolox#misc#timer#stop(msg, s:script, starttime) + else + let msg = "%s: Filtered %i invalid tags in %s." + call xolox#misc#timer#stop(msg, s:script, num_filtered, starttime) + endif + endif + return 1 + catch + call xolox#misc#msg#warn("%s: %s (at %s)", s:script, v:exception, v:throwpoint) + finally + unlet s:cached_filenames + 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 g:easytags_autorecurse + 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 index(xolox#easytags#supported_filetypes(), &ft) == -1 + 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) " {{{3 + let cmdline = [g:easytags_cmd, '--fields=+l', '--c-kinds=+p', '--c++-kinds=+p'] + if a:firstrun + call add(cmdline, shellescape('-f' . a:tagsfile)) + call add(cmdline, '--sort=' . (&ic ? 'foldcase' : 'yes')) + else + call add(cmdline, '--sort=no') + call add(cmdline, '-f-') + endif + if g:easytags_include_members + call add(cmdline, '--extra=+q') + endif + let have_args = 0 + if a:cfile != '' + if g:easytags_autorecurse + call add(cmdline, '-R') + call add(cmdline, shellescape(a:cfile)) + else + let filetype = xolox#easytags#to_ctags_ft(&filetype) + call add(cmdline, shellescape('--language-force=' . filetype)) + call add(cmdline, shellescape(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, 'shellescape(s:canonicalize(v:val))') + 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 output = [] + if a:cmdline != '' + call xolox#misc#msg#debug("%s: Executing %s", s:script, a:cmdline) + try + let output = xolox#shell#execute(a:cmdline, 1) + catch /^Vim\%((\a\+)\)\=:E117/ + " Ignore missing shell.vim plug-in. + let output = split(system(a:cmdline), "\n") + if v:shell_error + let msg = "Failed to update tags file %s: %s!" + throw printf(msg, fnamemodify(a:tagsfile, ':~'), strtrans(join(output, "\n"))) + endif + endtry + if a:firstrun + if a:cfile != '' + call xolox#easytags#add_tagged_file(a:cfile) + call xolox#misc#timer#stop("%s: Created tags for %s in %s.", s:script, expand('%:p:~'), a:starttime) + else + call xolox#misc#timer#stop("%s: Created tags in %s.", s:script, a:starttime) + endif + endif + endif + return output +endfunction + +function! s:filter_merge_tags(filter_tags, tagsfile, output) " {{{3 + let [headers, entries] = xolox#easytags#read_tagsfile(a:tagsfile) + call s:set_tagged_files(entries) + let filters = [] + let tagged_files = s:find_tagged_files(a:output) + if !empty(tagged_files) + call add(filters, '!has_key(tagged_files, s:canonicalize(get(v:val, 1)))') + endif + if a:filter_tags + call add(filters, 'filereadable(get(v:val, 1))') + endif + let num_old_entries = len(entries) + if !empty(filters) + call filter(entries, join(filters, ' && ')) + endif + let num_filtered = num_old_entries - len(entries) + call map(entries, 'join(v:val, "\t")') + call extend(entries, a:output) + 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(new_entries) " {{{3 + let tagged_files = {} + for line in a:new_entries + " Never corrupt the tags file by merging an invalid line + " (probably an error message) with the existing tags! + if match(line, '^[^\t]\+\t[^\t]\+\t.\+$') == -1 + throw "Exuberant Ctags returned invalid data: " . strtrans(line) + endif + let filename = matchstr(line, '^[^\t]\+\t\zs[^\t]\+') + if !has_key(tagged_files, filename) + let filename = s:canonicalize(filename) + let tagged_files[filename] = 1 + call xolox#easytags#add_tagged_file(filename) + endif + endfor + return tagged_files +endfunction + +function! xolox#easytags#highlight() " {{{2 + 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() + 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 + for tagkind in tagkinds + let hlgroup_tagged = tagkind.hlgroup . 'Tag' + if hlexists(hlgroup_tagged) + execute 'syntax clear' hlgroup_tagged + else + execute 'highlight def link' hlgroup_tagged tagkind.hlgroup + endif + let matches = filter(copy(taglist), tagkind.filter) + if matches != [] + call map(matches, 'xolox#misc#escape#pattern(get(v:val, "name"))') + let pattern = tagkind.pattern_prefix . '\%(' . join(xolox#misc#list#unique(matches), '\|') . '\)' . tagkind.pattern_suffix + let template = 'syntax match %s /%s/ containedin=ALLBUT,.*String.*,.*Comment.*,cIncluded' + let command = printf(template, hlgroup_tagged, escape(pattern, '/')) + try + execute command + catch /^Vim\%((\a\+)\)\=:E339/ + let msg = "easytags.vim: Failed to highlight %i %s tags because pattern is too big! (%i KB)" + call xolox#misc#msg#warn(printf(msg, len(matches), tagkind.hlgroup, len(pattern) / 1024)) + endtry + endif + endfor + redraw + let bufname = expand('%:p:~') + if bufname == '' + let bufname = 'unnamed buffer #' . bufnr('%') + endif + let msg = "%s: Highlighted tags in %s in %s." + call xolox#misc#timer#stop(msg, s:script, bufname, starttime) + return 1 + endif + catch + call xolox#misc#msg#warn("%s: %s (at %s)", s:script, v:exception, v:throwpoint) + endtry +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 command = g:easytags_cmd . ' --list-languages' + try + let listing = xolox#shell#execute(command, 1) + catch /^Vim\%((\a\+)\)\=:E117/ + " Ignore missing shell.vim plug-in. + let listing = split(system(command), "\n") + if v:shell_error + let msg = "Failed to get supported languages! (output: %s)" + throw printf(msg, strtrans(join(listing, "\n"))) + endif + endtry + let s:supported_filetypes = map(copy(listing), 's:check_filetype(listing, v:val)') + let msg = "%s: Retrieved %i supported languages in %s." + call xolox#misc#timer#stop(msg, s:script, 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#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 pattern = '^\([^\t]\+\)\t\([^\t]\+\)\t\(.\+\)$' + for line in readfile(a:tagsfile) + if line =~# '^!_TAG_' + call add(headers, line) + else + call add(entries, matchlist(line, pattern)[1:3]) + endif + endfor + return [headers, entries] +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 + if sort_order == 1 + call sort(a:entries) + else + call sort(a:entries, 1) + 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 + return writefile(lines, a:tagsfile) == 0 +endfunction + +function! xolox#easytags#file_has_tags(filename) " {{{2 + call s:cache_tagged_files() + return has_key(s:tagged_files, s:resolve(a:filename)) +endfunction + +function! xolox#easytags#add_tagged_file(filename) " {{{2 + call s:cache_tagged_files() + let filename = s:resolve(a:filename) + let s:tagged_files[filename] = 1 +endfunction + +function! xolox#easytags#get_tagsfile() " {{{2 + if g:easytags_dynamic_files + let files = tagfiles() + if len(files) > 0 + return files[0] + endif + endif + let tagsfile = expand(g:easytags_file) + 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 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 + 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:resolve(filename) " {{{2 + if g:easytags_resolve_links + return resolve(a:filename) + else + return a:filename + endif +endfunction + +function! s:canonicalize(filename) " {{{2 + if has_key(s:cached_filenames, a:filename) + return s:cached_filenames[a:filename] + endif + let canonical = s:resolve(fnamemodify(a:filename, ':p')) + let s:cached_filenames[a:filename] = canonical + return canonical + endif +endfunction + +function! s:cache_tagged_files() " {{{2 + if !exists('s:tagged_files') + let tagsfile = xolox#easytags#get_tagsfile() + try + let [headers, entries] = xolox#easytags#read_tagsfile(tagsfile) + call s:set_tagged_files(entries) + catch /\<E484\>/ + " Ignore missing tags file. + call s:set_tagged_files([]) + endtry + endif +endfunction + +function! s:set_tagged_files(entries) " {{{2 + " TODO use taglist() instead of readfile() so that all tag files are + " automatically used :-) + let s:tagged_files = {} + for entry in a:entries + let filename = get(entry, 1, '') + if filename != '' + let s:tagged_files[s:resolve(filename)] = 1 + endif + endfor +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') + +" Enable line continuation. +let s:cpo_save = &cpo +set cpo&vim + +" Lua. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'lua', + \ 'hlgroup': 'luaFunc', + \ 'filter': 'get(v:val, "kind") ==# "f"'}) + +" C. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'c', + \ 'hlgroup': 'cType', + \ 'filter': 'get(v:val, "kind") =~# "[cgstu]"'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'c', + \ 'hlgroup': 'cEnum', + \ 'filter': 'get(v:val, "kind") ==# "e"'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'c', + \ 'hlgroup': 'cPreProc', + \ 'filter': 'get(v:val, "kind") ==# "d"'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'c', + \ 'hlgroup': 'cFunction', + \ 'filter': 'get(v:val, "kind") =~# "[fp]"'}) + +highlight def link cEnum Identifier +highlight def link cFunction Function + +if g:easytags_include_members + call xolox#easytags#define_tagkind({ + \ 'filetype': 'c', + \ 'hlgroup': 'cMember', + \ 'filter': 'get(v:val, "kind") ==# "m"'}) + highlight def link cMember Identifier +endif + +" PHP. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'php', + \ 'hlgroup': 'phpFunctions', + \ 'filter': 'get(v:val, "kind") ==# "f"', + \ 'pattern_suffix': '(\@='}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'php', + \ 'hlgroup': 'phpClasses', + \ 'filter': 'get(v:val, "kind") ==# "c"'}) + +" Vim script. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'vim', + \ 'hlgroup': 'vimAutoGroup', + \ 'filter': 'get(v:val, "kind") ==# "a"'}) + +highlight def link vimAutoGroup vimAutoEvent + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'vim', + \ 'hlgroup': 'vimCommand', + \ 'filter': 'get(v:val, "kind") ==# "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', + \ 'filter': 'get(v:val, "kind") ==# "f" && get(v:val, "cmd") !~? ''<sid>\w\|\<s:\w''', + \ 'pattern_prefix': '\C\%(\<s:\|<[sS][iI][dD]>\)\@<!\<'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'vim', + \ 'hlgroup': 'vimScriptFuncName', + \ 'filter': 'get(v:val, "kind") ==# "f" && get(v:val, "cmd") =~? ''<sid>\w\|\<s:\w''', + \ 'pattern_prefix': '\C\%(\<s:\|<[sS][iI][dD]>\)'}) + +highlight def link vimScriptFuncName vimFuncName + +" Python. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'python', + \ 'hlgroup': 'pythonFunction', + \ 'filter': 'get(v:val, "kind") ==# "f"', + \ 'pattern_prefix': '\%(\<def\s\+\)\@<!\<'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'python', + \ 'hlgroup': 'pythonMethod', + \ 'filter': 'get(v:val, "kind") ==# "m"', + \ 'pattern_prefix': '\.\@<='}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'python', + \ 'hlgroup': 'pythonClass', + \ 'filter': 'get(v:val, "kind") ==# "c"'}) + +highlight def link pythonMethodTag pythonFunction +highlight def link pythonClassTag pythonFunction + +" Java. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'java', + \ 'hlgroup': 'javaClass', + \ 'filter': 'get(v:val, "kind") ==# "c"'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'java', + \ 'hlgroup': 'javaMethod', + \ 'filter': 'get(v:val, "kind") ==# "m"'}) + +highlight def link javaClass Identifier +highlight def link javaMethod Function + +" C#. {{{2 + +" TODO C# name spaces? +" TODO C# interface names +" TODO C# enumeration member names +" TODO C# structure names? + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'cs', + \ 'hlgroup': 'csClassOrStruct', + \ 'filter': 'get(v:val, "kind") ==# "c"'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'cs', + \ 'hlgroup': 'csMethod', + \ 'filter': 'get(v:val, "kind") =~# "[ms]"'}) + +highlight def link csClassOrStruct Identifier +highlight def link csMethod Function + +" Ruby. {{{2 + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'ruby', + \ 'hlgroup': 'rubyModuleName', + \ 'filter': 'get(v:val, "kind") ==# "m"'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'ruby', + \ 'hlgroup': 'rubyClassName', + \ 'filter': 'get(v:val, "kind") ==# "c"'}) + +call xolox#easytags#define_tagkind({ + \ 'filetype': 'ruby', + \ 'hlgroup': 'rubyMethodName', + \ 'filter': 'get(v:val, "kind") =~# "[fF]"'}) + +highlight def link rubyModuleName Type +highlight def link rubyClassName Type +highlight def link rubyMethodName Function + +" }}} + +" Restore "cpoptions". +let &cpo = s:cpo_save +unlet s:cpo_save + +" vim: ts=2 sw=2 et diff --git a/autoload/xolox/misc/README.md b/autoload/xolox/misc/README.md new file mode 100644 index 0000000..d305ddd --- /dev/null +++ b/autoload/xolox/misc/README.md @@ -0,0 +1,13 @@ +# Miscellaneous auto-load Vim scripts + +The git repository at <http://github.com/xolox/vim-misc> 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. I'm hoping to include this repository as a +git submodule in my other repositories so that I only have to maintain these +files in one place. + +For lack of a better place: I hereby release these scripts under the MIT +license, in other words feel free to do with them as you please but don't +misrepresent this work as your own. + +[plugins]: http://peterodding.com/code/vim/ diff --git a/complete.vim b/autoload/xolox/misc/complete.vim index 2ada676..2ada676 100644 --- a/complete.vim +++ b/autoload/xolox/misc/complete.vim diff --git a/escape.vim b/autoload/xolox/misc/escape.vim index a698ae0..a698ae0 100644 --- a/escape.vim +++ b/autoload/xolox/misc/escape.vim diff --git a/list.vim b/autoload/xolox/misc/list.vim index 8857af1..8857af1 100644 --- a/list.vim +++ b/autoload/xolox/misc/list.vim diff --git a/msg.vim b/autoload/xolox/misc/msg.vim index 9ba2b7c..9ba2b7c 100644 --- a/msg.vim +++ b/autoload/xolox/misc/msg.vim diff --git a/option.vim b/autoload/xolox/misc/option.vim index f785e1b..f785e1b 100644 --- a/option.vim +++ b/autoload/xolox/misc/option.vim diff --git a/os.vim b/autoload/xolox/misc/os.vim index 0852e2d..0852e2d 100644 --- a/os.vim +++ b/autoload/xolox/misc/os.vim diff --git a/path.vim b/autoload/xolox/misc/path.vim index 2b4510f..2b4510f 100644 --- a/path.vim +++ b/autoload/xolox/misc/path.vim diff --git a/str.vim b/autoload/xolox/misc/str.vim index 19bfe09..19bfe09 100644 --- a/str.vim +++ b/autoload/xolox/misc/str.vim diff --git a/timer.vim b/autoload/xolox/misc/timer.vim index 151972d..151972d 100644 --- a/timer.vim +++ b/autoload/xolox/misc/timer.vim diff --git a/doc/easytags.txt b/doc/easytags.txt new file mode 100644 index 0000000..9ac777c --- /dev/null +++ b/doc/easytags.txt @@ -0,0 +1,416 @@ +*easytags.txt* Automated tag generation and syntax highlighting in Vim + +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-install-usage* +Install & usage ~ + +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 a C, C++, Objective-C, Java, Lua, +Python, PHP, Ruby 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-if-you-re-using-windows* +If you're using 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-:updatetags-command* +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'. + +------------------------------------------------------------------------------ + *easytags-:highlighttags-command* +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'. + +------------------------------------------------------------------------------ + *g:easytags_cmd-option* +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.vim' 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' + +------------------------------------------------------------------------------ + *g:easytags_file-option* +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). + +------------------------------------------------------------------------------ + *g:easytags_dynamic_files-option* +The 'g:easytags_dynamic_files' option ~ + +By default ':UpdateTags' only writes to the global tags file. If you use the +following setting to enable project specific tags files: +> + :set tags=./tags; + +You can enable this option so that the project specific tags files are written +instead of the global tags file: +> + :let g:easytags_dynamic_files = 1 + +When you enable this option, the easytags plug-in will use the first filename +returned by |tagfiles()| as the tags file to write. Note that 'tagfiles()' is +reevaluated every time the plug-in runs. + +------------------------------------------------------------------------------ + *g:easytags_always_enabled-option* +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. + +------------------------------------------------------------------------------ + *g:easytags_on_cursorhold-option* +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. + +------------------------------------------------------------------------------ + *g:easytags_autorecurse-option* +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 Cags 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. + +------------------------------------------------------------------------------ + *g:easytags_include_members-option* +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 + +------------------------------------------------------------------------------ + *g:easytags_resolve_links-option* +The 'g:easytags_resolve_links' option ~ + +UNIX has symbolic links [9] and hard links [10], 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 [11]. 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 + +------------------------------------------------------------------------------ + *g:easytags_suppress_ctags_warning-option* +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 + +------------------------------------------------------------------------------ +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: + + - Lua: 'luaFuncTag' + + - C: 'cTypeTag', 'cEnumTag', 'cPreProcTag', 'cFunctionTag', 'cMemberTag' + + - PHP: 'phpFunctionsTag', 'phpClassesTag' + + - Vim: 'vimAutoGroupTag', 'vimCommandTag', 'vimFuncNameTag', + 'vimScriptFuncNameTag' + + - Python: 'pythonFunctionTag', 'pythonMethodTag', 'pythonClassTag' + + - Java: 'javaClassTag', 'javaMethodTag' + + - C#: 'csClassOrStructTag', 'csMethodTag' + + - Ruby: 'rubyModuleNameTag', 'rubyClassNameTag', 'rubyMethodNameTag' + +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-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 [12] ~ + +If you want to use the plug-in with Vim under Cygwin, 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 [13]. + +============================================================================== + *easytags-license* +License ~ + +This software is licensed under the MIT license [14]. Copyright 2010 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] http://en.wikipedia.org/wiki/Symbolic_link +[10] http://en.wikipedia.org/wiki/Hard_link +[11] http://en.wikipedia.org/wiki/Canonicalization +[12] http://en.wikipedia.org/wiki/Cygwin +[13] http://www.vim.org/scripts/script.php?script_id=3114 +[14] http://en.wikipedia.org/wiki/MIT_License + +vim: ft=help diff --git a/normalize-tags.py b/normalize-tags.py new file mode 100755 index 0000000..6701c53 --- /dev/null +++ b/normalize-tags.py @@ -0,0 +1,62 @@ +#!/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: May 11, 2011 +URL: https://github.com/xolox/vim-easytags/blob/master/normalize-tags.py +''' + +import os, sys, time + +tagsfile = os.path.expanduser(len(sys.argv) > 1 and sys.argv[1] or '~/.vimtags') +tempname = '%s-new-%d' % (tagsfile, time.time()) +results, cache = {}, {} +infile = open(tagsfile) +outfile = open(tempname, 'w') +nprocessed = 0 +fold_case = False + +for line in infile: + nprocessed += 1 + 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 not os.path.exists(pathname): continue + cache[pathname] = os.path.realpath(pathname) + fields[1] = cache[pathname] + results['\t'.join(fields)] = True + +infile.close() + +lines = results.keys() +if fold_case: + lines.sort(key=str.lower) +else: + lines.sort() + +outfile.write('\n'.join(lines)) +outfile.write('\n') +outfile.close() + +backup = '%s-backup-%d' % (tagsfile, time.time()) +print "Making a backup of %s as %s" % (tagsfile, backup) +os.rename(tagsfile, backup) + +print "Replacing old", tagsfile, "with new one" +os.rename(tempname, tagsfile) + +nfiltered = nprocessed - len(lines) +print "Filtered %d out of %d entries" % (nfiltered, nprocessed) + +# vim: ts=2 sw=2 et diff --git a/plugin/easytags.vim b/plugin/easytags.vim new file mode 100644 index 0000000..cf6519b --- /dev/null +++ b/plugin/easytags.vim @@ -0,0 +1,202 @@ +" Vim plug-in +" Author: Peter Odding <peter@peterodding.com> +" Last Change: May 23, 2011 +" URL: http://peterodding.com/code/vim/easytags/ +" Requires: Exuberant Ctags (http://ctags.sf.net) +" License: MIT +" Version: 2.2.9 + +" Support for automatic update using the GLVS plug-in. +" GetLatestVimScripts: 3114 1 :AutoInstall: easytags.zip + +" Don't source the plug-in when its already been loaded or &compatible is set. +if &cp || exists('g:loaded_easytags') + finish +endif + +let s:script = expand('<sfile>:p:~') + +" Make sure the submodule with miscellaneous auto-load scripts is available. +try + call xolox#misc#os#is_win() +catch /^Vim\%((\a\+)\)\=:E117/ + let s:msg = "It looks like the easytags plug-in wasn't correctly installed, if you're using" + let s:msg .= " git you should probably use 'git clone --recursive ...' to clone the repository!" + echoerr s:msg + finish +endtry + +" 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_dynamic_files') + let g:easytags_dynamic_files = 0 +endif + +if !exists('g:easytags_resolve_links') + let g:easytags_resolve_links = 0 +endif + +if !exists('g:easytags_always_enabled') + let g:easytags_always_enabled = 0 +endif + +if !exists('g:easytags_on_cursorhold') + let g:easytags_on_cursorhold = 1 +endif + +if !exists('g:easytags_ignored_filetypes') + let g:easytags_ignored_filetypes = '^tex$' +endif + +if !exists('g:easytags_autorecurse') + let g:easytags_autorecurse = 0 +endif + +if !exists('g:easytags_include_members') + let g:easytags_include_members = 0 +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 + " On Ubuntu Linux, Exuberant Ctags is installed as `ctags'. On Debian Linux, + " Exuberant Ctags is installed as `exuberant-ctags'. On Free-BSD, Exuberant + " Ctags is installed as `exctags'. + for name in ['ctags', 'exuberant-ctags', 'exctags'] + if s:CheckCtags(name, a:version) + let g:easytags_cmd = name + return 1 + endif + endfor +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. + if executable(a:name) + let command = a:name . ' --version' + try + let listing = join(xolox#shell#execute(command, 1), '\n') + catch /^Vim\%((\a\+)\)\=:E117/ + " Ignore missing shell.vim plug-in. + let listing = system(command) + catch + " xolox#shell#execute() converts shell errors to exceptions and since + " we're checking whether one of several executables exists we don't want + " to throw an error when the first one doesn't! + return + endtry + let pattern = 'Exuberant Ctags \zs\(\d\+\(\.\d\+\)*\|Development\)' + let g:easytags_ctags_version = matchstr(listing, pattern) + if g:easytags_ctags_version == 'Development' + return 1 + else + return s:VersionToNumber(g:easytags_ctags_version) >= a:version + 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 = "%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, s:script) + else + let s:msg = "%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, s:script, g:easytags_ctags_version) + endif + unlet s:msg + finish +endif + +function! s:RegisterTagsFile() + " 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. + if index(expanded, resolve(expand(g:easytags_file))) == -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, g:easytags_file) + let value = xolox#misc#option#join_tags(tagfiles) + let cmd = 'set 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 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 s:RegisterTagsFile() + +" 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() + +" 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 s:RegisterTagsFile() + if g:easytags_always_enabled + " TODO Also on FocusGained because tags files might be updated externally? + autocmd BufReadPost,BufWritePost * call xolox#easytags#autoload() + endif + if g:easytags_on_cursorhold + autocmd CursorHold,CursorHoldI * call xolox#easytags#autoload() + autocmd BufReadPost * unlet! b:easytags_last_highlighted + endif +augroup END + +" }}}1 + +" Make sure the plug-in is only loaded once. +let g:loaded_easytags = 1 + +" vim: ts=2 sw=2 et diff --git a/why-so-slow.py b/why-so-slow.py new file mode 100755 index 0000000..ead62f2 --- /dev/null +++ b/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 |