l0.DependencyControl.SemanticVersion¶

MoonScriptLua

SemanticVersion = require "l0.DependencyControl.SemanticVersion"

local SemanticVersion = require("l0.DependencyControl.SemanticVersion")

SemanticVersion ¶

A semantic version value (major.minor.patch) plus the static semantic-versioning utilities. Construct one from a version string or from numeric components; instances compare with </==, stringify to "major.minor.patch", and bump. The static helpers additionally accept an instance wherever they take a number|string version. Packed integers are an internal encoding, exposed only via fromPacked/toPacked.

Constructor ¶

MoonScriptLua

semanticVersion = SemanticVersion major, minor, patch

local semanticVersion = SemanticVersion(major, minor, patch)

minor and patch supplied as the next two arguments. Raises on an invalid string or component.

param	type	description
major	`integer`\|`string`	A full version string ("1.2.3"), or the major version (0-255) with the
minor?	`integer`	The minor version (0-255); ignored when the first argument is a string.
patch?	`integer`	The patch version (0-255); ignored when the first argument is a string.

Instance methods¶

toPacked ¶

MoonScriptLua

semanticVersion\toPacked!

semanticVersion:toPacked()

Returns:

packed integer — This version in the internal packed encoding (major<<16 | minor<<8 | patch).

satisfies ¶

MoonScriptLua

semanticVersion\satisfies range

semanticVersion:satisfies(range)

Reports whether this version satisfies an npm-style range (see the static parseRange for the syntax).

param	type	description
range	`string`	The version range.

Returns:

satisfies boolean? — True/false, or nil on a malformed range.
err string? — Error message on a malformed range.

bumpMajor ¶

MoonScriptLua

semanticVersion\bumpMajor!

semanticVersion:bumpMajor()

Returns:

bumped SemanticVersion — A new version with the major incremented and minor/patch reset to 0.

bumpMinor ¶

MoonScriptLua

semanticVersion\bumpMinor!

semanticVersion:bumpMinor()

Returns:

bumped SemanticVersion — A new version with the minor incremented and patch reset to 0.

bumpPatch ¶

MoonScriptLua

semanticVersion\bumpPatch!

semanticVersion:bumpPatch()

Returns:

bumped SemanticVersion — A new version with the patch incremented.

Class methods¶

toString ¶

MoonScriptLua

SemanticVersion\toString version, precision

SemanticVersion:toString(version, precision)

Converts a version number, string, or instance to a semantic version string.

param	type	description
version	`number`\|`string`\|SemanticVersion\|`nil`	The version as a packed number, a string, an instance, or nil (rendered as "0.0.0").
precision?	SemverPrecision

Returns:

versionString string|nil
err string|nil

fromPacked ¶

MoonScriptLua

SemanticVersion.fromPacked packed

SemanticVersion.fromPacked(packed)

Builds a version from the internal packed encoding (as returned by toPacked). Raises on a value outside [0, 0xFFFFFF]. Call as a plain static (SemanticVersion.fromPacked packed).

param	type	description
packed	`integer`	A packed version in [0, 0xFFFFFF].

Returns:

version SemanticVersion — The version the packed integer encodes.

parse ¶

MoonScriptLua

SemanticVersion.parse str

SemanticVersion.parse(str)

Parses a version string into an instance without raising, for untrusted input (the constructor raises instead). Call as a plain static (SemanticVersion.parse str).

param	type	description
str	`string`	The version string (e.g. "1.2.3").

Returns:

version SemanticVersion? — The parsed version, or nil on error.
err string? — Error message if parsing failed.

check ¶

MoonScriptLua

SemanticVersion\check a, b, precision

SemanticVersion:check(a, b, precision)

Checks whether version a is greater than or equal to version b, up to the given precision. When precision is "range", b is instead an npm-style version range string and the result is whether a satisfies that range (see satisfiesRange).

param	type	description
a	`number`\|`string`	The first version.
b	`number`\|`string`	The second version, or an npm-style range string when precision is "range".
precision?	SemverPrecision	Precision to compare at (default "patch").

Returns:

result boolean? — True if a satisfies b, or nil on error.
masked number|string — The masked value of b on success (absent for ranges), or the error message on failure.

