Version string parsing and comparison functions

README.md

@@ -37,8 +37,8 @@ from the source code of the miscellaneous scripts using the Python module
 
 <!-- Start of generated documentation -->
 
-The documentation of the 68 functions below was extracted from
-15 Vim scripts on June 19, 2013 at 22:53.
+The documentation of the 72 functions below was extracted from
+16 Vim scripts on June 22, 2013 at 02:08.
 
 ### Handling of special buffers
 
@@ -570,6 +570,14 @@ Test synchronous command execution without raising of errors with
 Test basic functionality of asynchronous command execution with
 `xolox#misc#os#exec()`.
 
+#### The `xolox#misc#tests#version_string_parsing()` function
+
+Test parsing of version strings with `xolox#misc#version#parse()`.
+
+#### The `xolox#misc#tests#version_string_comparison()` function
+
+Test comparison of version strings with `xolox#misc#version#at_least()`.
+
 ### Timing of long during operations
 
 #### The `xolox#misc#timer#start()` function
@@ -598,6 +606,17 @@ 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.
 
+### Version string handling
+
+#### The `xolox#misc#version#parse()` function
+
+Convert a version string to a list of integers.
+
+#### The `xolox#misc#version#at_least()` function
+
+Check whether the second version string is equal to or greater than the
+first version string. Returns 1 (true) when it is, 0 (false) otherwise.
+
 <!-- End of generated documentation -->
 
 ## Contact

autoload/xolox/misc.vim

@@ -1,7 +1,7 @@
 " The version of my miscellaneous scripts.
 "
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: June 19, 2013
+" Last Change: June 22, 2013
 " URL: http://peterodding.com/code/vim/misc/
 
-let g:xolox#misc#version = '1.6.3'
+let g:xolox#misc#version = '1.7'

autoload/xolox/misc/tests.vim

@@ -1,7 +1,7 @@
 " Tests for the miscellaneous Vim scripts.
 "
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: June 2, 2013
+" Last Change: June 22, 2013
 " URL: http://peterodding.com/code/vim/misc/
 "
 " The Vim auto-load script `autoload/xolox/misc/tests.vim` contains the
@@ -17,6 +17,7 @@ function! xolox#misc#tests#run() " {{{1
   call s:test_list_handling()
   call s:test_option_handling()
   call s:test_command_execution()
+  call s:test_version_handling()
   " Report a short summary to the user.
   call xolox#misc#test#summarize()
 endfunction
@@ -228,3 +229,28 @@ function! xolox#misc#tests#asynchronous_command_execution() " {{{2
   call xolox#misc#test#assert_true(filereadable(tempfile))
   call xolox#misc#test#assert_equals([expected_value], readfile(tempfile))
 endfunction
+
+" Tests for autoload/xolox/misc/version.vim {{{1
+
+function! s:test_version_handling()
+  call xolox#misc#test#wrap('xolox#misc#tests#version_string_parsing')
+  call xolox#misc#test#wrap('xolox#misc#tests#version_string_comparison')
+endfunction
+
+function! xolox#misc#tests#version_string_parsing() " {{{2
+  " Test parsing of version strings with `xolox#misc#version#parse()`.
+  call xolox#misc#test#assert_equals([1], xolox#misc#version#parse('1'))
+  call xolox#misc#test#assert_equals([1, 5], xolox#misc#version#parse('1.5'))
+  call xolox#misc#test#assert_equals([1, 22, 3333, 44444, 55555], xolox#misc#version#parse('1.22.3333.44444.55555'))
+  call xolox#misc#test#assert_equals([1, 5], xolox#misc#version#parse('1x.5y'))
+endfunction
+
+function! xolox#misc#tests#version_string_comparison() " {{{2
+  " Test comparison of version strings with `xolox#misc#version#at_least()`.
+  call xolox#misc#test#assert_true(xolox#misc#version#at_least('1', '1'))
+  call xolox#misc#test#assert_true(!xolox#misc#version#at_least('1', '0'))
+  call xolox#misc#test#assert_true(xolox#misc#version#at_least('1', '2'))
+  call xolox#misc#test#assert_true(xolox#misc#version#at_least('1.2.3', '1.2.3'))
+  call xolox#misc#test#assert_true(!xolox#misc#version#at_least('1.2.3', '1.2'))
+  call xolox#misc#test#assert_true(xolox#misc#version#at_least('1.2.3', '1.2.4'))
+endfunction

autoload/xolox/misc/version.vim

