version

README

Versioning Library for Go

go-version is a library for parsing versions and version constraints, and verifying versions against a set of constraints. go-version can sort a collection of versions properly, handles prerelease/beta versions, can increment versions, etc.

Versions used with go-version must follow SemVer.

Installation and Usage

Package documentation can be found on GoDoc.

Installation can be done with a normal go get:

$ go get github.com/hashicorp/go-version

Version Parsing and Comparison

v1, err := version.NewVersion("1.2")
v2, err := version.NewVersion("1.5+metadata")

// Comparison example. There is also GreaterThan, Equal, and just
// a simple Compare that returns an int allowing easy >=, <=, etc.
if v1.LessThan(v2) {
    fmt.Printf("%s is less than %s", v1, v2)
}

Version Constraints

v1, err := version.NewVersion("1.2")

// Constraints example.
constraints, err := version.NewConstraint(">= 1.0, < 1.4")
if constraints.Check(v1) {
	fmt.Printf("%s satisfies constraints %s", v1, constraints)
}

Version Sorting

versionsRaw := []string{"1.1", "0.7.1", "1.4-beta", "1.4", "2"}
versions := make([]*version.Version, len(versionsRaw))
for i, raw := range versionsRaw {
    v, _ := version.NewVersion(raw)
    versions[i] = v
}

// After this, the versions are properly sorted
sort.Sort(version.Collection(versions))

Issues and Contributing

If you find an issue with this library, please report an issue. If you'd like, we welcome any contributions. Fork this library and submit a pull request.

Documentation

Index

• Constants
• type Collection
  • func (v Collection) Len() int
  • func (v Collection) Less(i, j int) bool
  • func (v Collection) Swap(i, j int)
• type Constraint
  • func (c *Constraint) Check(v *Version) bool
  • func (c *Constraint) Equals(con *Constraint) bool
  • func (c *Constraint) Prerelease() bool
  • func (c *Constraint) String() string
• type Constraints
  • func MustConstraints(c Constraints, err error) Constraints
  • func NewConstraint(v string) (Constraints, error)
  • func (cs Constraints) Check(v *Version) bool
  • func (cs Constraints) Equals(c Constraints) bool
  • func (cs Constraints) Len() int
  • func (cs Constraints) Less(i, j int) bool
  • func (cs Constraints) String() string
  • func (cs Constraints) Swap(i, j int)
• type Version
  • func Must(v *Version, err error) *Version
  • func NewSemver(v string) (*Version, error)
  • func NewVersion(v string) (*Version, error)
  • func (v *Version) Compare(other *Version) int
  • func (v *Version) Core() *Version
  • func (v *Version) Equal(o *Version) bool
  • func (v *Version) GreaterThan(o *Version) bool
  • func (v *Version) GreaterThanOrEqual(o *Version) bool
  • func (v *Version) LessThan(o *Version) bool
  • func (v *Version) LessThanOrEqual(o *Version) bool
  • func (v *Version) MarshalText() ([]byte, error)
  • func (v *Version) Metadata() string
  • func (v *Version) Original() string
  • func (v *Version) Prerelease() string
  • func (v *Version) Segments() []int
  • func (v *Version) Segments64() []int64
  • func (v *Version) String() string
  • func (v *Version) UnmarshalText(b []byte) error

Constants

const (
	VersionRegexpRaw string = `v?([0-9]+(\.[0-9]+)*?)` +
		`(-([0-9]+[0-9A-Za-z\-~]*(\.[0-9A-Za-z\-~]+)*)|(-?([A-Za-z\-~]+[0-9A-Za-z\-~]*(\.[0-9A-Za-z\-~]+)*)))?` +
		`(\+([0-9A-Za-z\-~]+(\.[0-9A-Za-z\-~]+)*))?` +
		`?`

	// SemverRegexpRaw requires a separator between version and prerelease
	SemverRegexpRaw string = `v?([0-9]+(\.[0-9]+)*?)` +
		`(-([0-9]+[0-9A-Za-z\-~]*(\.[0-9A-Za-z\-~]+)*)|(-([A-Za-z\-~]+[0-9A-Za-z\-~]*(\.[0-9A-Za-z\-~]+)*)))?` +
		`(\+([0-9A-Za-z\-~]+(\.[0-9A-Za-z\-~]+)*))?` +
		`?`
)

The raw regular expression string used for testing the validity of a version.

Types

type Collection

type Collection []*Version

Collection is a type that implements the sort.Interface interface so that versions can be sorted.

func (Collection) Len

func (v Collection) Len() int

func (Collection) Less

func (v Collection) Less(i, j int) bool

func (Collection) Swap

func (v Collection) Swap(i, j int)

type Constraint

type Constraint struct {
	// contains filtered or unexported fields
}

Constraint represents a single constraint for a version, such as ">= 1.0".

func (*Constraint) Check

func (c *Constraint) Check(v *Version) bool

Check tests if a constraint is validated by the given version.

