semver #

Description

semver is a library for processing versions, that use the semver format.

Examples

import semver

fn main() {
    ver1 := semver.from('1.2.4') or {
        println('Invalid version')
        return
    }
    ver2 := semver.from('2.3.4') or {
        println('Invalid version')
        return
    }
    println(ver1 > ver2)
    println(ver2 > ver1)
    println(ver1.satisfies('>=1.1.0 <2.0.0'))
    println(ver2.satisfies('>=1.1.0 <2.0.0'))
    println(ver2.satisfies('>=1.1.0 <2.0.0 || >2.2.0'))
}

false
true
true
false
true

For more details see semver.v file.

Tilde ranges allow changes to the patch when a minor is specified: ~2.0 and ~2.0.0 mean >=2.0.0 <2.1.0. A bare major such as ~2 allows minor changes up to 3.0.0.

Comparison operators accept wildcard or missing version components. For example, >=1.x means >=1.0.0, >1.x means >=2.0.0, and <=1.2.x stops before 1.3.0, including its prereleases. Wildcard or partial comparators can be combined with other comparators in any order, as in >=1.x <2.0.0 or >=0.0.0 >1.2. Wildcard components must be whole x, X, or * tokens. Prerelease tags on wildcard ranges do not change their release floor; for example, >=1.2.x-beta.1 starts at 1.2.0 and does not admit 1.2.0-beta.1.

Malformed comparator sets return a descriptive parse error when range expansion fails.

Each whitespace-separated operand in a comparator set is evaluated and intersected with the others. Partial versions and wildcards describe a series: 1.2 and 1.2.x cover all stable versions from 1.2.0 up to 1.3.0. Operators apply to those series, so >=1.2 includes 1.2.0, <=1.2 includes 1.2.9, and >1.2 starts at 1.3.0. A wildcard major with =, >=, or <= accepts every stable version; <* and >* accept none.

Prereleases require an explicit prerelease comparator with the same major, minor, and patch in that set. Advanced ranges keep their exclusive ceiling at the next series' -0 boundary, so adding a prerelease comparator cannot admit the next series. Hyphens inside prerelease identifiers and wildcard letters in build metadata are literal characters.

Reporting malformed ranges

Version.satisfies(range) returns false when a range cannot be parsed. Use Version.satisfies_or_error(range) to distinguish an invalid range from a valid range that does not match. semver.is_valid_range(range) checks the range syntax without choosing a version. An empty range is valid and matches every release version. It follows the normal prerelease exclusion rule described above.

import semver

fn main() {
    version := semver.from('1.2.3')!
    assert version.satisfies_or_error('^1.0.0')!
    assert !version.satisfies_or_error('^2.0.0')!
    assert semver.is_valid_range('')
    assert !semver.is_valid_range('not-a-version')
}

fn build(major int, minor int, patch int) Version

build returns a Version structure with given major, minor and patch versions.

fn coerce(input string) !Version

fn from(input string) !Version

• Constructor. from returns a Version structure parsed from input string.

fn is_valid(input string) bool

is_valid returns true if the input string can be converted to a (semantic) Version struct.

fn is_valid_range(input string) bool

is_valid_range reports whether input parses as a range at all. It exists so a caller can reject a broken constraint before it is used, rather than discovering the problem as a result that looks like a genuine miss.

fn Increment.from[W](input W) !Increment

from returns the Increment value of an integer or of a field name, or an error if there is none.

fn (err EmptyInputError) msg() string

fn (err InvalidVersionFormatError) msg() string

enum Increment {
	major
	minor
	patch
}

Increment represents the different types of version increments.

struct Version {
pub:
	major      int
	minor      int
	patch      int
	prerelease string
	metadata   string
}

• Structures. Version represents a semantic version in semver format.

fn (ver Version) increment(typ Increment) Version

increment returns a Version structure with incremented values.

fn (ver Version) satisfies(input string) bool

satisfies returns true if the input expression can be validated to true when run against this Version.

assert semver.build(1,0,0).satisfies('<=2.0.0')

assert semver.build(1,0,0).satisfies('>=2.0.0') == false

fn (ver Version) satisfies_or_error(input string) !bool

satisfies_or_error is satisfies, but it reports an unparseable range as an error rather than as a miss, so a caller can tell a broken constraint from a genuine one. satisfies keeps returning false for that case, because changing it would break every caller at once and the ones that need the distinction can move over.

fn (v1 Version) == (v2 Version) bool

== checks if v1 is equal to v2.

fn (v1 Version) < (v2 Version) bool

< checks if v1 is less than v2.

fn (ver Version) str() string

str returns the string representation of the Version.