parseRange ¶

MoonScriptLua

SemanticVersion\parseRange range

SemanticVersion:parseRange(range)

Parses an npm-style version range into its set of half-open integer intervals [min,max) (mininclusive, max exclusive). Supports the following range syntax: * comparators: >=1.2.7, <=1.2.7, >1.2.7, <1.2.7, =1.2.7 * intersection: >=1.2.7 <1.3.0 * union: >=1.2.7 <1.3.0 || >=1.4.0 <2.0.0 * hyphen ranges: 1.2 - 2.3 * X-ranges: 1.x, * * tilde ranges: ~1.2.3 * caret ranges: ^1.2.3 An unsatisfiable range (e.g. >2 <1) yields an empty list. Pre-release/build labels are not supported at this time.

param	type	description
range	`string`	The version range.

Returns:

intervals SemverInterval[]? — The range's intervals, or nil on a malformed range.
err string? — Error message on failure.

satisfiesRange ¶

MoonScriptLua

SemanticVersion\satisfiesRange version, range

SemanticVersion:satisfiesRange(version, range)

Reports whether a version satisfies an npm-style semver range.

param	type	description
version	`number`\|`string`	The version to test.
range	`string`	The version range.

Returns:

satisfies boolean? — True/false, or nil on error (a malformed version or range).
err string? — Error message on failure.

rangesIntersect ¶

MoonScriptLua

SemanticVersion\rangesIntersect rangeA, rangeB

SemanticVersion:rangesIntersect(rangeA, rangeB)

Reports whether two npm-style version ranges overlap for at least one version.

param	type	description
rangeA	`string`	The first version range.
rangeB	`string`	The second version range.

Returns:

intersect boolean? — True/false, or nil on error (a malformed range).
err string? — Error message on failure.

getRangeMaxVersion ¶

MoonScriptLua

SemanticVersion\getRangeMaxVersion range

SemanticVersion:getRangeMaxVersion(range)

Returns the highest version that satisfies an npm-style range.

param	type	description
range	`string`	The version range.

Returns:

version number? — The greatest satisfying version, or nil on an unsatisfiable range or a malformed one.
err string? — Error message on a malformed range.

isHigher ¶

MoonScriptLua

SemanticVersion.isHigher version, reference

SemanticVersion.isHigher(version, reference)

Reports whether version is strictly higher than reference. Raises on invalid input. Call as a plain static (SemanticVersion.isHigher a, b), e.g. as a table.sort comparator.

param	type	description
version	`number`\|`string`
reference	`number`\|`string`

Returns:

boolean

isLower ¶

MoonScriptLua

SemanticVersion.isLower version, reference

SemanticVersion.isLower(version, reference)

Reports whether version is strictly lower than reference. Raises on invalid input. Call as a plain static (SemanticVersion.isLower a, b), e.g. as a table.sort comparator.

param	type	description
version	`number`\|`string`
reference	`number`\|`string`

Returns:

boolean

Fields¶

field	type	description
major	`integer`	The major version (0-255).
minor	`integer`	The minor version (0-255).
patch	`integer`	The patch version (0-255).

Types¶

SemverPrecision ¶

value	description
`"major"`
`"minor"`
`"patch"`
`"range"`	compare `b` as an npm-style version range string instead of as a version

ComparisonOperator ¶

A version comparison operator (the value of a ComparisonOperator enum member).

value	description
`">"`	GT: greater than
`">="`	GTE: greater than or equal
`"<"`	LT: less than
`"<="`	LTE: less than or equal
`"="`	EQ: equal

PartialVersion ¶

A semantic version parsed into its specified components; an absent or wildcard (x/*) component is nil.

field	type	description
major?	`integer`
minor?	`integer`
patch?	`integer`

SemverComparator ¶

A single version comparator: an operator and the encoded version it compares against.

field	type	description
op	ComparisonOperator
num	`integer`	The encoded version (see encodeVersion) the operator compares against.

SemverInterval ¶

A half-open version interval [min, max): min inclusive, max exclusive (both encoded versions).

field	type	description
min	`integer`	Inclusive lower bound (encoded version).
max	`integer`	Exclusive upper bound (encoded version).