semver

package
v1.1.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 9, 2023 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package semver provides the ability to work with Semantic Versions (http://semver.org) in Go.

Specifically it provides the ability to:

  • Parse semantic versions
  • Sort semantic versions
  • Check if a semantic version fits within a set of constraints
  • Optionally work with a `v` prefix

Parsing Semantic Versions

To parse a semantic version use the `NewVersion` function. For example, 

v, err := semver.NewVersion("1.2.3-beta.1+build345")

If there is an error the version wasn't parseable. The version object has methods to get the parts of the version, compare it to other versions, convert the version back into a string, and get the original string. For more details please see the documentation at https://godoc.org/github.com/Masterminds/semver.

Sorting Semantic Versions

A set of versions can be sorted using the `sort` package from the standard library. For example, 

    raw := []string{"1.2.3", "1.0", "1.3", "2", "0.4.2",}
    vs := make([]*semver.Version, len(raw))
	for i, r := range raw {
		v, err := semver.NewVersion(r)
		if err != nil {
			t.Errorf("Error parsing version: %s", err)
		}

		vs[i] = v
	}

	sort.Sort(semver.Collection(vs))

Checking Version Constraints

Checking a version against version constraints is one of the most featureful parts of the package. 

c, err := semver.NewConstraint(">= 1.2.3")
if err != nil {
    // Handle constraint not being parseable.
}

v, err := semver.NewVersion("1.3")
if err != nil {
    // Handle version not being parseable.
}
// Check if the version meets the constraints. The a variable will be true.
a := c.Check(v)

Basic Comparisons

There are two elements to the comparisons. First, a comparison string is a list of comma separated and comparisons. These are then separated by || separated or comparisons. For example, `">= 1.2, < 3.0.0 || >= 4.2.3"` is looking for a comparison that's greater than or equal to 1.2 and less than 3.0.0 or is greater than or equal to 4.2.3.

The basic comparisons are:

  • `=`: equal (aliased to no operator)
  • `!=`: not equal
  • `>`: greater than
  • `<`: less than
  • `>=`: greater than or equal to
  • `<=`: less than or equal to

Hyphen Range Comparisons

There are multiple methods to handle ranges and the first is hyphens ranges. These look like:

  • `1.2 - 1.4.5` which is equivalent to `>= 1.2, <= 1.4.5`
  • `2.3.4 - 4.5` which is equivalent to `>= 2.3.4, <= 4.5`

Wildcards In Comparisons

The `x`, `X`, and `*` characters can be used as a wildcard character. This works for all comparison operators. When used on the `=` operator it falls back to the pack level comparison (see tilde below). For example,

  • `1.2.x` is equivalent to `>= 1.2.0, < 1.3.0`
  • `>= 1.2.x` is equivalent to `>= 1.2.0`
  • `<= 2.x` is equivalent to `<= 3`
  • `*` is equivalent to `>= 0.0.0`

Tilde Range Comparisons (Patch)

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. For example,

  • `~1.2.3` is equivalent to `>= 1.2.3, < 1.3.0`
  • `~1` is equivalent to `>= 1, < 2`
  • `~2.3` is equivalent to `>= 2.3, < 2.4`
  • `~1.2.x` is equivalent to `>= 1.2.0, < 1.3.0`
  • `~1.x` is equivalent to `>= 1, < 2`

Caret Range Comparisons (Major)

The caret (`^`) comparison operator is for major level changes. This is useful when comparisons of API versions as a major change is API breaking. For example,

  • `^1.2.3` is equivalent to `>= 1.2.3, < 2.0.0`
  • `^1.2.x` is equivalent to `>= 1.2.0, < 2.0.0`
  • `^2.3` is equivalent to `>= 2.3, < 3`
  • `^2.x` is equivalent to `>= 2.0.0, < 3`

Index

Constants

View Source 
const SemVerRegex string = `v?([0-9]+)(\.[0-9]+)?(\.[0-9]+)?` +
	`(-([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?` +
	`(\+([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?`

SemVerRegex is the regular expression used to parse a semantic version.

View Source 
const ValidPrerelease string = `^([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*)$`

ValidPrerelease is the regular expression which validates both prerelease and metadata values.

Variables

View Source 
var (
	// ErrInvalidSemVer is returned a version is found to be invalid when
	// being parsed.
	ErrInvalidSemVer = errors.New("Invalid Semantic Version")

	// ErrInvalidMetadata is returned when the metadata is an invalid format
	ErrInvalidMetadata = errors.New("Invalid Metadata string")

	// ErrInvalidPrerelease is returned when the pre-release is an invalid format
	ErrInvalidPrerelease = errors.New("Invalid Prerelease string")
)

Functions

This section is empty.

Types

type Collection 

type Collection []*Version

Collection is a collection of Version instances and implements the sort interface. See the sort package for more details. https://golang.org/pkg/sort/

func (Collection) Len 

func (c Collection) Len() int

Len returns the length of a collection. The number of Version instances on the slice.

func (Collection) Less 

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

Less is needed for the sort interface to compare two Version objects on the slice. If checks if one is less than the other.

func (Collection) Swap 

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

Swap is needed for the sort interface to replace the Version objects at two different positions in the slice.

type Constraints 

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

Constraints is one or more constraint that a semantic version can be checked against.

func NewConstraint 

func NewConstraint(c string) (*Constraints, error)

NewConstraint returns a Constraints instance that a Version instance can be checked against. If there is a parse error it will be returned.

func (Constraints) Check 

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

Check tests if a version satisfies the constraints.

func (Constraints) Validate 

func (cs Constraints) Validate(v *Version) (bool, []error)

Validate checks if a version satisfies a constraint. If not a slice of reasons for the failure are returned in addition to a bool.

type Version 

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

Version represents a single semantic version.

func MustParse 

func MustParse(v string) *Version

MustParse parses a given version and panics on error.

func NewVersion 

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

NewVersion parses a given version and returns an instance of Version or an error if unable to parse the version.

func (*Version) Compare 

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

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

Versions are compared by X.Y.Z. Build metadata is ignored. Prerelease is lower than the version without a prerelease.

func (*Version) Equal 

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

Equal tests if two versions are equal to each other. Note, versions can be equal with different metadata since metadata is not considered part of the comparable version.

func (*Version) GreaterThan 

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

GreaterThan tests if one version is greater than another one.

func (Version) IncMajor 

func (v Version) IncMajor() Version

IncMajor produces the next major version. Sets patch to 0. Sets minor to 0. Increments major number. Unsets metadata. Unsets prerelease status.

func (Version) IncMinor 

func (v Version) IncMinor() Version

IncMinor produces the next minor version. Sets patch to 0. Increments minor number. Unsets metadata. Unsets prerelease status.

func (Version) IncPatch 

func (v Version) IncPatch() Version

IncPatch produces the next patch version. If the current version does not have prerelease/metadata information, it unsets metadata and prerelease values, increments patch number. If the current version has any of prerelease or metadata information, it unsets both values and keeps curent patch value

func (*Version) LessThan 

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

LessThan tests if one version is less than another one.

func (*Version) Major 

func (v *Version) Major() int64

Major returns the major version.

func (*Version) MarshalJSON 

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

MarshalJSON implements JSON.Marshaler interface.

func (*Version) Metadata 

func (v *Version) Metadata() string

Metadata returns the metadata on the version.

func (*Version) Minor 

func (v *Version) Minor() int64

Minor returns the minor version.

func (*Version) Original 

func (v *Version) Original() string

Original returns the original value passed in to be parsed.

func (*Version) Patch 

func (v *Version) Patch() int64

Patch returns the patch version.

func (*Version) Prerelease 

func (v *Version) Prerelease() string

Prerelease returns the pre-release version.

func (Version) SetMetadata 

func (v Version) SetMetadata(metadata string) (Version, error)

SetMetadata defines metadata value. Value must not include the required 'plus' prefix.

func (Version) SetPrerelease 

func (v Version) SetPrerelease(prerelease string) (Version, error)

SetPrerelease defines the prerelease value. Value must not include the required 'hypen' prefix.

func (*Version) String 

func (v *Version) String() string

String converts a Version object to a string. Note, if the original version contained a leading v this version will not. See the Original() method to retrieve the original value. Semantic Versions don't contain a leading v per the spec. Instead it's optional on implementation.

func (*Version) UnmarshalJSON 

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

UnmarshalJSON implements JSON.Unmarshaler interface.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.