aboutsummaryrefslogtreecommitdiffstats
path: root/autoload/xolox
diff options
context:
space:
mode:
Diffstat (limited to 'autoload/xolox')
-rw-r--r--autoload/xolox/misc/buffer.vim39
-rw-r--r--autoload/xolox/misc/compat.vim15
-rw-r--r--autoload/xolox/misc/complete.vim12
-rw-r--r--autoload/xolox/misc/escape.vim40
-rw-r--r--autoload/xolox/misc/list.vim24
-rw-r--r--autoload/xolox/misc/msg.vim35
-rw-r--r--autoload/xolox/misc/open.vim32
-rw-r--r--autoload/xolox/misc/option.vim51
-rw-r--r--autoload/xolox/misc/os.vim35
-rw-r--r--autoload/xolox/misc/path.vim70
-rw-r--r--autoload/xolox/misc/str.vim12
-rw-r--r--autoload/xolox/misc/timer.vim33
12 files changed, 295 insertions, 103 deletions
diff --git a/autoload/xolox/misc/buffer.vim b/autoload/xolox/misc/buffer.vim
index 3597cc2..01dca6e 100644
--- a/autoload/xolox/misc/buffer.vim
+++ b/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
diff --git a/autoload/xolox/misc/compat.vim b/autoload/xolox/misc/compat.vim
index 84f0a5f..3cf1f1f 100644
--- a/autoload/xolox/misc/compat.vim
+++ b/autoload/xolox/misc/compat.vim
@@ -1,9 +1,14 @@
-" Vim auto-load script
+" Compatibility checking.
+"
" Author: Peter Odding <peter@peterodding.com>
" Last Change: May 19, 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 :-).
@@ -14,6 +19,10 @@ let g:xolox#misc#compat#version = 6
let s:misc_directory = fnamemodify(expand('<sfile>'), ':p:h')
function! xolox#misc#compat#check(plugin_name, required_version)
+ " Expects two arguments: The name of a Vim plug-in and the version of the
+ " miscellaneous scripts expected by the plug-in. When the active version of
+ " the miscellaneous scripts has a different version, this 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)
diff --git a/autoload/xolox/misc/complete.vim b/autoload/xolox/misc/complete.vim
index 2ada676..763e0b9 100644
--- a/autoload/xolox/misc/complete.vim
+++ b/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\+')
diff --git a/autoload/xolox/misc/escape.vim b/autoload/xolox/misc/escape.vim
index 1dd1838..29a16ca 100644
--- a/autoload/xolox/misc/escape.vim
+++ b/autoload/xolox/misc/escape.vim
@@ -1,11 +1,16 @@
-" 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')
@@ -13,9 +18,10 @@ function! xolox#misc#escape#pattern(string)
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')
@@ -23,13 +29,17 @@ function! xolox#misc#escape#substitute(string)
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
diff --git a/autoload/xolox/misc/list.vim b/autoload/xolox/misc/list.vim
index ee243d4..13dfb43 100644
--- a/autoload/xolox/misc/list.vim
+++ b/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
diff --git a/autoload/xolox/misc/msg.vim b/autoload/xolox/misc/msg.vim
index 74657c8..38eb474 100644
--- a/autoload/xolox/misc/msg.vim
+++ b/autoload/xolox/misc/msg.vim
@@ -1,4 +1,5 @@
-" Vim auto-load script
+" Functions to interact with the user.
+"
" Author: Peter Odding <peter@peterodding.com>
" Last Change: May 19, 2013
" URL: http://peterodding.com/code/vim/misc/
@@ -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]
@@ -73,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
diff --git a/autoload/xolox/misc/open.vim b/autoload/xolox/misc/open.vim
index 1fb24e0..b369f4f 100644
--- a/autoload/xolox/misc/open.vim
+++ b/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))
diff --git a/autoload/xolox/misc/option.vim b/autoload/xolox/misc/option.vim
index 2912967..fce155c 100644
--- a/autoload/xolox/misc/option.vim
+++ b/autoload/xolox/misc/option.vim
@@ -1,9 +1,18 @@
-" Vim auto-load script
+" Vim and plug-in option handling.
+"
" Author: Peter Odding <peter@peterodding.com>
-" Last Change: August 31, 2011
+" Last Change: May 19, 2013
" URL: http://peterodding.com/code/vim/misc/
-function! xolox#misc#option#get(name, ...)
+function! xolox#misc#option#get(name, ...) " {{{1
+ " Expects one or two arguments: 1. The name of a variable and 2. the default
+ " value if the variable does not exist.
+ "
+ " Returns the value of the variable from a buffer local variable, global
+ " variable or the default value, depending on which is defined.
+ "
+ " This is used by some of my Vim plug-ins for option handling, so that users
+ " can customize options for specific buffers.
if exists('b:' . a:name)
" Buffer local variable.
return eval('b:' . a:name)
@@ -16,9 +25,17 @@ function! xolox#misc#option#get(name, ...)
endif
endfunction
-" Functions to parse multi-valued Vim options like &tags and &runtimepath.
-
-function! xolox#misc#option#split(value)
+function! xolox#misc#option#split(value) " {{{1
+ " Given a multi-value Vim option like ['runtimepath'] [rtp] this returns a
+ " list of strings. For example:
+ "
+ " :echo xolox#misc#option#split(&runtimepath)
+ " ['/home/peter/Projects/Vim/misc',
+ " '/home/peter/Projects/Vim/colorscheme-switcher',
+ " '/home/peter/Projects/Vim/easytags',
+ " ...]
+ "
+ " [rtp]: http://vimdoc.sourceforge.net/htmldoc/options.html#'runtimepath'
let values = split(a:value, '[^\\]\zs,')
return map(values, 's:unescape(v:val)')
endfunction
@@ -27,7 +44,10 @@ function! s:unescape(s)
return substitute(a:s, '\\\([\\,]\)', '\1', 'g')
endfunction
-function! xolox#misc#option#join(values)
+function! xolox#misc#option#join(values) " {{{1
+ " Given a list of strings like the ones returned by
+ " `xolox#misc#option#split()`, this joins the strings together into a
+ " single value that can be used to set a Vim option.
let values = copy(a:values)
call map(values, 's:escape(v:val)')
return join(values, ',')
@@ -37,7 +57,11 @@ function! s:escape(s)
return escape(a:s, ',\')
endfunction
-function! xolox#misc#option#split_tags(value)
+function! xolox#misc#option#split_tags(value) " {{{1
+ " Customized version of `xolox#misc#option#split()` with specialized
+ " handling for Vim's ['tags' option] [tags].
+ "
+ " [tags]: http://vimdoc.sourceforge.net/htmldoc/options.html#'tags'
let values = split(a:value, '[^\\]\zs,')
return map(values, 's:unescape_tags(v:val)')
endfunction
@@ -46,7 +70,9 @@ function! s:unescape_tags(s)
return substitute(a:s, '\\\([\\, ]\)', '\1', 'g')
endfunction
-function! xolox#misc#option#join_tags(values)
+function! xolox#misc#option#join_tags(values) " {{{1
+ " Customized version of `xolox#misc#option#join()` with specialized
+ " handling for Vim's ['tags' option] [tags].
let values = copy(a:values)
call map(values, 's:escape_tags(v:val)')
return join(values, ',')
@@ -56,7 +82,12 @@ function! s:escape_tags(s)
return escape(a:s, ', ')
endfunction
-function! xolox#misc#option#eval_tags(value, ...)
+function! xolox#misc#option#eval_tags(value, ...) " {{{1
+ " Evaluate Vim's ['tags' option] [tags] without looking at the file
+ " system, i.e. this will report tags files that don't exist yet. Expects
+ " the value of the ['tags' option] [tags] as the first argument. If the
+ " optional second argument is 1 (true) only the first match is returned,
+ " otherwise (so by default) a list with all matches is returned.
let pathnames = []
let first_only = exists('a:1') ? a:1 : 0
for pattern in xolox#misc#option#split_tags(a:value)
diff --git a/autoload/xolox/misc/os.vim b/autoload/xolox/misc/os.vim
index 032d2c8..4dcf64d 100644
--- a/autoload/xolox/misc/os.vim
+++ b/autoload/xolox/misc/os.vim
@@ -1,4 +1,5 @@
-" Vim auto-load script
+" Operating system interfaces.
+"
" Author: Peter Odding <peter@peterodding.com>
" Last Change: May 19, 2013
" URL: http://peterodding.com/code/vim/misc/
@@ -6,14 +7,38 @@
let g:xolox#misc#os#version = '0.3'
function! xolox#misc#os#is_win() " {{{1
- " Check whether Vim is running on Microsoft Windows.
+ " Returns 1 (true) when on Microsoft Windows, 0 (false) otherwise.
return has('win16') || has('win32') || has('win64')
endfunction
function! xolox#misc#os#exec(options) " {{{1
- " Execute an external command (hiding the console on Windows when possible).
- " NB: Everything below is wrapped in a try/finally block to guarantee
- " cleanup of temporary files.
+ " Execute an external command (hiding the console on Microsoft Windows when
+ " my [vim-shell plug-in] [vim-shell] is installed).
+ "
+ " Expects a dictionary with the following key/value pairs as the first
+ " argument:
+ "
+ " - **command** (required): The command line to execute
+ " - **async** (optional): set this to 1 (true) to execute the command in the
+ " background (asynchronously)
+ " - **stdin** (optional): a string or list of strings with the input for the
+ " external command
+ " - **check** (optional): set this to 0 (false) to disable checking of the
+ " exit code of the external command (by default an exception will be
+ " raised when the command fails)
+ "
+ " Returns a dictionary with one or more of the following key/value pairs:
+ "
+ " - **command** (always available): the generated command line that was used
+ " to run the external command
+ " - **exit_code** (only in synchronous mode): the exit status of the
+ " external command (an integer, zero on success)
+ " - **stdout** (only in synchronous mode): the output of the command on the
+ " standard output stream (a list of strings, one for each line)
+ " - **stderr** (only in synchronous mode): the output of the command on the
+ " standard error stream (as a list of strings, one for each line)
+ "
+ " [vim-shell]: http://peterodding.com/code/vim/shell/
try
" Unpack the options.
diff --git a/autoload/xolox/misc/path.vim b/autoload/xolox/misc/path.vim
index 60d3cbb..15e11d6 100644
--- a/autoload/xolox/misc/path.vim
+++ b/autoload/xolox/misc/path.vim
@@ -1,4 +1,5 @@
-" Vim auto-load script
+" Pathname manipulation functions.
+"
" Author: Peter Odding <peter@peterodding.com>
" Last Change: May 19, 2013
" URL: http://peterodding.com/code/vim/misc/
@@ -7,7 +8,16 @@ let s:windows_compatible = has('win32') || has('win64')
let s:mac_os_x_compatible = has('macunix')
function! xolox#misc#path#which(...) " {{{1
- " Scan the executable search path for programs.
+ " Scan the executable search path (`$PATH`) for one or more external
+ " programs. Expects one or more string arguments with program names. Returns
+ " a list with the absolute pathnames of all found programs. Here's an
+ " example:
+ "
+ " :echo xolox#misc#path#which('gvim', 'vim')
+ " ['/usr/local/bin/gvim',
+ " '/usr/bin/gvim',
+ " '/usr/local/bin/vim',
+ " '/usr/bin/vim']
let extensions = s:windows_compatible ? split($PATHEXT, ';') : ['']
let matches = []
let checked = {}
@@ -28,23 +38,35 @@ function! xolox#misc#path#which(...) " {{{1
endfunction
function! xolox#misc#path#split(path) " {{{1
- " Split a pathname into a list of path components.
+ " Split a pathname (the first and only argument) into a list of pathname
+ " components.
+ "
+ " On Windows, pathnames starting with two slashes or backslashes are UNC
+ " paths where the leading slashes are significant... In this case we split
+ " like this:
+ "
+ " - Input: `'//server/share/directory'`
+ " - Result: `['//server', 'share', 'directory']`
+ "
+ " Everything except Windows is treated like UNIX until someone has a better
+ " suggestion :-). In this case we split like this:
+ "
+ " - Input: `'/foo/bar/baz'`
+ " - Result: `['/', 'foo', 'bar', 'baz']`
+ "
+ " To join a list of pathname components back into a single pathname string,
+ " use the `xolox#misc#path#join()` function.
if type(a:path) == type('')
if s:windows_compatible
if a:path =~ '^[\/][\/]'
- " On Windows, pathnames starting with two slashes or backslashes are
- " UNC paths where the leading slashes are significant... In this case
- " we split like this:
- " '//server/share/directory' -> ['//server', 'share', 'directory']
+ " UNC pathname.
return split(a:path, '\%>2c[\/]\+')
else
" If it's not a UNC path we can simply split on slashes & backslashes.
return split(a:path, '[\/]\+')
endif
else
- " Everything except Windows is treated like UNIX until someone
- " has a better suggestion :-). In this case we split like this:
- " '/foo/bar/baz' -> ['/', 'foo', 'bar', 'baz']
+ " Everything else is treated as UNIX.
let absolute = (a:path =~ '^/')
let segments = split(a:path, '/\+')
return absolute ? insert(segments, '/') : segments
@@ -54,7 +76,10 @@ function! xolox#misc#path#split(path) " {{{1
endfunction
function! xolox#misc#path#join(parts) " {{{1
- " Join a list of pathname components into a single pathname.
+ " Join a list of pathname components (the first and only argument) into a
+ " single pathname string. This is the counterpart to the
+ " `xolox#misc#path#split()` function and it expects a list of pathname
+ " components as returned by `xolox#misc#path#split()`.
if type(a:parts) == type([])
if s:windows_compatible
return join(a:parts, xolox#misc#path#directory_separator())
@@ -75,9 +100,9 @@ function! xolox#misc#path#directory_separator() " {{{1
endfunction
function! xolox#misc#path#absolute(path) " {{{1
- " Canonicalize and resolve a pathname, regardless of whether it exists. This
- " is intended to support string comparison to determine whether two pathnames
- " point to the same directory or file.
+ " Canonicalize and resolve a pathname, *regardless of whether it exists*.
+ " This is intended to support string comparison to determine whether two
+ " pathnames point to the same directory or file.
if type(a:path) == type('')
let path = a:path
" Make the pathname absolute.
@@ -107,7 +132,8 @@ function! xolox#misc#path#absolute(path) " {{{1
endfunction
function! xolox#misc#path#relative(path, base) " {{{1
- " Make an absolute pathname relative.
+ " Make an absolute pathname (the first argument) relative to a directory
+ " (the second argument).
let path = xolox#misc#path#split(a:path)
let base = xolox#misc#path#split(a:base)
while path != [] && base != [] && path[0] == base[0]
@@ -120,9 +146,9 @@ endfunction
function! xolox#misc#path#merge(parent, child, ...) " {{{1
- " Join a directory and filename into a single pathname.
- " TODO Use isabs()!
+ " Join a directory pathname and filename into a single pathname.
if type(a:parent) == type('') && type(a:child) == type('')
+ " TODO Use xolox#misc#path#is_relative()?
if s:windows_compatible
let parent = substitute(a:parent, '[\\/]\+$', '', '')
let child = substitute(a:child, '^[\\/]\+', '', '')
@@ -155,7 +181,8 @@ function! xolox#misc#path#commonprefix(paths) " {{{1
endfunction
function! xolox#misc#path#encode(path) " {{{1
- " Encode a pathname so it can be used as a filename.
+ " Encode a pathname so it can be used as a filename. This uses URL encoding
+ " to encode special characters.
if s:windows_compatible
let mask = '[*|\\/:"<>?%]'
elseif s:mac_os_x_compatible
@@ -168,7 +195,7 @@ endfunction
function! xolox#misc#path#decode(encoded_path) " {{{1
- " Decode a pathname previously encoded with xolox#misc#path#encode().
+ " Decode a pathname previously encoded with `xolox#misc#path#encode()`.
return substitute(a:encoded_path, '%\(\x\x\?\)', '\=nr2char("0x" . submatch(1))', 'g')
endfunction
@@ -185,7 +212,8 @@ else
endif
function! xolox#misc#path#is_relative(path) " {{{1
- " Check whether a path is relative.
+ " Returns true (1) when the pathname given as the first argument is
+ " relative, false (0) otherwise.
if a:path =~ '^\w\+://'
return 0
elseif s:windows_compatible
@@ -196,7 +224,7 @@ function! xolox#misc#path#is_relative(path) " {{{1
endfunction
function! xolox#misc#path#tempdir() " {{{1
- " Create a temporary directory and return the path.
+ " Create a temporary directory and return the pathname of the directory.
if !exists('s:tempdir_counter')
let s:tempdir_counter = 1
endif
diff --git a/autoload/xolox/misc/str.vim b/autoload/xolox/misc/str.vim
index 74a05aa..901696c 100644
--- a/autoload/xolox/misc/str.vim
+++ b/autoload/xolox/misc/str.vim
@@ -1,11 +1,17 @@
-" Vim auto-load script
+" String handling.
+"
" Author: Peter Odding <peter@peterodding.com>
-" Last Change: June 14, 2011
+" Last Change: May 19, 2013
" URL: http://peterodding.com/code/vim/misc/
-" Trim whitespace from start and end of string.
+function! xolox#misc#str#compact(s)
+ " Compact whitespace in the string given as the first argument.
+ return join(split(a:s), " ")
+endfunction
function! xolox#misc#str#trim(s)
+ " Trim all whitespace from the start and end of the string given as the
+ " first argument.
return substitute(a:s, '^\_s*\(.\{-}\)\_s*$', '\1', '')
endfunction
diff --git a/autoload/xolox/misc/timer.vim b/autoload/xolox/misc/timer.vim
index 151972d..d7fc32d 100644
--- a/autoload/xolox/misc/timer.vim
+++ b/autoload/xolox/misc/timer.vim
@@ -1,6 +1,7 @@
-" Vim auto-load script
+" Timing of long during operations.
+"
" 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:timer_enabled')
@@ -13,24 +14,33 @@ endif
let s:has_reltime = has('reltime')
-" Start a timer.
-
-function! xolox#misc#timer#start()
+function! xolox#misc#timer#start() " {{{1
+ " Start a timer. This returns a list which can later be passed to
+ " `xolox#misc#timer#stop()`.
if g:timer_enabled || &verbose >= g:timer_verbosity
return s:has_reltime ? reltime() : [localtime()]
endif
return []
endfunction
-" Stop a timer and print the elapsed time (only if the user is interested).
-
-function! xolox#misc#timer#stop(...)
+function! xolox#misc#timer#stop(...) " {{{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 with one difference: At the point where you want the elapsed time
+ " to be embedded, you write `%s` and you pass the list returned by
+ " `xolox#misc#timer#start()` as an argument.
+ "
+ " [verbose]: http://vimdoc.sourceforge.net/htmldoc/options.html#'verbose'
+ " [printf]: http://vimdoc.sourceforge.net/htmldoc/eval.html#printf()
if (g:timer_enabled || &verbose >= g:timer_verbosity)
call call('xolox#misc#msg#info', map(copy(a:000), 's:convert_value(v:val)'))
endif
endfunction
-function! s:convert_value(value)
+function! s:convert_value(value) " {{{1
if type(a:value) != type([])
return a:value
elseif !empty(a:value)
@@ -49,7 +59,10 @@ endfunction
let s:units = [['day', 60 * 60 * 24], ['hour', 60 * 60], ['minute', 60], ['second', 1]]
-function! xolox#misc#timer#format_timespan(ts)
+function! xolox#misc#timer#format_timespan(ts) " {{{1
+ " Format a time stamp (a string containing a formatted floating point
+ " number) into a human friendly format, for example 70 seconds is phrased as
+ " "1 minute and 10 seconds".
" Convert timespan to integer.
let seconds = a:ts + 0
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-22 08:43:12 +0000