Updated miscellaneous scripts

Author: xolox

autoload/xolox/misc/buffer.vim

@@ -1,15 +1,44 @@
-" Vim auto-load script
+" Handling of special buffers
+"
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: April 18, 2013
+" Last Change: May 19, 2013
 " URL: http://peterodding.com/code/vim/misc/
+"
+" The functions defined here make it easier to deal with special Vim buffers
+" that contain text generated by a Vim plug-in. For example my [vim-notes
+" plug-in] [vim-notes] generates several such buffers:
+"
+" - [:RecentNotes] [RecentNotes] lists recently modified notes
+" - [:ShowTaggedNotes] [ShowTaggedNotes] lists notes grouped by tags
+" - etc.
+"
+" Because the text in these buffers is generated, Vim shouldn't bother with
+" swap files and it should never prompt the user whether to save changes to
+" the generated text.
+"
+" [vim-notes]: http://peterodding.com/code/vim/notes/
+" [RecentNotes]: http://peterodding.com/code/vim/notes/#recentnotes_command
+" [ShowTaggedNotes]: http://peterodding.com/code/vim/notes/#showtaggednotes_command
 
 function! xolox#misc#buffer#is_empty() " {{{1
-  " Check if the current buffer is an empty, unchanged buffer which can be reused.
+  " Checks if the current buffer is an empty, unchanged buffer which can be
+  " reused. Returns 1 if an empty buffer is found, 0 otherwise.
   return !&modified && expand('%') == '' && line('$') <= 1 && getline(1) == ''
 endfunction
 
 function! xolox#misc#buffer#prepare(...) " {{{1
-  " Open a special buffer (with generated contents, not directly edited by the user).
+  " Open a special buffer, i.e. a buffer that will hold generated contents,
+  " not directly edited by the user. The buffer can be customized by passing a
+  " dictionary with the following key/value pairs as the first argument:
+  "
+  " - **name** (required): The base name of the buffer (i.e. the base name of
+  "   the file loaded in the buffer, even though it isn't really a file and
+  "   nothing is really 'loaded' :-)
+  " - **path** (required): The pathname of the buffer. May be relevant if
+  "   [:lcd] [lcd] or ['autochdir'] [acd] is being used.
+  "
+  " [lcd]: http://vimdoc.sourceforge.net/htmldoc/editing.html#:lcd
+  " [acd]: http://vimdoc.sourceforge.net/htmldoc/options.html#'autochdir'
   if a:0 == 1 && type(a:1) == type('')
     " Backwards compatibility with old interface.
     let options = {'name': a:1, 'path': a:1}
@@ -41,7 +70,7 @@ function! xolox#misc#buffer#prepare(...) " {{{1
 endfunction
 
 function! xolox#misc#buffer#lock() " {{{1
-  " Lock a special buffer so it can no longer be edited.
+  " Lock a special buffer so that its contents can no longer be edited.
   setlocal readonly nomodifiable nomodified
 endfunction
 

autoload/xolox/misc/compat.vim

@@ -1,22 +1,36 @@
-" Vim auto-load script
+" Compatibility checking.
+"
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: May 13, 2013
+" Last Change: May 20, 2013
 " URL: http://peterodding.com/code/vim/misc/
-
-" The following integer will be bumped whenever a change in the miscellaneous
+"
+" This Vim script defines a version number for the miscellaneous scripts. Each
+" of my plug-ins compares their expected version of the miscellaneous scripts
+" against the version number defined inside the miscellaneous scripts.
+"
+" The version number is incremented whenever a change in the miscellaneous
 " scripts breaks backwards compatibility. This enables my Vim plug-ins to fail
 " early when they detect an incompatible version, instead of breaking at the
 " worst possible moments :-).
-let g:xolox#misc#compat#version = 3
+let g:xolox#misc#compat#version = 7
 
 " Remember the directory where the miscellaneous scripts are loaded from
 " so the user knows which plug-in to update if incompatibilities arise.
