Improve xolox#misc#os#find_vim() function

Now accepts a 'vim' or 'gvim' argument to allow callers to
indicate their preference independently from 'v:progname'.

README.md

@@ -38,7 +38,7 @@ from the source code of the miscellaneous scripts using the Python module
 <!-- Start of generated documentation -->
 
 The documentation of the 67 functions below was extracted from
-15 Vim scripts on June  3, 2013 at 21:23.
+15 Vim scripts on June  3, 2013 at 21:53.
 
 ### Handling of special buffers
 
@@ -286,14 +286,18 @@ Returns 1 (true) when on Microsoft Windows, 0 (false) otherwise.
 
 #### The `xolox#misc#os#find_vim()` function
 
-Returns the program name of Vim as a string. On Windows and UNIX this
-simply returns [v:progname] [progname] while on Mac OS X there is some
-special magic to find MacVim's executable even though it's usually not on
-the executable search path. If you want, you can override the value
-returned from this function by setting the global variable
+Returns the program name of Vim as a string. On Windows and UNIX this just
+[v:progname] [] as an absolute pathname while on Mac OS X there is
+some special magic to find MacVim's executable even though it's usually
+not on the executable search path. If you want, you can override the
+value returned from this function by setting the global variable
 `g:xolox#misc#os#vim_progname`.
 
-[progname]: http://vimdoc.sourceforge.net/htmldoc/eval.html#v:progname
+By default the choice of console Vim vs graphical Vim is made based on
+the value of [v:progname] [], but if you have a preference you can pass
+the string `vim` or `gvim` as the first and only argument.
+
+[v:progname]: http://vimdoc.sourceforge.net/htmldoc/eval.html#v:progname
 
 #### The `xolox#misc#os#exec()` function
 

autoload/xolox/misc.vim

@@ -4,4 +4,4 @@
 " Last Change: June 3, 2013
 " URL: http://peterodding.com/code/vim/misc/
 
-let g:xolox#misc#version = '1.5'
+let g:xolox#misc#version = '1.6'

autoload/xolox/misc/os.vim

@@ -1,47 +1,59 @@
 " Operating system interfaces.
 "
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: June 1, 2013
+" Last Change: June 3, 2013
 " URL: http://peterodding.com/code/vim/misc/
 
 function! xolox#misc#os#is_win() " {{{1
   " Returns 1 (true) when on Microsoft Windows, 0 (false) otherwise.
   return has('win16') || has('win32') || has('win64')
 endfunction
 
-function! xolox#misc#os#find_vim() " {{{1
-  " Returns the program name of Vim as a string. On Windows and UNIX this
-  " simply returns [v:progname] [progname] while on Mac OS X there is some
-  " special magic to find MacVim's executable even though it's usually not on
-  " the executable search path. If you want, you can override the value
-  " returned from this function by setting the global variable
+function! xolox#misc#os#find_vim(...) " {{{1
+  " Returns the program name of Vim as a string. On Windows and UNIX this just
+  " [v:progname] [] as an absolute pathname while on Mac OS X there is
+  " some special magic to find MacVim's executable even though it's usually
+  " not on the executable search path. If you want, you can override the
+  " value returned from this function by setting the global variable
   " `g:xolox#misc#os#vim_progname`.
   "
-  " [progname]: http://vimdoc.sourceforge.net/htmldoc/eval.html#v:progname
-  let progname = ''
+  " By default the choice of console Vim vs graphical Vim is made based on
+  " the value of [v:progname] [], but if you have a preference you can pass
+  " the string `vim` or `gvim` as the first and only argument.
+  "
+  " [v:progname]: http://vimdoc.sourceforge.net/htmldoc/eval.html#v:progname
+  if exists('a:1')
+    let program_name = a:1
+  else
+    let program_name = v:progname
+  endif
   if exists('g:xolox#misc#os#vim_progname')
