Back to godoc.org
blitznote.com/src/semver/v3

Package semver

v3.2.1
Latest Go to latest
Published: Dec 31, 2019 | License: BSD-3-Clause | Module: blitznote.com/src/semver/v3

Overview

Package semver contains types and functions for parsing of Versions and (Version-)Ranges.

Example (Range)

Code:

v1 := semver.MustParse("1.2.3-beta")
r1, _ := semver.NewRange([]byte("~1.2"))

fmt.Println(r1.Contains(v1))
fmt.Println(r1.IsSatisfiedBy(v1))
true
false
Example (Version)

Code:

v1 := semver.MustParse("1.2.3-beta")
v2 := semver.MustParse("2.0.0-alpha20140805.456-rc3+build1800")

fmt.Println(v1.Less(v2))
true

Index

Examples

Package Files

func Compare

func Compare(a, b Version) int

Compare computes the difference between two Versions and returns its signum.

1  if a > b
0  if a == b
-1 if a < b

The 'build' is not compared.

Example

Code:

v1 := semver.MustParse("v1")
v2 := semver.MustParse("v2.0")
v3 := semver.MustParse("v3.0.0")

fmt.Println("Compare", v3, v2, "=", semver.Compare(v3, v2))
fmt.Println("Compare", v2, v2, "=", semver.Compare(v2, v2))
fmt.Println("Compare", v1, v2, "=", semver.Compare(v1, v2))
Compare 3.0.0 2.0.0 = 1
Compare 2.0.0 2.0.0 = 0
Compare 1.0.0 2.0.0 = -1

func Satisfies

func Satisfies(aVersion, aRange string) (bool, error)

Satisfies is a convenience function for former NodeJS developers, and works on two strings.

Please see Range's IsSatisfiedBy for details.

type InvalidStringValue

type InvalidStringValue string

InvalidStringValue instances are returned as error on any conversion failure.

func (InvalidStringValue) Error

func (e InvalidStringValue) Error() string

Error implements the error interface.

func (InvalidStringValue) IsInvalid

func (e InvalidStringValue) IsInvalid() bool

IsInvalid satisfies a function IsInvalid(). This is used by some input validator packages.

type Range

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

Range is a subset of the universe of Versions: It can have a lower and upper boundary. For example, "1.2–2.0" is such a Range, with two boundaries.

func NewRange

func NewRange(str []byte) (Range, error)

NewRange translates into a Range.

func (Range) Contains

func (r Range) Contains(v Version) bool

Contains returns true if a Version is inside this Range.

If in doubt use IsSatisfiedBy.

Example (First)

Code:

v := semver.MustParse("1.4.3")
r, _ := semver.NewRange([]byte("^1.2"))

fmt.Println(r.Contains(v))
true
Example (Prerelases)

Code:

v := semver.MustParse("1.4.3-beta")
r, _ := semver.NewRange([]byte("1.2 <2.0.0"))

fmt.Println(r.Contains(v))
true
Example (Second)

Code:

v := semver.MustParse("1.4.3")
r, _ := semver.NewRange([]byte("1.2 <2.0.0"))

fmt.Println(r.Contains(v))
true

func (Range) GetLowerBoundary

func (r Range) GetLowerBoundary() *Version

GetLowerBoundary gets you the lower (left) boundary.

Example

Code:

r, _ := semver.NewRange([]byte("^1.2"))
fmt.Println(*r.GetLowerBoundary())
1.2.0

func (Range) GetUpperBoundary

func (r Range) GetUpperBoundary() *Version

GetUpperBoundary gets you the high (right) boundary.

Example (First)

Code:

r, _ := semver.NewRange([]byte("1.2 <2.0.0"))
fmt.Println(*r.GetUpperBoundary())
2.0.0
Example (Second)

Code:

r, _ := semver.NewRange([]byte("~1.2.3"))
fmt.Println(*r.GetUpperBoundary())
1.3.0

func (Range) IsSatisfiedBy

func (r Range) IsSatisfiedBy(v Version) bool

IsSatisfiedBy works like Contains, but rejects pre-releases if neither of the bounds is a pre-release.

