Permalink
Browse files

Updated miscellaneous scripts

  • Loading branch information...
2 parents 8e23d8e + 37a9bf4 commit dab5a33c6a505a464d50c82b81141a668b36085a @xolox committed May 19, 2013
@@ -1,11 +1,11 @@
" Vim script.
" Author: Peter Odding <peter@peterodding.com>
-" Last Change: May 13, 2013
+" Last Change: May 20, 2013
" URL: http://peterodding.com/code/vim/lua-inspect/
-let g:xolox#luainspect#version = '0.4.22'
+let g:xolox#luainspect#version = '0.4.23'
-call xolox#misc#compat#check('lua-inspect', 3)
+call xolox#misc#compat#check('luainspect.vim', g:xolox#luainspect#version, 7)
function! xolox#luainspect#toggle_cmd() " {{{1
if !(exists('b:luainspect_disabled') && b:luainspect_disabled)
@@ -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
@@ -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
@@ -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\+')
@@ -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
@@ -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
@@ -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
@@ -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))
Oops, something went wrong.

0 comments on commit dab5a33

Please sign in to comment.