SemVer API

Version parsing, validation, comparison, and bumping helpers live under ptool.semver and p.semver.

ptool.semver.parse

v0.1.0 - Introduced.

ptool.semver.parse(version) parses a version string and returns a Version object.

• version (string, required): A semantic version string, optionally prefixed with v.

Example:

local v = ptool.semver.parse("v1.2.3-alpha.1+build.9")
print(v.major, v.minor, v.patch)
print(v.pre, v.build)
print(tostring(v))

ptool.semver.is_valid

v0.1.0 - Introduced.

ptool.semver.is_valid(version) checks whether a version string is valid.

• version (string, required): A semantic version string.
• Returns: boolean.

print(ptool.semver.is_valid("1.2.3")) -- true
print(ptool.semver.is_valid("x.y.z")) -- false

ptool.semver.compare

v0.1.0 - Introduced.

ptool.semver.compare(a, b) compares two versions.

• a / b (string|Version, required): A version string or a Version object.
• Returns: -1 | 0 | 1.

print(ptool.semver.compare("1.2.3", "1.2.4")) -- -1

ptool.semver.bump

v0.1.0 - Introduced.

ptool.semver.bump(v, op[, channel]) returns a new version object after applying the bump.

• v (string|Version, required): The original version.
• op (string, required): One of major, minor, patch, release, alpha, beta, rc, prepatch, preminor, or premajor.
• channel (string, optional): Supported only for prepatch, preminor, and premajor. Must be one of alpha, beta, or rc. Defaults to alpha.
• Returns: Version.

local v = ptool.semver.bump("1.2.3", "alpha")
print(tostring(v)) -- 1.2.4-alpha.1

local next_minor_rc = ptool.semver.bump("1.2.3", "preminor", "rc")
print(tostring(next_minor_rc)) -- 1.3.0-rc.1

local stable = ptool.semver.bump("1.2.4-rc.2", "release")
print(tostring(stable)) -- 1.2.4

Version

v0.1.0 - Introduced.

Version represents a parsed semantic version returned by ptool.semver.parse(...) or ptool.semver.bump(...).

It is implemented as a Lua userdata.

Fields and methods:

• Fields:
  • major (integer)
  • minor (integer)
  • patch (integer)
  • pre (string|nil)
  • build (string|nil)
• Methods:
  • v:compare(other) -> -1|0|1
  • v:bump(op[, channel]) -> Version
  • v:to_string() -> string
• Metamethods:
  • tostring(v) is available.
  • ==, <, and <= comparisons are supported.

compare

Canonical API name: ptool.semver.Version:compare.

v:compare(other) compares the current version with other.

• other (string|Version, required): A version string or another Version object.
• Returns: -1 | 0 | 1.

bump

Canonical API name: ptool.semver.Version:bump.

v:bump(op[, channel]) returns a new Version object after applying the bump.

• op (string, required): One of major, minor, patch, release, alpha, beta, rc, prepatch, preminor, or premajor.
• channel (string, optional): Supported only for prepatch, preminor, and premajor. Must be one of alpha, beta, or rc. Defaults to alpha.
• Returns: Version.

to_string

Canonical API name: ptool.semver.Version:to_string.

v:to_string() returns the canonical string form of the version.

• Returns: string.

Prerelease bump rules:

• Bumping a stable version to alpha, beta, or rc first increments the patch version, then enters the target channel starting from .1.
• prepatch, preminor, and premajor start a fresh prerelease from the next patch, minor, or major version respectively, such as 1.2.3 -> 1.3.0-rc.1 with preminor + rc.
• Bumping within the same channel increments the sequence number, such as alpha.1 -> alpha.2.
• release removes prerelease and build metadata while keeping the same major.minor.patch values, such as 1.2.3-rc.2 -> 1.2.3.
• Channel promotion is allowed (alpha -> beta -> rc), but channel downgrade is not (for example, rc -> beta raises an error).