From 7e8533fceefb4358444997bf3deda8c1812069c7 Mon Sep 17 00:00:00 2001 From: Peter Odding Date: Mon, 9 Aug 2010 20:40:42 +0200 Subject: Automatic/optional integration with shell.vim I developed (parts of) my shell.vim plug-in after noticing the annoying command prompt windows that pop up temporarily on Windows when the easytags plug-in runs ctags. Because the shell.vim plug-in was a proof of concept I hadn't published any integration between the two plug-ins. Since then I've had several requests for this so here it is :-) --- README.md | 78 +++++++++++++++++++++++++----------------------------------- autoload.vim | 58 ++++++++++++++++++++++++++++---------------- easytags.vim | 13 +++++++++- 3 files changed, 82 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index f8c2f27..14f1fd2 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ # Automated tag generation and syntax highlighting in Vim -[Vim] [vim] 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] [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-\]][jump_to_tag] mapping. +[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. -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_support] (!) and Exuberant Ctags can generate tags for [over 40 file types] [ctags_support] as well... +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... -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! +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] [latest_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! +Unzip the most recent [ZIP archive](http://peterodding.com/code/vim/downloads/easytags) 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 or Vim source file you should also notice that the function and type names defined in the file have been syntax highlighted. @@ -18,6 +18,24 @@ Note that if the plug-in warns you `ctags` isn't installed you'll have to downlo $ 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). + +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#'tags')). + +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.: @@ -34,11 +52,11 @@ A leading `~` in the `g:easytags_file` variable is expanded to your current home ### 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][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: +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 (see my [shell.vim][shell] plug-in) so stay tuned! +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]. @@ -52,24 +70,10 @@ Note: Like the `g:easytags_always_enabled` option, if you change this option it ### The `g:easytags_resolve_links` option -UNIX has [symbolic links] [symlinks] and [hard links] [hardlinks], 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: +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 `: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). - -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#'tags')). - -Note that this command will be executed automatically every once in a while, assuming you haven't changed `g:easytags_on_cursorhold`. - ## Troubleshooting ### The plug-in complains that Exuberant Ctags isn't installed @@ -92,7 +96,7 @@ If this doesn't print the location where you installed Exuberant Ctags it means ### 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][control_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): +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 @@ -100,13 +104,13 @@ If Vim seems very slow and you suspect this plug-in might be the one to blame, i :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][messages] command. +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] [E339] and unfortunately the only way to avoid this problem once it occurs is to reduce the number of tagged identifiers... +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] [tags_option] as follows: +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#'tags') as follows: :set tags=./.tags;,~/.vimtags @@ -114,32 +118,14 @@ Once you've executed the above command, Vim will automatically look for a file n ## Contact -If you have questions, bug reports, suggestions, etc. the author can be contacted at . The latest version is available at and . If you like this plug-in please vote for it on [www.vim.org] [vim_scripts_entry]. +If you have questions, bug reports, suggestions, etc. the author can be contacted at . The latest version is available at and . If you like this plug-in please vote for it on [www.vim.org](http://www.vim.org/scripts/script.php?script_id=3114). ## License -This software is licensed under the [MIT license] [mit_license]. +This software is licensed under the [MIT license](http://en.wikipedia.org/wiki/MIT_License). © 2010 Peter Odding <>. -[canon]: http://en.wikipedia.org/wiki/Canonicalization -[control_c]: http://vimdoc.sourceforge.net/htmldoc/pattern.html#CTRL-C -[ctags]: http://en.wikipedia.org/wiki/Ctags -[ctags_support]: http://ctags.sourceforge.net/languages.html -[cursorhold]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#CursorHold -[E339]: http://vimdoc.sourceforge.net/htmldoc/message.html#E339 [exuberant_ctags]: http://ctags.sourceforge.net/ -[hardlinks]: http://en.wikipedia.org/wiki/Hard_link -[ide]: http://en.wikipedia.org/wiki/Integrated_development_environment -[jump_to_tag]: http://vimdoc.sourceforge.net/htmldoc/tagsrch.html#CTRL-] -[latest_zip]: http://peterodding.com/code/vim/downloads/easytags -[messages]: http://vimdoc.sourceforge.net/htmldoc/message.html#:messages -[mit_license]: http://en.wikipedia.org/wiki/MIT_License -[shell]: http://peterodding.com/code/vim/shell/ -[symlinks]: http://en.wikipedia.org/wiki/Symbolic_link -[system]: http://vimdoc.sourceforge.net/htmldoc/eval.html#system() -[tags_option]: http://vimdoc.sourceforge.net/htmldoc/options.html#'tags' -[vim]: http://www.vim.org/ -[vim_scripts_entry]: http://www.vim.org/scripts/script.php?script_id=3114 -[vim_support]: http://ftp.vim.org/vim/runtime/syntax/ +[system]: http://vimdoc.sourceforge.net/htmldoc/eval.html#system%28%29 [vimrc]: http://vimdoc.sourceforge.net/htmldoc/starting.html#vimrc diff --git a/autoload.vim b/autoload.vim index 35fee2c..7263457 100644 --- a/autoload.vim +++ b/autoload.vim @@ -106,13 +106,19 @@ function! s:prep_cmdline(cfile, tagsfile, firstrun, arguments) " {{{3 endfunction function! s:run_ctags(starttime, cfile, tagsfile, firstrun, cmdline) " {{{3 - let output = '' + let output = [] if a:cmdline != '' - let output = system(a:cmdline) - if v:shell_error - let msg = "Failed to update tags file %s: %s!" - throw printf(msg, fnamemodify(a:tagsfile, ':~'), strtrans(output)) - elseif a:firstrun + 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 easytags#add_tagged_file(a:cfile) call xolox#timer#stop("%s: Created tags for %s in %s.", s:script, expand('%:p:~'), a:starttime) @@ -129,8 +135,7 @@ function! s:filter_merge_tags(filter_tags, tagsfile, output) " {{{3 call s:set_tagged_files(entries) let filters = [] let s:cached_filenames = {} - let new_entries = split(a:output, "\n") - let tagged_files = s:find_tagged_files(new_entries) + 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 @@ -144,7 +149,7 @@ function! s:filter_merge_tags(filter_tags, tagsfile, output) " {{{3 unlet s:cached_filenames let num_filtered = num_old_entries - len(entries) call map(entries, 'join(v:val, "\t")') - call extend(entries, new_entries) + call extend(entries, a:output) if !easytags#write_tagsfile(a:tagsfile, headers, entries) let msg = "Failed to write filtered tags file %s!" throw printf(msg, fnamemodify(a:tagsfile, ':~')) @@ -173,7 +178,7 @@ endfunction function! easytags#highlight() " {{{2 try if exists('g:syntax_on') && has_key(s:tagkinds, &ft) && !exists('b:easytags_nohl') - let start = xolox#timer#start() + let starttime = xolox#timer#start() if !has_key(s:aliases, &ft) let taglist = filter(taglist('.'), "get(v:val, 'language', '') ==? &ft") else @@ -207,7 +212,7 @@ function! easytags#highlight() " {{{2 let bufname = 'unnamed buffer #' . bufnr('%') endif let msg = "%s: Highlighted tags in %s in %s." - call xolox#timer#stop(msg, s:script, bufname, start) + call xolox#timer#stop(msg, s:script, bufname, starttime) return 1 endif catch @@ -219,20 +224,33 @@ endfunction function! easytags#supported_filetypes() " {{{2 if !exists('s:supported_filetypes') - let start = xolox#timer#start() - let listing = system(g:easytags_cmd . ' --list-languages') - if v:shell_error - let msg = "Failed to get supported languages! (output: %s)" - throw printf(msg, strtrans(listing)) - endif - let s:supported_filetypes = split(listing, '\n') - call map(s:supported_filetypes, 'easytags#to_vim_ft(v:val)') + let starttime = xolox#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#timer#stop(msg, s:script, len(s:supported_filetypes), start) + call xolox#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 easytags#to_vim_ft(a:cline) +endfunction + function! 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 diff --git a/easytags.vim b/easytags.vim index 22845fb..79f56e9 100644 --- a/easytags.vim +++ b/easytags.vim @@ -64,7 +64,18 @@ function! s:CheckCtags(name, version) " This function makes sure it is because the easytags plug-in requires the " --list-languages option. if executable(a:name) - let listing = system(a:name . ' --version') + 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\+\)*' let g:easytags_ctags_version = matchstr(listing, pattern) return s:VersionToNumber(g:easytags_ctags_version) >= a:version -- cgit v1.2.3