-    let progname = g:xolox#misc#os#vim_progname
+    let pathname = g:xolox#misc#os#vim_progname
+  else
+    let pathname = ''
   endif
-  if empty(progname) && has('macunix')
+  if empty(pathname) && has('macunix')
     " Special handling for Mac OS X where MacVim is usually not on the $PATH.
+    " This always returns the "Vim" executable and not "MacVim" (regardless of
+    " the caller's preference) because "MacVim" has funky dock magic going on.
     call xolox#misc#msg#debug("vim-misc %s: Trying MacVim workaround to find Vim executable ..", g:xolox#misc#version)
     let segments = xolox#misc#path#split($VIMRUNTIME)
     if segments[-3:] == ['Resources', 'vim', 'runtime']
-      let progname = xolox#misc#path#join(segments[0:-4] + ['MacOS', 'Vim'])
-      call xolox#misc#msg#debug("vim-misc %s: The MacVim workaround resulted in the Vim executable %s.", g:xolox#misc#version, string(progname))
+      let pathname = xolox#misc#path#join(segments[0:-4] + ['MacOS', 'Vim'])
+      call xolox#misc#msg#debug("vim-misc %s: The MacVim workaround resulted in the Vim executable %s.", g:xolox#misc#version, string(pathname))
     endif
   endif
-  if empty(progname)
+  if empty(pathname)
     " Default logic.
-    call xolox#misc#msg#debug("vim-misc %s: Looking for Vim executable named %s on search path ..", g:xolox#misc#version, string(v:progname))
-    let candidates = xolox#misc#path#which(v:progname)
+    call xolox#misc#msg#debug("vim-misc %s: Looking for Vim executable named %s on search path ..", g:xolox#misc#version, string(program_name))
+    let candidates = xolox#misc#path#which(program_name)
     if !empty(candidates)
       call xolox#misc#msg#debug("vim-misc %s: Found %i candidate(s) on search path: %s.", g:xolox#misc#version, len(candidates), string(candidates))
-      let progname = candidates[0]
+      let pathname = candidates[0]
     endif
   endif
-  call xolox#misc#msg#debug("vim-misc %s: Reporting Vim executable %s.", g:xolox#misc#version, string(progname))
-  return progname
+  call xolox#misc#msg#debug("vim-misc %s: Reporting Vim executable %s.", g:xolox#misc#version, string(pathname))
+  return pathname
 endfunction
 
 function! xolox#misc#os#exec(options) " {{{1

doc/misc.txt

@@ -137,7 +137,7 @@ from the source code of the miscellaneous scripts using the Python module
 'vimdoctool.py' included in vim-tools [5].
 
 The documentation of the 67 functions below was extracted from 15 Vim scripts
-on June 3, 2013 at 21:23.
+on June 3, 2013 at 21:53.
 
 -------------------------------------------------------------------------------
                                              *misc-handling-of-special-buffers*
@@ -401,11 +401,15 @@ Returns 1 (true) when on Microsoft Windows, 0 (false) otherwise.
 -------------------------------------------------------------------------------
 The *xolox#misc#os#find_vim()* function
 
-Returns the program name of Vim as a string. On Windows and UNIX this simply
-returns |v:progname| while on Mac OS X there is some special magic to find
-MacVim's executable even though it's usually not on the executable search path.
-If you want, you can override the value returned from this function by setting
-the global variable 'g:xolox#misc#os#vim_progname'.
+Returns the program name of Vim as a string. On Windows and UNIX this just
+|v:progname| as an absolute pathname while on Mac OS X there is some special
+magic to find MacVim's executable even though it's usually not on the
+executable search path. If you want, you can override the value returned from
+this function by setting the global variable 'g:xolox#misc#os#vim_progname'.
+
+By default the choice of console Vim vs graphical Vim is made based on the
+value of |v:progname|, but if you have a preference you can pass the string
+'vim' or 'gvim' as the first and only argument.
 
 -------------------------------------------------------------------------------
 The *xolox#misc#os#exec()* function