func (*Constraint) Equals

func (c *Constraint) Equals(con *Constraint) bool

func (*Constraint) Prerelease

func (c *Constraint) Prerelease() bool

Prerelease returns true if the version underlying this constraint contains a prerelease field.

func (*Constraint) String

func (c *Constraint) String() string

type Constraints

type Constraints []*Constraint

Constraints is a slice of constraints. We make a custom type so that we can add methods to it.

func MustConstraints

func MustConstraints(c Constraints, err error) Constraints

MustConstraints is a helper that wraps a call to a function returning (Constraints, error) and panics if error is non-nil.

func NewConstraint

func NewConstraint(v string) (Constraints, error)

NewConstraint will parse one or more constraints from the given constraint string. The string must be a comma-separated list of constraints.

func (Constraints) Check

func (cs Constraints) Check(v *Version) bool

Check tests if a version satisfies all the constraints.

func (Constraints) Equals

func (cs Constraints) Equals(c Constraints) bool

Equals compares Constraints with other Constraints for equality. This may not represent logical equivalence of compared constraints. e.g. even though '>0.1,>0.2' is logically equivalent to '>0.2' it is *NOT* treated as equal.

Missing operator is treated as equal to '=', whitespaces are ignored and constraints are sorted before comaparison.

func (Constraints) Len

func (cs Constraints) Len() int

func (Constraints) Less

func (cs Constraints) Less(i, j int) bool

func (Constraints) String

func (cs Constraints) String() string

Returns the string format of the constraints

func (Constraints) Swap

func (cs Constraints) Swap(i, j int)

type Version

type Version struct {
	// contains filtered or unexported fields
}

Version represents a single version.

func Must

func Must(v *Version, err error) *Version

Must is a helper that wraps a call to a function returning (*Version, error) and panics if error is non-nil.

func NewSemver

func NewSemver(v string) (*Version, error)

NewSemver parses the given version and returns a new Version that adheres strictly to SemVer specs https://semver.org/

func NewVersion

func NewVersion(v string) (*Version, error)

NewVersion parses the given version and returns a new Version.

func (*Version) Compare

func (v *Version) Compare(other *Version) int

Compare compares this version to another version. This returns -1, 0, or 1 if this version is smaller, equal, or larger than the other version, respectively.

If you want boolean results, use the LessThan, Equal, GreaterThan, GreaterThanOrEqual or LessThanOrEqual methods.

func (*Version) Core

func (v *Version) Core() *Version

Core returns a new version constructed from only the MAJOR.MINOR.PATCH segments of the version, without prerelease or metadata.

func (*Version) Equal

func (v *Version) Equal(o *Version) bool

Equal tests if two versions are equal.

func (*Version) GreaterThan

func (v *Version) GreaterThan(o *Version) bool

GreaterThan tests if this version is greater than another version.

func (*Version) GreaterThanOrEqual

func (v *Version) GreaterThanOrEqual(o *Version) bool

GreaterThanOrEqual tests if this version is greater than or equal to another version.

func (*Version) LessThan

func (v *Version) LessThan(o *Version) bool

LessThan tests if this version is less than another version.

func (*Version) LessThanOrEqual

func (v *Version) LessThanOrEqual(o *Version) bool

LessThanOrEqual tests if this version is less than or equal to another version.

func (*Version) MarshalText

func (v *Version) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler interface.

func (*Version) Metadata

func (v *Version) Metadata() string

Metadata returns any metadata that was part of the version string.

Metadata is anything that comes after the "+" in the version. For example, with "1.2.3+beta", the metadata is "beta".

func (*Version) Original

func (v *Version) Original() string

Original returns the original parsed version as-is, including any potential whitespace, `v` prefix, etc.

func (*Version) Prerelease

func (v *Version) Prerelease() string

Prerelease returns any prerelease data that is part of the version, or blank if there is no prerelease data.

Prerelease information is anything that comes after the "-" in the version (but before any metadata). For example, with "1.2.3-beta", the prerelease information is "beta".

func (*Version) Segments

func (v *Version) Segments() []int

Segments returns the numeric segments of the version as a slice of ints.

This excludes any metadata or pre-release information. For example, for a version "1.2.3-beta", segments will return a slice of 1, 2, 3.

func (*Version) Segments64

func (v *Version) Segments64() []int64

Segments64 returns the numeric segments of the version as a slice of int64s.

This excludes any metadata or pre-release information. For example, for a version "1.2.3-beta", segments will return a slice of 1, 2, 3.

func (*Version) String

func (v *Version) String() string

String returns the full version string included pre-release and metadata information.

This value is rebuilt according to the parsed segments and other information. Therefore, ambiguities in the version string such as prefixed zeroes (1.04.0 => 1.4.0), `v` prefix (v1.0.0 => 1.0.0), and missing parts (1.0 => 1.0.0) will be made into a canonicalized form as shown in the parenthesized examples.

func (*Version) UnmarshalText

func (v *Version) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler interface.