moonsverSemantic Versioning 2.0.0 for MoonBit

API reference

moonsver

Every public value, type and method of moonbitstack/moonsver. Import it as @moonsver. Signatures are the package interface, in declaration order.

Functions 1

Values that are not tied to a type.

fnsatisfies#

pub fn satisfies(String, String, syntax? : Syntax) -> Bool raise Refused

Convenience wrapper: parse two strings and check whether the version satisfies.

Both strings are read with the same grammar, the version through Version::parse.

Errors 1

One error type, raised by every parser.

suberrorRefused#

Why a version or a range was refused, and where.

at is the zero-based character index of the first offending character, or the input's length when it ended early; the message says what was expected.

pub(all) suberror Refused {
  • Empty(at~ : Int32, String)Empty input where the grammar wants a version or a range.
  • Unexpected(at~ : Int32, String)A character that does not belong where it stands.
  • Truncated(at~ : Int32, String)The input ended partway through.
  • Number(at~ : Int32, String)A numeric component that is not a number.
  • LeadingZero(at~ : Int32, String)A numeric component, or a numeric prerelease identifier, with a leading zero (SemVer 2.0.0 §2, §9).
  • EmptyIdentifier(at~ : Int32, String)An empty identifier, as in 1.0.0- or 1.0.0-a..b.
  • Identifier(at~ : Int32, String)An identifier with characters §9 and §10 do not allow.
  • Unsupported(at~ : Int32, String)A spelling the chosen Syntax does not accept.
  • Range(at~ : Int32, String)A range that does not hang together, such as a concrete part after a wildcard.

Implements Show.

atmethod#
pub fn Refused::at(Self) -> Int32

Where the input went wrong.

messagemethod#
pub fn Refused::message(Self) -> String

What was wrong, in words.

to_stringmethod#
pub fn Refused::to_string(Self) -> String

The canonical text form, from Show.

Types 11

The values the package works with.

structComparator#

One comparator: an operator and a full version.

Build metadata is dropped from comparators (>=1.2.3+build is >=1.2.3), since it takes no part in precedence.

pub(all) struct Comparator {
  • op : Op
  • version : Version

Implements Eq, Show.

to_stringmethod#
pub fn Comparator::to_string(Self) -> String

The canonical text form, from Show.

structComparatorSet#

A conjunction (AND) of comparators. An empty list means "any version".

pub(all) struct ComparatorSet {
  • comparators : Array[Comparator]

Implements Eq, Show.

to_stringmethod#
pub fn ComparatorSet::to_string(Self) -> String

The canonical text form, from Show.

enumDefaultOp#

What a bare version means when no operator is given.

pub(all) enum DefaultOp {
  • ExactExact: 1.2.3 means =1.2.3, which is how npm and Ruby read it.
  • CaretCaret: 1.2.3 means ^1.2.3, Cargo's default.
  • TildeTilde: 1.2.3 means ~1.2.3.

Implements Eq.

enumIdentifier#

A version identifier.

SemVer 2.0.0 allows two kinds of identifier: all digits, or a string drawn from [0-9A-Za-z-]. Numeric ones are held as arbitrary-precision integers, so a value such as 18446744073709551616 does not overflow.

pub(all) enum Identifier {
  • Num(@bigint.BigInt)A numeric identifier, normalised to carry no leading zeroes.
  • Alpha(String)An alphanumeric identifier, kept verbatim.

Implements Compare, Eq, Hash, Show.

alphamethod#
pub fn Identifier::alpha(String) -> Self
as_bigintmethod#
pub fn Identifier::as_bigint(Self) -> @bigint.BigInt?

The integer value, or None for an alphanumeric identifier.

as_intmethod#
pub fn Identifier::as_int(Self) -> Int32?

The value as an Int, or None if it is alphanumeric or out of range.

comparemethod#
pub fn Identifier::compare(Self, Self) -> Int32

A total order that sort uses: precedence first, then build metadata.

is_numericmethod#
pub fn Identifier::is_numeric(Self) -> Bool
numericmethod#
pub fn Identifier::numeric(Int32) -> Self
to_stringmethod#
pub fn Identifier::to_string(Self) -> String

The canonical text form, from Show.

enumOp#

A comparison operator.

pub(all) enum Op {
  • EqEquals =
  • NeNot equal !=, which only grammars such as Syntax::ruby() accept
  • GtGreater than >
  • GeGreater than or equal >=
  • LtLess than <
  • LeLess than or equal <=

Implements Eq, Show.

to_stringmethod#
pub fn Op::to_string(Self) -> String

The canonical text form, from Show.

enumPrereleasePolicy#

How prereleases are matched against a range.

The spec only orders prereleases against each other; it says nothing about how a range should treat them, so every ecosystem settled on its own convention.

pub(all) enum PrereleasePolicy {
  • SameTupleThe npm and Cargo convention: a prerelease can only satisfy a set when some comparator carries a prerelease with the same major.minor.patch. So >=1.2.3-alpha takes 1.2.3-beta but not 1.2.4-beta, and * takes no prerelease at all.
  • AlwaysTreat prereleases as ordinary versions (npm's includePrerelease).
  • NeverPrereleases never match anything, for when only stable releases will do.

Implements Eq.

structRange#

A version range: a disjunction (OR) of comparator sets.

A Range is the parsed, normalised structure rather than the original string. ^1.2.3, for instance, becomes the set >=1.2.3, <2.0.0.

pub struct Range {

Implements Eq, Show, ToJson.

anymethod#
pub fn Range::any() -> Self

A range matching any stable version, the same as *.

parsemethod#
pub fn Range::parse(String, syntax? : Syntax) -> Self raise Refused

Parse a version range.

npm's grammar is the default; pass syntax= for Cargo, Ruby or strict.

from_jsonmethod#
pub fn Range::from_json(Json, @json.JsonPath) -> Self raise @json.JsonDecodeError

Read back from a JSON string, through the same parser.

is_anymethod#
pub fn Range::is_any(Self) -> Bool

Whether this is equivalent to "any version".

max_satisfyingmethod#
pub fn Range::max_satisfying(Self, Array[Version]) -> Version?

The highest satisfying version, by precedence, with build metadata breaking ties.

min_satisfyingmethod#
pub fn Range::min_satisfying(Self, Array[Version]) -> Version?

The lowest satisfying version.

policymethod#
pub fn Range::policy(Self) -> PrereleasePolicy

The prerelease policy this range was parsed with.

satisfiesmethod#
pub fn Range::satisfies(Self, Version) -> Bool

Does the version fall inside the range?

The prerelease policy comes from the Syntax used to parse the range.

satisfies_withmethod#
pub fn Range::satisfies_with(Self, Version, PrereleasePolicy) -> Bool

Does the version fall inside the range, with the policy overridden for this call?

satisfyingmethod#
pub fn Range::satisfying(Self, Array[Version]) -> Array[Version]

Every satisfying version, sorted ascending by precedence.

setsmethod#
pub fn Range::sets(Self) -> ArrayView[ComparatorSet]

The disjuncts, one per || branch.

to_jsonmethod#
pub fn Range::to_json(Self) -> Json

Serialise as a JSON string.

to_stringmethod#
pub fn Range::to_string(Self) -> String

The canonical text form, from Show.

enumRelease#

The kind of bump to apply.

Several corners are easy to miss: the major bump of 1.0.0-pre is 1.0.0.

pub(all) enum Release {
  • Major1.2.3 → 2.0.0；1.0.0-pre → 1.0.0
  • Minor1.2.3 → 1.3.0；1.2.0-pre → 1.2.0
  • Patch1.2.3 → 1.2.4；1.2.3-pre → 1.2.3
  • PreMajor1.2.3 → 2.0.0-0
  • PreMinor1.2.3 → 1.3.0-0
  • PrePatch1.2.3 → 1.2.4-0
  • PrereleaseBump the last numeric identifier, or raise the patch and append -0 if there is none
  • StableDrop the prerelease, leaving the numbers alone

Implements Show.

parsemethod#
pub fn Release::parse(String) -> Self?

Parse a bump name, for the CLI.

to_stringmethod#
pub fn Release::to_string(Self) -> String

The canonical text form, from Show.

structSyntax#

Range grammar settings.

A version has one spelling in SemVer 2.0.0, but ranges are not in the spec, and different ecosystems settled on different rules. Their differences are settings here, so one parser can read several grammars.

Switches that govern version literals:

  • allow_v_prefix: accept v1.2.3
  • allow_equals_prefix: accept =1.2.3 as a version literal
  • allow_build_metadata: accept a +build segment
  • trim: allow whitespace around a version literal

Switches that govern range syntax:

  • default_op: what a bare version means (npm Exact, Cargo Caret)
  • tilde_bump: how ~ finds its upper bound (npm/Cargo Patch, Ruby LastSpecified)
  • allow_caret / allow_tilde: accept ^ / ~ (~> only under LastSpecified)
  • allow_ne: accept !=
  • allow_or: accept ||
  • allow_hyphen_range: accept 1.2.3 - 2.0.0
  • allow_xrange: accept the shorthand forms 1.x, 1.2.* and bare 1.2
  • allow_empty: whether an empty string means "any version"
  • prerelease_policy: how prereleases are matched
pub(all) struct Syntax {
  • allow_v_prefix : Bool
  • allow_equals_prefix : Bool
  • allow_build_metadata : Bool
  • trim : Bool
  • default_op : DefaultOp
  • tilde_bump : TildeBump
  • allow_caret : Bool
  • allow_tilde : Bool
  • allow_ne : Bool
  • allow_or : Bool
  • allow_hyphen_range : Bool
  • allow_xrange : Bool
  • allow_empty : Bool
  • prerelease_policy : PrereleasePolicy

Implements Default, Eq, Show.

cargomethod#
pub fn Syntax::cargo() -> Self

Cargo grammar: a bare version carries a caret (1.2.3 is ^1.2.3), with , or space for conjunctions and * / 1.* wildcards; no ||, no hyphen ranges, no v.

defaultmethod#
pub fn Syntax::default() -> Self
from_namemethod#
pub fn Syntax::from_name(String) -> Self?

Look up a preset by name, for the CLI and config files.

npmmethod#
pub fn Syntax::npm() -> Self

npm grammar: a bare version is exact, with ^, ~, ||, hyphen ranges, 1.x shorthand, a v prefix, and the empty string for "any".

rubymethod#
pub fn Syntax::ruby() -> Self

Ruby grammar: ~> is the pessimistic operator (drop the last segment, then bump), and != is allowed; no ^, ||, hyphen ranges or shorthand.

strictmethod#
pub fn Syntax::strict() -> Self

Strict SemVer 2.0.0 spelling: only = > >= < <=, joined by commas or spaces, with no ^, ~, ||, hyphen ranges, 1.x shorthand or v prefix.

The one exception is *, which always means "any version": it is what Range::to_string prints for an empty range, so refusing it would break the round trip.

namemethod#
pub fn Syntax::name(Self) -> String?

The preset name for this syntax, or None for a custom mix.

to_stringmethod#
pub fn Syntax::to_string(Self) -> String

The canonical text form, from Show.

enumTildeBump#

How ~ and ~> work out their upper bound.

pub(all) enum TildeBump {
  • Patchnpm and Cargo: bump the minor if one was written, otherwise bump the major. - ~1.2.3 → >=1.2.3 <1.3.0 - ~1.2 → >=1.2.0 <1.3.0 - ~1 → >=1.0.0 <2.0.0
  • LastSpecifiedRuby's ~>: drop the last segment, then bump whatever is left. - ~> 1.2.3 → >=1.2.3 <1.3.0 - ~> 1.2 → >=1.2.0 <2.0.0 - ~> 1 → >=1.0.0 <2.0.0

Implements Eq.

structVersion#

A SemVer 2.0.0 version.

The three numbers are arbitrary-precision integers, so 18446744073709551616.0.0 parses, prints and compares exactly, well past 64 bits.

The fields are private and only Version::new / Version::parse can build one, so a version never carries a leading zero or a malformed identifier list.

pub struct Version {

Implements Compare, Eq, Hash, Show, ToJson.

from_bigintmethod#
pub fn Version::from_bigint(@bigint.BigInt, @bigint.BigInt, @bigint.BigInt) -> Self

Build a version from three arbitrary-precision integers.

newmethod#
pub fn Version::new(Int32, Int32, Int32) -> Self

Build a version from three Ints, with no prerelease and no build metadata.

parsemethod#
pub fn Version::parse(String, syntax? : Syntax) -> Self raise Refused

Parse a version.

The npm grammar is the default, so v1.2.3, =1.2.3 and surrounding whitespace are all fine. Pass syntax=Syntax::strict() to hold to the spec exactly.

buildmethod#
pub fn Version::build(Self) -> ArrayView[String]

The build metadata identifiers: ["build", "5"] for 1.2.3+build.5.

comparemethod#
pub fn Version::compare(Self, Self) -> Int32

A total order that sort uses: precedence first, then build metadata.

coremethod#
pub fn Version::core(Self) -> Self

Keep the three numbers only, dropping prerelease and build metadata.

core_stringmethod#
pub fn Version::core_string(Self) -> String

The major.minor.patch form, without prerelease or build metadata.

from_jsonmethod#
pub fn Version::from_json(Json, @json.JsonPath) -> Self raise @json.JsonDecodeError

Read back from a JSON string, through the same parser.

incmethod#
pub fn Version::inc(Self, Release) -> Self

Apply a bump.

is_prereleasemethod#
pub fn Version::is_prerelease(Self) -> Bool

Whether the version carries a prerelease.

is_stablemethod#
pub fn Version::is_stable(Self) -> Bool

Whether this is a stable release. Build metadata does not make it unstable.

majormethod#
pub fn Version::major(Self) -> @bigint.BigInt

The major number.

minormethod#
pub fn Version::minor(Self) -> @bigint.BigInt

The minor number.

patchmethod#
pub fn Version::patch(Self) -> @bigint.BigInt

The patch number.

precedence_cmpmethod#
pub fn Version::precedence_cmp(Self, Self) -> Int32

Compare precedence as laid out in SemVer 2.0.0 §11.

Returns -1, 0 or 1. **Build metadata takes no part**: 1.0.0+a and 1.0.0+b share the same precedence.

prereleasemethod#
pub fn Version::prerelease(Self) -> ArrayView[Identifier]

The prerelease identifiers: ["alpha", 1] for 1.2.3-alpha.1.

same_coremethod#
pub fn Version::same_core(Self, Self) -> Bool

Whether the three numbers match, ignoring prerelease and build metadata.

to_jsonmethod#
pub fn Version::to_json(Self) -> Json

Serialise as a JSON string.

to_stringmethod#
pub fn Version::to_string(Self) -> String

The canonical text form, from Show.