README
¶
Semver
The semver package implements logic to work with Sementic Versioning 2.0.0 in Go.
It provides:
- Parser for semantic versions
- Validation of semantic versions
- Sorting of semantic versions
- Parser for semantic version range constraints
- Range constraint matching
- whether version contained in range
- whether a range is contained in another range
This library is loosely based on the awesome:
https://github.com/Masterminds/semver
Parsing Semantic Versions
This library implements strict parsing of semantic versions as outlined in the Sementic Versioning spec. Shorthand forms or a v prefix e.g. 2.0, 1, v2.1.2 are not considered valid semantic versions following the 2.0.0 spec.
Parsing Huge Versions
Semver does not limit the amount of Major, Minor or Patch version numbers.
Making99999999999999999999999.999999999999999999.99999999999999999a valid semver. For simplicity this library usesuint64as underlying datatype for Major, Minor and Patch, limiting the maximum number to9999999999999999999.
When parsing an invalid version errors are annotated with the character column number that an issue was encountered on:
_, err := semver.NewVersion("1.2")
fmt.Println(err)
// Output: col 4: missing patch
Parsing Semantic Version Constraints
Constraints can be used to filter parsed semantic versions. All constraint expressions expand to one or multiple valid semver ranges.
The constraints parser is more permissive to allow shorthand ranges and wildcards.
e.g. 1 - 2 => 1.0.0 - 2.0.0
Pre release versions that fall within a range will match. If pre release versions should be excluded, they have to be filtered before checking against constraints.
Specifying pre-release ranges is NOT supported.
e.g. 1.0.0-rc.0 - 1.0.0.rc.10
In the following examples <max> is used to denote the max number possible to put into the Major, Minor or Patch section of a semantic version.
Available Operators:
=: equal, version must match exactly!=: not equal, excludes a specific version>: greater than<: less than>=: greater than or equal<=: less than or equal
Hypen Range
A hyphen range explicitly defines the minimum and maximum version of a range. The min and max values are inclusive.
e.g. A constraint 1.0.0 - 2.0.0 will match 1.0.0 and 2.0.0, but not 0.9.1 or 2.0.1.
1.2 - 1.4.5which is equivalent to>= 1.2.0 <= 1.4.52.3.4 - 4.5which is equivalent to>= 2.3.4 <= 4.5.0
Wildcards
The x, X and * characters can be used as wildcard in version constraints. They will be automatically expanded to either 0 or <max>, depending on the operator.
1.2.xis expanded to1.2.0 - 1.2.<max>> 1.2.xis expanded to1.2.1 - 1.2.<max>< 2.4.xis expanded to0.0.0 - 2.4.<max>1.2.x - 3.xis expanded to1.2.0 - 3.<max>.<max>
Tilde Range
The tilde (~) comparison operator is for patch level ranges when a minor version is specified and major level changes when the minor number is missing.
~1.2.3is expanded to1.2.3 - 1.2.<max>~2.3is expanded to2.3.0 - 2.3.<max>~1is expanded to1.0.0 - 1.<max>.<max>~1.xis expanded to1.0.0 - 1.<max>.<max>~2.3.xis expanded to2.3.0 - 2.3.<max>
Caret Range
The caret (^) comparison operator is for major level changes once a stable (1.0.0) release has occurred. Prior to a 1.0.0 release the minor versions acts as the API stability level. This is useful when comparisons of API versions as a major change is API breaking.
stable versions
^1.2.3is expanded to1.2.3 - 1.<max>.<max>^2.3is expanded to2.3.0 - 2.<max>.<max>^2is expanded to2.0.0 - 2.<max>.<max>^1.2.xis expanded to1.2.0 - 1.<max>.<max>^2.xis expanded to2.0.0 - 2.<max>.<max>
unstable versions
^0.2.3is expanded to0.2.3 - 0.2.<max>^0.2is expanded to0.2.0 - 0.2.<max>^0is expanded to0.0.0 - 0.0.<max>
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Ascending ¶
type Ascending []Version
Sorts versions Ascending via the sorts standard lib package. resulting order: 1.0.0, 1.1.0, 2.0.0.
Example ¶
package main
import (
"fmt"
"sort"
"pkg.package-operator.run/semver"
)
func main() {
versions := []semver.Version{
semver.MustNewVersion("1.2.4"),
semver.MustNewVersion("1.2.3"),
semver.MustNewVersion("1.0.0"),
semver.MustNewVersion("1.3.0"),
semver.MustNewVersion("2.0.0"),
semver.MustNewVersion("0.4.2"),
}
sort.Sort(semver.Ascending(versions))
fmt.Println(semver.VersionList(versions).String())
}
Output: 0.4.2, 1.0.0, 1.2.3, 1.2.4, 1.3.0, 2.0.0
type Constraint ¶
type Constraint interface {
// Check if the version is allowed by the constraint or not.
Check(v Version) bool
// Check if a range is contained within a constraint.
Contains(or Constraint) bool
// Returns the string representation of this constraint.
String() string
}
Constraint interface is common to all version constraints.
func MustNewConstraint ¶
func MustNewConstraint(data string) Constraint
Parses the given string into a Version Constraint or panics.
func NewConstraint ¶
func NewConstraint(data string) (Constraint, error)
Parses the given string into a Version Constraint.
Example (Range) ¶
package main
import (
"fmt"
"pkg.package-operator.run/semver"
)
func main() {
constraint := "1.0.0 - 2.0.0"
c, err := semver.NewConstraint(constraint)
if err != nil {
panic(err)
}
notContained := semver.MustNewConstraint("2.0.0 - 3.0.0")
contained := semver.MustNewConstraint("1.0.0 - 1.4.0")
fmt.Printf("1.0.0 - 1.4.0 is contained in range %q: %v\n", constraint, c.Contains(contained))
fmt.Printf("2.0.0 - 3.0.0 is contained in range %q: %v\n", constraint, c.Contains(notContained))
}
Output: 1.0.0 - 1.4.0 is contained in range "1.0.0 - 2.0.0": true 2.0.0 - 3.0.0 is contained in range "1.0.0 - 2.0.0": false
Example (Version) ¶
package main
import (
"fmt"
"pkg.package-operator.run/semver"
)
func main() {
constraint := "1.0.0 - 2.0.0"
c, err := semver.NewConstraint(constraint)
if err != nil {
panic(err)
}
notContained := semver.MustNewVersion("3.0.0")
contained := semver.MustNewVersion("1.2.0")
fmt.Printf("%s is contained in range %q: %v\n", contained.String(), constraint, c.Check(contained))
fmt.Printf("%s is contained in range %q: %v\n", notContained.String(), constraint, c.Check(notContained))
}
Output: 1.2.0 is contained in range "1.0.0 - 2.0.0": true 3.0.0 is contained in range "1.0.0 - 2.0.0": false
type Descending ¶
type Descending []Version
Sorts versions Descending via the sorts standard lib package. resulting order: 2.0.0, 1.1.0, 1.0.0.
Example ¶
package main
import (
"fmt"
"sort"
"pkg.package-operator.run/semver"
)
func main() {
versions := []semver.Version{
semver.MustNewVersion("1.2.4"),
semver.MustNewVersion("1.2.3"),
semver.MustNewVersion("1.0.0"),
semver.MustNewVersion("1.3.0"),
semver.MustNewVersion("2.0.0"),
semver.MustNewVersion("0.4.2"),
}
sort.Sort(semver.Descending(versions))
fmt.Println(semver.VersionList(versions).String())
}
Output: 2.0.0, 1.3.0, 1.2.4, 1.2.3, 1.0.0, 0.4.2
func (Descending) Len ¶
func (l Descending) Len() int
Returns the number of items of the slice. Implements sort.Interface.
func (Descending) Less ¶
func (l Descending) Less(i, j int) bool
Returns true if item[j] is less than item[i]. Implements sort.Interface.
func (Descending) Swap ¶
func (l Descending) Swap(i, j int)
Swaps the position of two items in the list. Implements sort.Interface.
type PreReleaseIdentifier ¶
type PreReleaseIdentifier struct {
// contains filtered or unexported fields
}
PreReleaseIdentifier can be alphanumeric or a number.
func ToPreReleaseIdentifier ¶
func ToPreReleaseIdentifier(s string) PreReleaseIdentifier
Converts the given string into a PreReleaseIdentifier.
func (*PreReleaseIdentifier) Compare ¶
func (s *PreReleaseIdentifier) Compare(o PreReleaseIdentifier) int
Compare compares this pre release identifier to another one. It returns -1, 0, or 1 if the version smaller, equal, or larger than the other identifier.
func (*PreReleaseIdentifier) GetNumber ¶
func (s *PreReleaseIdentifier) GetNumber() (uint64, bool)
func (*PreReleaseIdentifier) GetString ¶
func (s *PreReleaseIdentifier) GetString() (string, bool)
func (*PreReleaseIdentifier) Interface ¶
func (s *PreReleaseIdentifier) Interface() interface{}
func (*PreReleaseIdentifier) String ¶
func (s *PreReleaseIdentifier) String() string
type PreReleaseIdentifierList ¶
type PreReleaseIdentifierList []PreReleaseIdentifier
func (PreReleaseIdentifierList) Compare ¶
func (l PreReleaseIdentifierList) Compare(o []PreReleaseIdentifier) int
Compare compares this pre release identifier list to another one. It returns -1, 0, or 1 if the version smaller, equal, or larger than the other list.
func (PreReleaseIdentifierList) String ¶
func (l PreReleaseIdentifierList) String() string
type Range ¶
Range represents a min to max version range. Min and Max are inclusive >=/<= e.g. 1.0.0 - 1.1.0 would contain both 1.0.0 and 1.1.0.
func (*Range) Contains ¶
func (r *Range) Contains(other Constraint) bool
Checks if the given constraint fits into this range.
type Version ¶
type Version struct {
Major, Minor, Patch uint64
PreRelease PreReleaseIdentifierList
BuildMetadata []string
}
Represents a Semantic Versioning 2.0.0 Version.
func MustNewVersion ¶
Parses the given string into a Version object and panics on error.
Example ¶
package main
import (
"fmt"
"pkg.package-operator.run/semver"
)
func main() {
v := semver.MustNewVersion("1.2.4-alpha.0+meta")
fmt.Println(v.Major, v.Minor, v.Patch, v.PreRelease, v.BuildMetadata)
}
Output: 1 2 4 alpha.0 [meta]
func NewVersion ¶
Parses the given string into a Version object.
Example ¶
package main
import (
"fmt"
"pkg.package-operator.run/semver"
)
func main() {
v, err := semver.NewVersion("1.2.4-alpha.0+meta")
if err != nil {
panic(err)
}
fmt.Println(v.Major, v.Minor, v.Patch, v.PreRelease, v.BuildMetadata)
}
Output: 1 2 4 alpha.0 [meta]
func (*Version) Compare ¶
Compare compares this version to another one. It returns -1, 0, or 1 if the version smaller, equal, or larger than the other version.
func (*Version) GreaterThan ¶
GreaterThan tests if one version is greater than another one.
type VersionList ¶
type VersionList []Version
VersionList keeps a list of versions and provides helper functions on them.
func (VersionList) String ¶
func (l VersionList) String() string
Prints the VersionList as comma and space ", " separated list.
func (VersionList) StringList ¶
func (l VersionList) StringList() []string
Converts all Versions into strings and returns them.
Source Files
Directories