Use this in the context of pulling in packages because it follows the spirit of §9 SemVer. Also see https://github.com/npm/node-semver/issues/64

Example (Full)

Code:

v := semver.MustParse("1.2.3")
r, _ := semver.NewRange([]byte("~1.2"))

fmt.Println(r.IsSatisfiedBy(v))
true
Example (Prerelases)

Code:

pre := semver.MustParse("1.2.3-beta")
r, _ := semver.NewRange([]byte("~1.2"))

fmt.Println(r.IsSatisfiedBy(pre))
false

type Version

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

Version represents a version: Columns consisting of up to four unsigned integers (1.2.4.99) optionally further divided into 'release' and 'specifier' (1.2-634.0-99.8).

func MustParse

func MustParse(str string) Version

MustParse is NewVersion for strings, and panics on errors.

Use this in tests or with constants, e. g. whenever you control the input.

This is a convenience function for a cloud plattform provider.

Example

Code:

v := semver.MustParse("v1.14")
fmt.Println(v)
1.14.0

func NewVersion

func NewVersion(str []byte) (Version, error)

NewVersion translates the given string, which must be free of whitespace, into a single Version.

An io.Reader will give you []byte, hence this (and most functions internally) works on []byte to have as few conversion as possible.

Example

Code:

for _, str := range []string{"v1.14", "6.0.2.1", "14b6"} {
	v, err := semver.NewVersion([]byte(str))
	fmt.Println(v, err)
}
1.14.0 <nil>
6.0.2.1 <nil>
14.0.0 Given string does not resemble a Version

func (Version) Bytes

func (t Version) Bytes() []byte

Bytes returns a slice with the minimal human-readable representation of this Version.

Unlike String(), which returns a minimum of columns, this will conserve space at the expense of legibility. In other words, `len(v.Bytes()) ≤ len(v.String())`.

Example (First)

Code:

v := semver.MustParse("1.0")
fmt.Println(v.Bytes())
[49]
Example (Minimal)

Code:

v := semver.MustParse("1.13beta")

fmt.Println("Bytes()  =", string(v.Bytes()))
fmt.Println("String() =", v.String())
Bytes()  = 1.13-beta
String() = 1.13.0-beta
Example (Second)

Code:

v := semver.MustParse("4.8")
fmt.Println(v.Bytes())
[52 46 56]

func (Version) IsAPreRelease

func (t Version) IsAPreRelease() bool

IsAPreRelease is used to discriminate pre-releases.

Example

Code:

v, pre := semver.MustParse("1.12"), semver.MustParse("1.13beta")

fmt.Println(v, "is a pre-release:", v.IsAPreRelease())
fmt.Println(pre, "is a pre-release:", pre.IsAPreRelease())
1.12.0 is a pre-release: false
1.13.0-beta is a pre-release: true

func (Version) Less

func (t Version) Less(o Version) bool

Less is a convenience function for sorting.

Example

Code:

l, r := semver.MustParse("v2"), semver.MustParse("v3")
fmt.Println(l.Less(r), ",", l, "is 'less' than", r)

l, r = semver.MustParse("v1+build7"), semver.MustParse("v1+build9")
fmt.Println(l.Less(r), ",", l, "is 'less' than", r)
true , 2.0.0 is 'less' than 3.0.0
true , 1.0.0+build7 is 'less' than 1.0.0+build9

func (Version) LimitedEqual

func (t Version) LimitedEqual(o Version) bool

LimitedEqual returns true if two versions share the same: prefix, which is the "actual version", (pre-)release type, and (pre-)release version. The exception are patch-levels, which are always equal.

Use this, for example, to tell a beta from a regular version; or to accept a patched version as regular version.

A thing confusing but convention is to read this from right to left.

Example (First)

Code:

pre := semver.MustParse("1.0.0-pre")
rc := semver.MustParse("1.0.0-rc")

fmt.Println(pre.LimitedEqual(rc))
false
Example (Second)

Code:

a := semver.MustParse("1.0.0-beta-pre3")
b := semver.MustParse("1.0.0-beta-pre5")

