Documentation
¶
Overview ¶
Package semver is a standard-library-only Go port of the npm "semver" package (https://www.npmjs.com/package/semver), the reference implementation of Semantic Versioning 2.0.0 (https://semver.org) used throughout the Node and Express ecosystems. It parses, compares, increments, coerces and range-matches version strings with the same semantics JavaScript projects rely on, so tooling that reasons about dependency versions can be ported to Go without pulling in a third-party dependency.
A version is Major.Minor.Patch with optional dot-separated prerelease and build-metadata identifiers, for example "1.2.3-alpha.1+build.5". Parse turns a string into a *Version; MustParse panics instead of returning an error and is convenient for constants and tests. Valid reports whether a string is a well-formed version, and Clean normalizes surrounding whitespace and an optional leading "v" or "=".
Ordering follows the spec precisely: numeric fields compare numerically, a version with a prerelease has lower precedence than the same version without one, prerelease identifiers compare left to right (numeric identifiers numerically, alphanumeric identifiers lexically in ASCII order, and numeric identifiers always rank below alphanumeric ones), and build metadata is ignored for precedence. Compare returns -1, 0 or +1; the boolean helpers GT, GTE, LT, LTE, EQ and NEQ wrap it, and Sort orders a slice ascending.
Inc and the IncMajor/IncMinor/IncPatch methods produce the next version for a release level, resetting the lower fields and clearing prerelease and build metadata exactly as npm's semver does. Coerce extracts the first version-shaped run of digits from arbitrary text ("v2 release" -> "2.0.0").
Range matching is provided by Satisfies and the Range type, which understand the common npm range grammar: plain comparators (">=1.2.0", "<2.0.0", "=1.0.0" and a bare "1.2.3"), caret ranges ("^1.2.3"), tilde ranges ("~1.2.0"), x-ranges ("1.x", "1.2.*", "*"), hyphen ranges ("1.2.3 - 2.3.4"), space- or comma-separated AND terms within a set, and "||" separating alternative sets. Prerelease versions only satisfy a range when a comparator in the same tuple names the same Major.Minor.Patch with its own prerelease, matching npm's default (includePrerelease=false) behaviour.
Everything is deterministic and depends only on the standard library.
Index ¶
- Variables
- func Clean(s string) string
- func Coerce(s string) (string, error)
- func Compare(a, b string) int
- func EQ(a, b string) bool
- func GT(a, b string) bool
- func GTE(a, b string) bool
- func Inc(s, release string) (string, error)
- func LT(a, b string) bool
- func LTE(a, b string) bool
- func Major(s string) (uint64, error)
- func MaxSatisfying(versions []string, constraint string) (string, bool)
- func MinSatisfying(versions []string, constraint string) (string, bool)
- func Minor(s string) (uint64, error)
- func NEQ(a, b string) bool
- func Patch(s string) (uint64, error)
- func Prerelease(s string) (string, error)
- func Satisfies(version, constraint string) bool
- func Sort(versions []string)
- func Valid(s string) bool
- type Range
- type Version
- func (v *Version) Compare(o *Version) int
- func (v *Version) Core() *Version
- func (v *Version) Equal(o *Version) bool
- func (v *Version) GreaterThan(o *Version) bool
- func (v *Version) IncMajor() *Version
- func (v *Version) IncMinor() *Version
- func (v *Version) IncPatch() *Version
- func (v *Version) LessThan(o *Version) bool
- func (v *Version) String() string
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidVersion = errors.New("semver: invalid version")
ErrInvalidVersion is returned by Parse and the string-based helpers when the input is not a valid semantic version.
Functions ¶
func Clean ¶
Clean returns the canonical string form of s (dropping a leading "v"/"=" and surrounding whitespace) when s is a valid version, or "" when it is not.
func Coerce ¶
Coerce extracts the first version-like sequence from arbitrary text and returns it as a canonical version string. Missing minor or patch fields default to zero, so "v2" becomes "2.0.0" and "1.2.x build" becomes "1.2.0". It returns ErrInvalidVersion when no numeric component is found.
func Compare ¶
Compare parses two version strings and returns -1, 0 or +1 as a is less than, equal to, or greater than b. It panics if either string is invalid; use Valid to check first when the inputs are untrusted.
func Inc ¶
Inc returns the version string incremented at the given release level, which must be "major", "minor" or "patch". It returns an error for an invalid version or an unknown release level.
func MaxSatisfying ¶
MaxSatisfying returns the highest version in versions that satisfies the range, or "" (and ok=false) if none do. Invalid version strings are skipped.
func MinSatisfying ¶
MinSatisfying returns the lowest version in versions that satisfies the range, or "" (and ok=false) if none do. Invalid version strings are skipped.
func Prerelease ¶
Prerelease returns the dot-joined prerelease identifiers of a version string ("" when there are none).
func Satisfies ¶
Satisfies reports whether the version string satisfies the range string. It returns false if either input is invalid.
Types ¶
type Range ¶
type Range struct {
// contains filtered or unexported fields
}
Range is a compiled semantic-version range: a disjunction (OR) of tuples, where each tuple is a conjunction (AND) of comparators. It matches the common npm range grammar (see the package documentation). The zero Range matches nothing; construct one with ParseRange.
func ParseRange ¶
ParseRange compiles a range expression (for example "^1.2.0", ">=1.0.0 <2.0.0", "1.x || 2.x", "1.2.3 - 2.3.4"). It returns an error when the expression cannot be parsed.
type Version ¶
type Version struct {
// Major, Minor and Patch are the three numeric release fields.
Major uint64
Minor uint64
Patch uint64
// Prerelease holds the dot-separated identifiers following a '-', in order
// (empty when the version has no prerelease).
Prerelease []string
// Build holds the dot-separated build-metadata identifiers following a '+',
// in order (empty when the version has no build metadata). Build metadata
// does not affect precedence.
Build []string
}
Version is a parsed semantic version. The zero Version is 0.0.0 with no prerelease or build identifiers.
func MustParse ¶
MustParse is like Parse but panics if the version is invalid. It is intended for package-level variables and tests where the input is known good.
func Parse ¶
Parse parses a semantic version string, tolerating an optional leading "v" or "=" and surrounding whitespace. It returns ErrInvalidVersion (wrapped) when the string is not a valid version.
func (*Version) Compare ¶
Compare returns -1, 0 or +1 as v is less than, equal to, or greater than o in semantic-version precedence. Build metadata is ignored.
func (*Version) Core ¶
Core returns a copy of the version with prerelease and build metadata stripped, i.e. just Major.Minor.Patch.
func (*Version) Equal ¶
Equal reports whether v and o have equal precedence (build metadata ignored).
func (*Version) GreaterThan ¶
GreaterThan reports whether v has higher precedence than o.
func (*Version) IncMajor ¶
IncMajor returns a new version with Major incremented and the lower fields, prerelease and build metadata cleared.
func (*Version) IncMinor ¶
IncMinor returns a new version with Minor incremented, Patch cleared and prerelease and build metadata cleared.
func (*Version) IncPatch ¶
IncPatch returns a new version with Patch incremented and prerelease and build metadata cleared. A prerelease version is promoted to its release form without incrementing Patch, matching npm semver.
Source Files