@@ -0,0 +1,34 @@
+" Version string handling.
+"
+" Author: Peter Odding <peter@peterodding.com>
+" Last Change: June 22, 2013
+" URL: http://peterodding.com/code/vim/misc/
+
+function! xolox#misc#version#parse(version_string)
+  " Convert a version string to a list of integers.
+  let result = map(split(a:version_string, '\.'), 'v:val + 0')
+  call xolox#misc#msg#debug("vim-misc %s: Parsed version string %s into %s.", g:xolox#misc#version, string(a:version_string), string(result))
+  return result
+endfunction
+
+function! xolox#misc#version#at_least(expected_version, available_version)
+  " Check whether the second version string is equal to or greater than the
+  " first version string. Returns 1 (true) when it is, 0 (false) otherwise.
+  let expected_version = xolox#misc#version#parse(a:expected_version)
+  let available_version = xolox#misc#version#parse(a:available_version)
+  for idx in range(max([len(expected_version), len(available_version)]))
+    let expected_number = get(expected_version, idx, 0)
+    let available_number = get(available_version, idx, 0)
+    if available_number > expected_number
+      call xolox#misc#msg#debug("vim-misc %s: Available version (%s) is higher than expected version (%s).", g:xolox#misc#version, a:available_version, a:expected_version)
+      return 1
+    elseif available_number < expected_number
+      call xolox#misc#msg#debug("vim-misc %s: Available version (%s) is lower than expected version (%s).", g:xolox#misc#version, a:available_version, a:expected_version)
+      return 0
+    endif
+  endfor
+  call xolox#misc#msg#debug("vim-misc %s: Available version (%s) is equal to expected version (%s).", g:xolox#misc#version, a:available_version, a:expected_version)
+  return 1
+endfunction
+
+" vim: ts=2 sw=2 et

doc/misc.txt

@@ -86,10 +86,15 @@ function
    14. The |xolox#misc#tests#synchronous_command_execution_without_raising_errors()|
 function
    15. The |xolox#misc#tests#asynchronous_command_execution()| function
+   16. The |xolox#misc#tests#version_string_parsing()| function
+   17. The |xolox#misc#tests#version_string_comparison()| function
   14. Timing of long during operations  |misc-timing-of-long-during-operations|
    1. The |xolox#misc#timer#start()| function
    2. The |xolox#misc#timer#stop()| function
    3. The |xolox#misc#timer#force()| function
+  15. Version string handling                    |misc-version-string-handling|
+   1. The |xolox#misc#version#parse()| function
+   2. The |xolox#misc#version#at_least()| function
  4. Contact                                                      |misc-contact|
  5. License                                                      |misc-license|
  6. References                                                |misc-references|
@@ -137,8 +142,8 @@ For those who are curious: The function descriptions given below were extracted
 from the source code of the miscellaneous scripts using the Python module
 'vimdoctool.py' included in vim-tools [5].
 
-The documentation of the 68 functions below was extracted from 15 Vim scripts
-on June 19, 2013 at 22:53.
+The documentation of the 72 functions below was extracted from 16 Vim scripts
+on June 22, 2013 at 02:08.
 
 -------------------------------------------------------------------------------
                                              *misc-handling-of-special-buffers*
@@ -723,6 +728,16 @@ The *xolox#misc#tests#asynchronous_command_execution()* function
 Test basic functionality of asynchronous command execution with
 |xolox#misc#os#exec()|.
 
+-------------------------------------------------------------------------------
+The *xolox#misc#tests#version_string_parsing()* function
+
+Test parsing of version strings with |xolox#misc#version#parse()|.
+
+-------------------------------------------------------------------------------
+The *xolox#misc#tests#version_string_comparison()* function
+
+Test comparison of version strings with |xolox#misc#version#at_least()|.
+
 -------------------------------------------------------------------------------
                                         *misc-timing-of-long-during-operations*
 Timing of long during operations ~
@@ -752,6 +767,21 @@ handling as Vim's |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.
 
+-------------------------------------------------------------------------------
+                                                 *misc-version-string-handling*
+Version string handling ~
+
+-------------------------------------------------------------------------------
+The *xolox#misc#version#parse()* function
+
+Convert a version string to a list of integers.
+
+-------------------------------------------------------------------------------
+The *xolox#misc#version#at_least()* function
+
+Check whether the second version string is equal to or greater than the first
+version string. Returns 1 (true) when it is, 0 (false) otherwise.
+
 ===============================================================================
                                                                  *misc-contact*
 Contact ~