`(sigil version)`

(sigil version) - Semantic Versioning

Parse, compare, and check version constraints using semantic versioning (semver 2.0.0). Useful for package management and compatibility checks.

(import (sigil version))

(define v (parse-version "1.2.3-alpha.1"))
(version-major v)  ; => 1
(version<? v (parse-version "1.2.4"))  ; => #t

;; Check version constraints
(version-satisfies? v ">= 1.0.0")  ; => #t
(version-satisfies? v "^1.2.0")    ; => #t (compatible)

Version Format

Versions follow the pattern: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

MAJOR: Incremented for breaking changes
MINOR: Incremented for new features (backwards compatible)
PATCH: Incremented for bug fixes
PRERELEASE: Optional pre-release identifier (e.g., alpha.1)
BUILD: Optional build metadata (ignored in comparisons)

Constraint Operators

Operator	Example	Meaning
(none)	`1.2.3`	Exact version
`=`	`= 1.2.3`	Exact version
`>`	`> 1.2.3`	Greater than
`>=`	`>= 1.2.3`	Greater than or equal
`<`	`< 1.2.3`	Less than
`<=`	`<= 1.2.3`	Less than or equal
`^`	`^1.2.3`	Compatible (same major, >= given)
`~`	`~1.2.3`	Approximately (same major.minor, >= given)
`*`	`*`	Any version

Exports

versionprocedure

A semantic version with major, minor, patch, prerelease, and build components.

(version major: 1 minor: 2 patch: 3)
(version major: 2 minor: 0 patch: 0 prerelease: '("alpha" 1))
(version major: 1 minor: 0 patch: 0 build: "20240101")

version?procedure

Test if a value is a version struct.

version-majorprocedure

Major version number. Breaking changes increment this.

version-minorprocedure

Minor version number. New features increment this.

version-patchprocedure

Patch version number. Bug fixes increment this.

version-prereleaseprocedure

Pre-release identifiers as a list of strings or integers, or #f for stable releases. Example: '("alpha" 1) for version 1.0.0-alpha.1

version-buildprocedure

Build metadata string, or #f if none. Not used in version comparison. Example: "20240101" for version 1.0.0+20240101

parse-versionprocedure

Parse a version string into a version record.

Returns #f if the string is not a valid version. Accepts optional leading v or V prefix.

(parse-version "1.2.3")           ; => <version 1.2.3>
(parse-version "v2.0.0-beta.1")   ; => <version 2.0.0-beta.1>
(parse-version "1.0.0+build.42")  ; => <version 1.0.0+build.42>
(parse-version "invalid")         ; => #f

string->versionvariable

Alias for parse-version.

version->stringprocedure

Convert a version to its string representation.

(version->string (parse-version "1.2.3-alpha"))
; => "1.2.3-alpha"

version-compareprocedure

Compare two versions.

Returns -1 if a < b, 0 if a = b, 1 if a > b. Build metadata is ignored per semver spec.

(version-compare (parse-version "1.0.0")
                 (parse-version "2.0.0"))  ; => -1

version=?procedure

Test if two versions are equal.

(version=? (parse-version "1.0.0")
           (parse-version "1.0.0"))  ; => #t

version<?procedure

Test if version a is less than version b.

version>?procedure

Test if version a is greater than version b.

version<=?procedure

Test if version a is less than or equal to version b.

version>=?procedure

Test if version a is greater than or equal to version b.

parse-constraintprocedure

Parse a version constraint string.

Returns a constraint record or #f if invalid.

(parse-constraint ">= 1.0.0")  ; => (>= <version>)
(parse-constraint "^2.0.0")    ; => (caret <version>)

version-satisfies?procedure

Check if a version satisfies a constraint string.

(version-satisfies? (parse-version "1.5.0") ">= 1.0.0")  ; => #t
(version-satisfies? (parse-version "2.0.0") "^1.0.0")    ; => #f

constraint-satisfies?procedure

Check if a version satisfies a parsed constraint.

version-compatible?procedure

Check if version a is compatible with version b.

Two versions are compatible if they have the same major version and a >= b.

(version-compatible? (parse-version "1.5.0")
                     (parse-version "1.2.0"))  ; => #t

version-bump-majorprocedure

Bump the major version (resets minor and patch to 0).

(version->string (version-bump-major (parse-version "1.2.3")))
; => "2.0.0"

version-bump-minorprocedure

Bump the minor version (resets patch to 0).

(version->string (version-bump-minor (parse-version "1.2.3")))
; => "1.3.0"

version-bump-patchprocedure

Bump the patch version.

(version->string (version-bump-patch (parse-version "1.2.3")))
; => "1.2.4"