README

Versioning Library for Go

Build Status

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.

Expand ▾ Collapse ▴

Documentation

Index

Constants

View Source
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.

    Variables

    This section is empty.

    Functions

    This section is empty.

    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) 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 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) MarshalJSON

                func (c Constraints) MarshalJSON() ([]byte, error)

                  MarshalJSON implements the json.Marshaller interface.

                  func (Constraints) String

                  func (cs Constraints) String() string

                    Returns the string format of the constraints

                    func (*Constraints) UnmarshalJSON

                    func (c *Constraints) UnmarshalJSON(value []byte) error

                      UnmarshalJSON implements the json.Unmarshaller interface.

                      type Mutator

                      type Mutator struct {
                      	*Version
                      }

                      func (*Mutator) Done

                      func (m *Mutator) Done() *Version

                      func (*Mutator) NextMajor

                      func (m *Mutator) NextMajor() *Mutator

                      func (*Mutator) NextMinor

                      func (m *Mutator) NextMinor() *Mutator

                      func (*Mutator) NextPatch

                      func (m *Mutator) NextPatch() *Mutator

                      func (*Mutator) ResetMetadata

                      func (m *Mutator) ResetMetadata() *Mutator

                      func (*Mutator) ResetPatch

                      func (m *Mutator) ResetPatch() *Mutator

                      func (*Mutator) ResetPrerelease

                      func (m *Mutator) ResetPrerelease() *Mutator

                      func (*Mutator) SetMetadata

                      func (m *Mutator) SetMetadata(md string) *Mutator

                      func (*Mutator) SetPrerelease

                      func (m *Mutator) SetPrerelease(id string) *Mutator

                      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) Clone

                              func (v *Version) Clone() *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) 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) Major

                                          func (v *Version) Major() int64

                                            Major returns major version number of this Version object

                                            func (Version) MarshalJSON

                                            func (v Version) MarshalJSON() ([]byte, error)

                                              MarshalJSON implements the json.Marshaller 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) Minor

                                                func (v *Version) Minor() int64

                                                  Minor returns minor version number of this Version object

                                                  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) Patch

                                                    func (v *Version) Patch() int64

                                                      Patch returns patch version number of this Version object

                                                      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) ToMutator

                                                              func (v *Version) ToMutator() *Mutator

                                                              func (*Version) UnmarshalJSON

                                                              func (v *Version) UnmarshalJSON(value []byte) error

                                                                UnmarshalJSON implements the json.Unmarshaller interface.