feat(lua): add semver api

2 files changed, 76 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 1eb5ab41e6..3c48cd37a6 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2497,4 +2497,76 @@ trust({opts})                                             *vim.secure.trust()*
         • true and full path of target file if operation was successful
         • false and error message on failure
 
+
+==============================================================================
+Lua module: version                                              *lua-version*
+
+cmp({v1}, {v2}, {opts})                                        *version.cmp()*
+    Compares two strings ( `v1` and `v2` ) in semver format.
+
+    Parameters: ~
+      • {v1}    (string) Version.
+      • {v2}    (string) Version to be compared with v1.
+      • {opts}  (table|nil) Optional keyword arguments:
+                • strict (boolean): see `semver.parse` for details. Defaults
+                  to false.
+
+    Return: ~
+        (integer) `-1` if `v1 < v2`, `0` if `v1 == v2`, `1` if `v1 > v2`.
+
+eq({version_1}, {version_2})                                    *version.eq()*
+    Returns `true` if `v1` are `v2` are equal versions.
+
+    Parameters: ~
+      • {version_1}  (string)
+      • {version_2}  (string)
+
+    Return: ~
+        (boolean)
+
+gt({version_1}, {version_2})                                    *version.gt()*
+    Returns `true` if `v1` is greater than `v2` .
+
+    Parameters: ~
+      • {version_1}  (string)
+      • {version_2}  (string)
+
+    Return: ~
+        (boolean)
+
+lt({version_1}, {version_2})                                    *version.lt()*
+    Returns `true` if `v1` is less than `v2` .
+
+    Parameters: ~
+      • {version_1}  (string)
+      • {version_2}  (string)
+
+    Return: ~
+        (boolean)
+
+parse({version}, {opts})                                     *version.parse()*
+    Parses a semantically formatted version string into a table.
+
+    Supports leading "v" and leading and trailing whitespace in the version
+    string. e.g. `" v1.0.1-rc1+build.2"` , `"1.0.1-rc1+build.2"`,
+    `"v1.0.1-rc1+build.2"` and `"v1.0.1-rc1+build.2 "` will be parsed as:
+
+    { major = 1, minor = 0, patch = 1, prerelease = 'rc1 , build = 'build.2' }`
+
+    Parameters: ~
+      • {version}  (string) Version string to be parsed.
+      • {opts}     (table|nil) Optional keyword arguments:
+                   • strict (boolean): when set to `true` an error will be
+                     thrown for version strings that do not conform to the
+                     semver specification (v2.0.0) (see
+                     semver.org/spec/v2.0.0.html for details). This means that
+                     `semver.parse('v1.2)` will throw an error. When set to
+                     `false`, `semver.parse('v1.2)` will coerce 'v1.2' to
+                     'v1.2.0' and return the table: `{ major = 1, minor = 2,
+                     patch = 0 }`. Defaults to false.
+
+    Return: ~
+        (table|nil) parsed_version Parsed version table or `nil` if `version`
+        is not valid.
+
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 415195e27e..b5cb975066 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -55,6 +55,10 @@ NEW FEATURES                                                    *news-features*
 
 The following new APIs or features were added.
 
+• Added |version.parse()|, |version.cmp()|, |version.lt()|, |version.eq()|
+  and |version.gt()| to |vim.version| for parsing and comparing version numbers
+  according to the semver specification, see |lua-version|.
+
 • A new environment variable named NVIM_APPNAME enables configuring the
   directories where Neovim should find its configuration and state files. See
   `:help $NVIM_APPNAME` .