semver
Semantic Versioning 2.0.0: parse, compare, sort and match version ranges. Pure - no capabilities.
ecko get github.com/ecko-lang/semver
import semver
Pure computation: it declares no capabilities, so it cannot touch the network, the filesystem or the environment.
Version 0.38.0 - source - MIT.
parse(text)
Parse a version into { major, minor, patch, prerelease, build }.
prerelease is a list whose numeric identifiers are Ints and the rest Strings; build is a list of Strings. A leading v is not accepted.
errors: semver/bad_version when text is not a valid version; semver/out_of_range when a number does not fit in 64 bits; bug/bad_argument when text is not a string.
semver.parse("1.2.3-rc.1+build.5")
# {build: [build, 5], major: 1, minor: 2, patch: 3, prerelease: [rc, 1]}
valid(text)
Whether text is a valid version: the total form of parse.
A value that is not a string is not a version, so this returns false for it rather than raising.
semver.valid("01.1.1") # false - leading zero
string_of(p)
Render a parsed version back to text, build metadata included.
errors: bug/bad_argument when p is not a map parse returned.
semver.string_of(semver.parse("1.0.0-rc.1+exp")) # 1.0.0-rc.1+exp
compare(a, b)
-1, 0 or 1 as a is lower than, equal to or higher than b by precedence.
Accepts text or already-parsed versions. Build metadata is ignored, exactly as the spec requires (§10).
errors: semver/bad_version or semver/out_of_range when a version does not parse; bug/bad_argument when an argument is neither a string nor a parsed version.
semver.compare("1.0.0-alpha", "1.0.0") # -1
sort(versions)
The versions in ascending order of precedence; versions of equal precedence keep their input order.
errors: semver/bad_version when an entry does not parse; bug/bad_argument when versions is not a list.
semver.sort(["2.0.0", "1.0.0-rc.1", "1.0.0"]) # [1.0.0-rc.1, 1.0.0, 2.0.0]
eq(a, b)
Whether a and b have equal precedence (build metadata ignored).
errors: as compare.
semver.eq("1.0.0+a", "1.0.0+b") # true
gt(a, b)
Whether a has higher precedence than b.
errors: as compare.
semver.gt("1.0.1", "1.0.0") # true
lt(a, b)
Whether a has lower precedence than b.
errors: as compare.
semver.lt("1.0.0-rc.1", "1.0.0") # true
inc(text, part)
The next version after text for part, one of "major", "minor" or "patch".
Bumping drops build metadata and any pre-release. A pre-release already comes before its release, so bumping one lands on that release when the parts below part are zero, as npm does: 1.2.0-rc.1 bumped by minor is 1.2.0, 2.0.0-rc.1 bumped by major is 2.0.0, and 1.2.3-rc.1 bumped by patch is 1.2.3.
errors: semver/bad_version when text does not parse; semver/out_of_range when the bumped number would pass 64 bits; bug/bad_argument when part is not one of the three.
semver.inc("1.2.3", "minor") # 1.3.0
semver.inc("1.2.0-rc.1", "minor") # 1.2.0
parse_range(text)
Expand a range into its alternatives, each a list of { op, version } comparators, where op is one of ">=", ">", "<=", "<" or "=".
^ and ~ expand to a pair of bounds and * to >=0.0.0. This is the form satisfies evaluates, exposed for inspection.
errors: semver/bad_range when the range or an alternative is empty or an operator has no version; semver/unsupported_range for a hyphen range or a partial or x-range version; semver/bad_version or semver/out_of_range when a version does not parse; bug/bad_argument when text is not a string.
semver.parse_range("^1.2.3")
# [[{op: >=, version: 1.2.3}, {op: <, version: 2.0.0}]]
satisfies(version, range)
Whether version falls inside range.
A pre-release only ever matches a range that names a pre-release on the same major.minor.patch. Without that rule ^1.0.0 would quietly accept 2.0.0-alpha, which is the behaviour every package ecosystem regrets.
errors: as parse_range for the range; semver/bad_version when version does not parse; bug/bad_argument when either is not a string.
semver.satisfies("1.9.3", "^1.2.0") # true
max_satisfying(versions, range)
The highest version in versions that satisfies range, or null.
Entries that are not valid versions, such as a latest tag or a v1.2.0 with its prefix, are skipped rather than raising.
errors: as parse_range for the range; bug/bad_argument when versions is not a list.
semver.max_satisfying(["1.0.0", "1.4.2", "2.0.0", "latest"], "^1.0.0") # 1.4.2
min_satisfying(versions, range)
The lowest version in versions that satisfies range, or null.
Entries that are not valid versions are skipped, as in max_satisfying.
errors: as max_satisfying.
semver.min_satisfying(["1.0.0", "1.4.2", "2.0.0"], "^1.1.0") # 1.4.2