-let s:misc_directory = fnamemodify(expand('<sfile>'), ':p:h')
+let s:misc_directory = fnamemodify(expand('<sfile>'), ':~:h')
 
-function! xolox#misc#compat#check(plugin_name, required_version)
+function! xolox#misc#compat#check(plugin_name, plugin_version, required_version)
+  " Expects three arguments:
+  "
+  " 1. The name of the Vim plug-in that is using the miscellaneous scripts
+  " 2. The version of the Vim plug-in that is using the miscellaneous scripts
+  " 3. The version of the miscellaneous scripts expected by the plug-in
+  "
+  " When the loaded version of the miscellaneous scripts is different from the
+  " version expected by the plug-in, this function will raise an error message
+  " that explains what went wrong.
   if a:required_version != g:xolox#misc#compat#version
-    let msg = "The %s plug-in requires version %i of the miscellaneous scripts, however version %i was loaded from %s!"
-    throw printf(msg, a:plugin_name, a:required_version, g:xolox#misc#compat#version, s:misc_directory)
+    let msg = "The %s %s plug-in expects version %i of the miscellaneous scripts, however version %i was loaded from the directory %s! Please upgrade your plug-ins to the latest releases to resolve this problem."
+    throw printf(msg, a:plugin_name, a:plugin_version, a:required_version, g:xolox#misc#compat#version, s:misc_directory)
   endif
 endfunction
 

autoload/xolox/misc/complete.vim

@@ -1,11 +1,15 @@
-" Vim auto-load script
+" Tab completion for user defined commands.
+"
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: March 15, 2011
+" Last Change: May 19, 2013
 " URL: http://peterodding.com/code/vim/misc/
 
-" Keyword completion from the current buffer for user defined commands.
-
 function! xolox#misc#complete#keywords(arglead, cmdline, cursorpos)
+  " This function can be used to perform keyword completion for user defined
+  " Vim commands based on the contents of the current buffer. Here's an
+  " example of how you would use it:
+  "
+  "     :command -nargs=* -complete=customlist,xolox#misc#complete#keywords MyCmd call s:MyCmd(<f-args>)
   let words = {}
   for line in getline(1, '$')
     for word in split(line, '\W\+')

autoload/xolox/misc/escape.vim

@@ -1,35 +1,45 @@
-" Vim auto-load script
+" String escaping functions.
+"
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: November 21, 2011
+" Last Change: May 19, 2013
 " URL: http://peterodding.com/code/vim/misc/
 
-" Convert a string into a :substitute pattern that matches the string literally.
-
-function! xolox#misc#escape#pattern(string)
+function! xolox#misc#escape#pattern(string) " {{{1
+  " Takes a single string argument and converts it into a [:substitute]
+  " [subcmd] / [substitute()] [subfun] pattern string that matches the given
+  " string literally.
+  "
+  " [subfun]: http://vimdoc.sourceforge.net/htmldoc/eval.html#substitute()
+  " [subcmd]: http://vimdoc.sourceforge.net/htmldoc/change.html#:substitute
   if type(a:string) == type('')
     let string = escape(a:string, '^$.*\~[]')
     return substitute(string, '\n', '\\n', 'g')
   endif
   return ''
 endfunction
 
-" Convert a string into a :substitute replacement that inserts the string literally.
-
-function! xolox#misc#escape#substitute(string)
+function! xolox#misc#escape#substitute(string) " {{{1
+  " Takes a single string argument and converts it into a [:substitute]
+  " [subcmd] / [substitute()] [subfun] replacement string that inserts the
+  " given string literally.
   if type(a:string) == type('')
     let string = escape(a:string, '\&~%')
     return substitute(string, '\n', '\\r', 'g')
   endif
   return ''
 endfunction
 
-" Convert a string into a quoted command line argument. I was going to add a
-" long rant here about &shellslash, but really, it won't make any difference.
-" Let's just suffice to say that I have yet to encounter a single person out
-" there who uses this option for its intended purpose (running a UNIX-style
-" shell on Windows).
-
-function! xolox#misc#escape#shell(string)
+function! xolox#misc#escape#shell(string) " {{{1
+  " Takes a single string argument and converts it into a quoted command line
+  " argument.
+  "
+  " I was going to add a long rant here about Vim's ['shellslash' option]
+  " [shellslash], but really, it won't make any difference. Let's just suffice
+  " to say that I have yet to encounter a single person out there who uses
+  " this option for its intended purpose (running a UNIX style shell on
+  " Microsoft Windows).
+  "
+  " [shellslash]: http://vimdoc.sourceforge.net/htmldoc/options.html#'shellslash'
   if xolox#misc#os#is_win()
     try
       let ssl_save = &shellslash

autoload/xolox/misc/list.vim

@@ -1,19 +1,27 @@
-" Vim auto-load script
+" List handling functions.
+"
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: August 31, 2011
+" Last Change: May 19, 2013
 " URL: http://peterodding.com/code/vim/misc/
 
-" Remove duplicate values from {list} in-place (preserves order).
-
-function! xolox#misc#list#unique(list)
+function! xolox#misc#list#unique(list) " {{{1
+  " Remove duplicate values from the given list in-place (preserves order).
   call reverse(a:list)
   call filter(a:list, 'count(a:list, v:val) == 1')
   return reverse(a:list)
 endfunction
 
-" Binary insertion (more efficient than calling sort() after each insertion).
-
-function! xolox#misc#list#binsert(list, value, ...)
+function! xolox#misc#list#binsert(list, value, ...) " {{{1
+  " Performs in-place binary insertion, which depending on your use case can
+  " be more efficient than calling Vim's [sort()] [sort] function after each
+  " insertion (in cases where a single, final sort is not an option). Expects
+  " three arguments:
+  "
+  " 1. A list
+  " 2. A value to insert
+  " 3. 1 (true) when case should be ignored, 0 (false) otherwise
+  "
+  " [sort]: http://vimdoc.sourceforge.net/htmldoc/eval.html#sort()
   let idx = s:binsert_r(a:list, 0, len(a:list), a:value, exists('a:1') && a:1)
   return insert(a:list, a:value, idx)
 endfunction

autoload/xolox/misc/msg.vim

@@ -1,6 +1,7 @@
-" Vim auto-load script
+" Functions to interact with the user.
+"
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: March 15, 2011
+" Last Change: May 19, 2013
 " URL: http://peterodding.com/code/vim/misc/
 
 if !exists('g:xolox_message_buffer')
@@ -12,29 +13,34 @@ if !exists('g:xolox_messages')
   let g:xolox_messages = []
 endif
 
-" Show a formatted informational message to the user.
-
-function! xolox#misc#msg#info(...)
+function! xolox#misc#msg#info(...) " {{{1
+  " Show a formatted informational message to the user. This function has the
+  " same argument handling as Vim's [printf()] [printf] function.
+  "
+  " [printf]: http://vimdoc.sourceforge.net/htmldoc/eval.html#printf()
   call s:show_message('title', a:000)
 endfunction
 
-" Show a formatted warning message to the user.
-
-function! xolox#misc#msg#warn(...)
+function! xolox#misc#msg#warn(...) " {{{1
+  " Show a formatted warning message to the user. This function has the same
+  " argument handling as Vim's [printf()] [printf] function.
   call s:show_message('warningmsg', a:000)
 endfunction
 
-" Show a formatted debugging message to the user?
-
-function! xolox#misc#msg#debug(...)
+function! xolox#misc#msg#debug(...) " {{{1
+  " Show a formatted debugging message to the user, if the user has enabled
+  " increased verbosity by setting Vim's ['verbose'] [verbose] option to one
+  " (1) or higher. This function has the same argument handling as Vim's
+  " [printf()] [printf] function.
+  "
+  " [verbose]: http://vimdoc.sourceforge.net/htmldoc/options.html#'verbose'
   if &vbs >= 1
     call s:show_message('question', a:000)
   endif
 endfunction
 
-" The implementation of info() and warn().
-
-function! s:show_message(hlgroup, args)
+function! s:show_message(hlgroup, args) " {{{1
+  " The implementation of info() and warn().
   let nargs = len(a:args)
   if nargs == 1
     let message = a:args[0]
@@ -56,7 +62,10 @@ function! s:show_message(hlgroup, args)
       augroup END
       execute 'echohl' a:hlgroup
       " Redraw to avoid |hit-enter| prompt.
-      redraw | echomsg message
+      redraw
+      for line in split(message, "\n")
+        echomsg line
+      endfor
       if g:xolox_message_buffer > 0
         call add(g:xolox_messages, message)
         if len(g:xolox_messages) > g:xolox_message_buffer
@@ -70,7 +79,8 @@ function! s:show_message(hlgroup, args)
   endif
 endfunction
 
-function! s:clear_message()
+function! s:clear_message() " {{{1
+  " Callback to clear message after some time has passed.
   echo ''
   let &more = s:more_save
   let &showmode = s:smd_save

autoload/xolox/misc/open.vim

@@ -1,6 +1,7 @@
-" Vim auto-load script
+" Integration between Vim and its environment.
+"
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: November 21, 2011
+" Last Change: May 19, 2013
 " URL: http://peterodding.com/code/vim/misc/
 
 if !exists('s:version')
@@ -9,7 +10,20 @@ if !exists('s:version')
   let s:handlers = ['gnome-open', 'kde-open', 'exo-open', 'xdg-open']
 endif
 
-function! xolox#misc#open#file(path, ...)
+function! xolox#misc#open#file(path, ...) " {{{1
+  " Given a pathname as the first argument, this opens the file with the
+  " program associated with the file type. So for example a text file might
+  " open in Vim, an `*.html` file would probably open in your web browser and
+  " a media file would open in a media player.
+  "
+  " This should work on Windows, Mac OS X and most Linux distributions. If
+  " this fails to find a file association, you can pass one or more external
+  " commands to try as additional arguments. For example:
+  "
+  "     :call xolox#misc#open#file('/path/to/my/file', 'firefox', 'google-chrome')
+  "
+  " This generally shouldn't be necessary but it might come in handy now and
+  " then.
   if xolox#misc#os#is_win()
     try
       call xolox#shell#open_with_windows_shell(a:path)
@@ -35,7 +49,15 @@ function! xolox#misc#open#file(path, ...)
   throw printf(s:enoimpl, s:script, 'xolox#misc#open#file')
 endfunction
 
-function! xolox#misc#open#url(url)
+function! xolox#misc#open#url(url) " {{{1
+  " Given a URL as the first argument, this opens the URL in your preferred or
+  " best available web browser:
+  "
+  " - In GUI environments a graphical web browser will open (or a new tab will
+  "   be created in an existing window)
+  " - In console Vim without a GUI environment, when you have any of `lynx`,
+  "   `links` or `w3m` installed it will launch a command line web browser in
+  "   front of Vim (temporarily suspending Vim)
   let url = a:url
   if url !~ '^\w\+://'
     if url !~ '@'
@@ -56,7 +78,7 @@ function! xolox#misc#open#url(url)
   call xolox#misc#open#file(url, 'firefox', 'google-chrome')
 endfunction
 
-function! s:handle_error(cmd, output)
+function! s:handle_error(cmd, output) " {{{1
   if v:shell_error
     let message = "open.vim %s: Failed to execute program! (command line: %s%s)"
     let output = strtrans(xolox#misc#str#trim(a:output))