feat(lua): add semver api

1 files changed, 297 insertions, 0 deletions

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
new file mode 100644
index 0000000000..49ef019295
--- /dev/null
+++ b/runtime/lua/vim/version.lua
@@ -0,0 +1,297 @@
+local M = {}
+
+---@private
+--- Compares the prerelease component of the two versions.
+---@param v1_parsed table Parsed version.
+---@param v2_parsed table Parsed version.
+---@return integer `-1` if `v1_parsed < v2_parsed`, `0` if `v1_parsed == v2_parsed`, `1` if `v1_parsed > v2_parsed`.
+local function cmp_prerelease(v1_parsed, v2_parsed)
+  if v1_parsed.prerelease and not v2_parsed.prerelease then
+    return -1
+  end
+  if not v1_parsed.prerelease and v2_parsed.prerelease then
+    return 1
+  end
+  if not v1_parsed.prerelease and not v2_parsed.prerelease then
+    return 0
+  end
+
+  local v1_identifiers = vim.split(v1_parsed.prerelease, '.', { plain = true })
+  local v2_identifiers = vim.split(v2_parsed.prerelease, '.', { plain = true })
+  local i = 1
+  local max = math.max(vim.tbl_count(v1_identifiers), vim.tbl_count(v2_identifiers))
+  while i <= max do
+    local v1_identifier = v1_identifiers[i]
+    local v2_identifier = v2_identifiers[i]
+    if v1_identifier ~= v2_identifier then
+      local v1_num = tonumber(v1_identifier)
+      local v2_num = tonumber(v2_identifier)
+      local is_number = v1_num and v2_num
+      if is_number then
+        -- Number comparisons
+        if not v1_num and v2_num then
+          return -1
+        end
+        if v1_num and not v2_num then
+          return 1
+        end
+        if v1_num == v2_num then
+          return 0
+        end
+        if v1_num > v2_num then
+          return 1
+        end
+        if v1_num < v2_num then
+          return -1
+        end
+      else
+        -- String comparisons
+        if v1_identifier and not v2_identifier then
+          return 1
+        end
+        if not v1_identifier and v2_identifier then
+          return -1
+        end
+        if v1_identifier < v2_identifier then
+          return -1
+        end
+        if v1_identifier > v2_identifier then
+          return 1
+        end
+        if v1_identifier == v2_identifier then
+          return 0
+        end
+      end
+    end
+    i = i + 1
+  end
+
+  return 0
+end
+
+---@private
+--- Compares the version core component of the two versions.
+---@param v1_parsed table Parsed version.
+---@param v2_parsed table Parsed version.
+---@return integer `-1` if `v1_parsed < v2_parsed`, `0` if `v1_parsed == v2_parsed`, `1` if `v1_parsed > v2_parsed`.
+local function cmp_version_core(v1_parsed, v2_parsed)
+  if
+    v1_parsed.major == v2_parsed.major
+    and v1_parsed.minor == v2_parsed.minor
+    and v1_parsed.patch == v2_parsed.patch
+  then
+    return 0
+  end
+
+  if
+    v1_parsed.major > v2_parsed.major
+    or v1_parsed.minor > v2_parsed.minor
+    or v1_parsed.patch > v2_parsed.patch
+  then
+    return 1
+  end
+
+  return -1
+end
+
+--- Compares two strings (`v1` and `v2`) in semver format.
+---@param v1 string Version.
+---@param v2 string Version to be compared with v1.
+---@param 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`.
+function M.cmp(v1, v2, opts)
+  opts = opts or { strict = false }
+  local v1_parsed = M.parse(v1, opts)
+  local v2_parsed = M.parse(v2, opts)
+
+  local result = cmp_version_core(v1_parsed, v2_parsed)
+  if result == 0 then
+    result = cmp_prerelease(v1_parsed, v2_parsed)
+  end
+  return result
+end
+
+---@private
+---@param labels string Prerelease and build component of semantic version string e.g. "-rc1+build.0".
+---@return string|nil
+local function parse_prerelease(labels)
+  -- This pattern matches "-(alpha)+build.15".
+  -- '^%-[%w%.]+$'
+  local result = labels:match('^%-([%w%.]+)+.+$')
+  if result then
+    return result
+  end
+  -- This pattern matches "-(alpha)".
+  result = labels:match('^%-([%w%.]+)')
+  if result then
+    return result
+  end
+
+  return nil
+end
+
+---@private
+---@param labels string Prerelease and build component of semantic version string e.g. "-rc1+build.0".
+---@return string|nil
+local function parse_build(labels)
+  -- Pattern matches "-alpha+(build.15)".
+  local result = labels:match('^%-[%w%.]+%+([%w%.]+)$')
+  if result then
+    return result
+  end
+
+  -- Pattern matches "+(build.15)".
+  result = labels:match('^%+([%w%.]+)$')
+  if result then
+    return result
+  end
+
+  return nil
+end
+
+---@private
+--- Extracts the major, minor, patch and preprelease and build components from
+--- `version`.
+---@param version string Version string
+local function extract_components_strict(version)
+  local major, minor, patch, prerelease_and_build = version:match('^v?(%d+)%.(%d+)%.(%d+)(.*)$')
+  return tonumber(major), tonumber(minor), tonumber(patch), prerelease_and_build
+end
+
+---@private
+--- Extracts the major, minor, patch and preprelease and build components from
+--- `version`. When `minor` and `patch` components are not found (nil), coerce
+--- them to 0.
+---@param version string Version string
+local function extract_components_loose(version)
+  local major, minor, patch, prerelease_and_build = version:match('^v?(%d+)%.?(%d*)%.?(%d*)(.*)$')
+  major = tonumber(major)
+  minor = tonumber(minor) or 0
+  patch = tonumber(patch) or 0
+  return major, minor, patch, prerelease_and_build
+end
+
+---@private
+--- Validates the prerelease and build string e.g. "-rc1+build.0". If the
+--- prerelease, build or both are valid forms then it will return true, if it
+--- is not of any valid form, it will return false.
+---@param prerelease_and_build string
+---@return boolean
+local function is_prerelease_and_build_valid(prerelease_and_build)
+  if prerelease_and_build == '' then
+    return true
+  end
+  local has_build = parse_build(prerelease_and_build) ~= nil
+  local has_prerelease = parse_prerelease(prerelease_and_build) ~= nil
+  local has_prerelease_and_build = has_prerelease and has_build
+  return has_build or has_prerelease or has_prerelease_and_build
+end
+
+---@private
+---@param version string
+---@return string
+local function create_err_msg(version)
+  return string.format('invalid version: "%s"', version)
+end
+
+--- 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' }`
+---
+---@param version string Version string to be parsed.
+---@param 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.
+function M.parse(version, opts)
+  if type(version) ~= 'string' then
+    error(create_err_msg(version))
+  end
+
+  opts = opts or { strict = false }
+
+  version = vim.trim(version)
+
+  local extract_components = opts.strict and extract_components_strict or extract_components_loose
+  local major, minor, patch, prerelease_and_build = extract_components(version)
+
+  -- If major is nil then that means that the version does not begin with a
+  -- digit with or without a "v" prefix.
+  if major == nil or not is_prerelease_and_build_valid(prerelease_and_build) then
+    return nil
+  end
+
+  local prerelease = nil
+  local build = nil
+  if prerelease_and_build ~= nil then
+    prerelease = parse_prerelease(prerelease_and_build)
+    build = parse_build(prerelease_and_build)
+  end
+
+  return {
+    major = major,
+    minor = minor,
+    patch = patch,
+    prerelease = prerelease,
+    build = build,
+  }
+end
+
+---@private
+--- Throws an error if `version` cannot be parsed.
+---@param version string
+local function assert_version(version)
+  if M.parse(version) == nil then
+    error(create_err_msg(version))
+  end
+end
+
+---Returns `true` if `v1` are `v2` are equal versions.
+---@param version_1 string
+---@param version_2 string
+---@return boolean
+function M.eq(version_1, version_2)
+  assert_version(version_1)
+  assert_version(version_2)
+
+  return M.cmp(version_1, version_2) == 0
+end
+
+---Returns `true` if `v1` is less than `v2`.
+---@param version_1 string
+---@param version_2 string
+---@return boolean
+function M.lt(version_1, version_2)
+  assert_version(version_1)
+  assert_version(version_2)
+
+  return M.cmp(version_1, version_2) == -1
+end
+
+---Returns `true` if `v1` is greater than `v2`.
+---@param version_1 string
+---@param version_2 string
+---@return boolean
+function M.gt(version_1, version_2)
+  assert_version(version_1)
+  assert_version(version_2)
+
+  return M.cmp(version_1, version_2) == 1
+end
+
+setmetatable(M, {
+  __call = function()
+    return vim.fn.api_info().version
+  end,
+})
+
+return M