fmt.Println(a.LimitedEqual(b))
true
Example (Third)

Code:

regular := semver.MustParse("1.0.0")
patched := semver.MustParse("1.0.0-p1")

fmt.Println(patched.LimitedEqual(regular))

fmt.Println(regular.LimitedEqual(patched))
false
true

func (Version) Major

func (t Version) Major() int

Major returns the major of a version.

Example

Code:

v := semver.MustParse("v1.2.3")
fmt.Println(v.Major())
1

func (Version) MarshalBinary

func (t Version) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

Anecdotically, encoders for binary protocols use this.

func (Version) MarshalJSON

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

MarshalJSON implements the json.Marshaler interface.

func (Version) MarshalText

func (t Version) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

Anecdotically, anything that writes XML will use this.

func (Version) Minor

func (t Version) Minor() int

Minor returns the minor of a version.

Example

Code:

v := semver.MustParse("v1.2.3")
fmt.Println(v.Minor())
2

func (Version) NextVersions

func (t Version) NextVersions(minReleaseType int, numberedPre bool) []*Version

NextVersions returns a list of possible next versions after t. For each of the three version points, pre-releases are given as options starting with the minimum release type (-4 <= 0), and those release types are numbered if numberedPre is true. Release types:

alpha: -4
beta:  -3
pre:   -2
rc:    -1
common: 0

Thus, if you don't want any pre-release options, set minReleaseType to 0.

Deprecated: This is a legacy method for the Caddyserver's build infrastructure. Do not rely on it, they are free to~ and can change it anytime.

func (*Version) Parse

func (t *Version) Parse(str string) error

Parse reads a string into the given version, overwriting any existing values.

Deprecated: Use the idiomatic UnmarshalText instead.

func (Version) Patch

func (t Version) Patch() int

Patch returns the patch of a version.

Example

Code:

v := semver.MustParse("v1.2.3")
fmt.Println(v.Patch())
3

func (*Version) Scan

func (t *Version) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

Example

Code:

a, b, c := new(semver.Version), new(semver.Version), new(semver.Version)
errA := a.Scan("5.5.65")
errB := b.Scan(int64(12))
errC := c.Scan(-1)

fmt.Println(a, errA)
fmt.Println(b, errB)
fmt.Println(c, errC)
5.5.65 <nil>
12.0.0 <nil>
0.0.0 Cannot read this type into a Version

func (Version) String

func (t Version) String() string

String returns the string representation of t.

Anecdotically, fmt.Println will use this.

Example

Code:

str := "v2.1"
v := semver.MustParse(str)
fmt.Println(str, "is", v.String(), "but as Bytes():", string(v.Bytes()))
v2.1 is 2.1.0 but as Bytes(): 2.1

func (*Version) UnmarshalBinary

func (t *Version) UnmarshalBinary(b []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

func (*Version) UnmarshalJSON

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

UnmarshalJSON implements the json.Unmarshaler interface.

func (*Version) UnmarshalText

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

UnmarshalText implements the encoding.TextUnmarshaler interface.

func (Version) Value

func (t Version) Value() (interface{}, error)

Value implements the driver.Valuer interface, as found in database/sql.

Deprecated: Use string(Version) instead.

type VersionPtrs

type VersionPtrs []*Version

VersionPtrs represents an array with elements derived from~ but smaller than Versions. Use this a proxy for sorting of large collections of Versions, to minimize memory moves.

func (VersionPtrs) Len

func (p VersionPtrs) Len() int

Len implements the sort.Interface.

func (VersionPtrs) Less

func (p VersionPtrs) Less(i, j int) bool

Less implements the sort.Interface.

func (VersionPtrs) Sort

func (p VersionPtrs) Sort()

Sort reorders the pointers so that the Versions appear in ascending order.

For that it will use optimized algorithms usually less time-complex than the generic ones found in package 'Sort'. Specifically, variants of radix sort expected to run in O(n).

Allocates a copy of VersionPtrs.

func (VersionPtrs) Swap

func (p VersionPtrs) Swap(i, j int)

Swap implements the sort.Interface.

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier