semver

README

semver for golang

semver is a Semantic Versioning library written in golang. It fully covers spec version 2.0.0.

Usage

$ go get github.com/blang/semver

Note: Always vendor your dependencies or fix on a specific version tag.

import github.com/blang/semver
v1, err := semver.Make("1.0.0-beta")
v2, err := semver.Make("2.0.0-beta")
v1.Compare(v2)

Also check the GoDocs.

Why should I use this lib?

• Fully spec compatible
• No reflection
• No regex
• Fully tested (Coverage >99%)
• Readable parsing/validation errors
• Fast (See Benchmarks)
• Only Stdlib
• Uses values instead of pointers
• Many features, see below

Features

• Parsing and validation at all levels
• Comparator-like comparisons
• Compare Helper Methods
• InPlace manipulation
• Ranges >=1.0.0 <2.0.0 || >=3.0.0 !3.0.1-beta.1
• Wildcards >=1.x, <=2.5.x
• Sortable (implements sort.Interface)
• database/sql compatible (sql.Scanner/Valuer)
• encoding/json compatible (json.Marshaler/Unmarshaler)

Ranges

A Range is a set of conditions which specify which versions satisfy the range.

A condition is composed of an operator and a version. The supported operators are:

• <1.0.0 Less than 1.0.0
• <=1.0.0 Less than or equal to 1.0.0
• >1.0.0 Greater than 1.0.0
• >=1.0.0 Greater than or equal to 1.0.0
• 1.0.0, =1.0.0, ==1.0.0 Equal to 1.0.0
• !1.0.0, !=1.0.0 Not equal to 1.0.0. Excludes version 1.0.0.

Note that spaces between the operator and the version will be gracefully tolerated.

A Range can link multiple Ranges separated by space:

Ranges can be linked by logical AND:

• >1.0.0 <2.0.0 would match between both ranges, so 1.1.1 and 1.8.7 but not 1.0.0 or 2.0.0
• >1.0.0 <3.0.0 !2.0.3-beta.2 would match every version between 1.0.0 and 3.0.0 except 2.0.3-beta.2

Ranges can also be linked by logical OR:

• <2.0.0 || >=3.0.0 would match 1.x.x and 3.x.x but not 2.x.x

AND has a higher precedence than OR. It's not possible to use brackets.

Ranges can be combined by both AND and OR

• >1.0.0 <2.0.0 || >3.0.0 !4.2.1 would match 1.2.3, 1.9.9, 3.1.1, but not 4.2.1, 2.1.1

Range usage:

v, err := semver.Parse("1.2.3")
range, err := semver.ParseRange(">1.0.0 <2.0.0 || >=3.0.0")
if range(v) {
    //valid
}

Example

Have a look at full examples in examples/main.go

import github.com/blang/semver

v, err := semver.Make("0.0.1-alpha.preview+123.github")
fmt.Printf("Major: %d\n", v.Major)
fmt.Printf("Minor: %d\n", v.Minor)
fmt.Printf("Patch: %d\n", v.Patch)
fmt.Printf("Pre: %s\n", v.Pre)
fmt.Printf("Build: %s\n", v.Build)

// Prerelease versions array
if len(v.Pre) > 0 {
    fmt.Println("Prerelease versions:")
    for i, pre := range v.Pre {
        fmt.Printf("%d: %q\n", i, pre)
    }
}

// Build meta data array
if len(v.Build) > 0 {
    fmt.Println("Build meta data:")
    for i, build := range v.Build {
        fmt.Printf("%d: %q\n", i, build)
    }
}

v001, err := semver.Make("0.0.1")
// Compare using helpers: v.GT(v2), v.LT, v.GTE, v.LTE
v001.GT(v) == true
v.LT(v001) == true
v.GTE(v) == true
v.LTE(v) == true

// Or use v.Compare(v2) for comparisons (-1, 0, 1):
v001.Compare(v) == 1
v.Compare(v001) == -1
v.Compare(v) == 0

// Manipulate Version in place:
v.Pre[0], err = semver.NewPRVersion("beta")
if err != nil {
    fmt.Printf("Error parsing pre release version: %q", err)
}

fmt.Println("\nValidate versions:")
v.Build[0] = "?"

err = v.Validate()
if err != nil {
    fmt.Printf("Validation failed: %s\n", err)
}

Benchmarks

BenchmarkParseSimple-4           5000000    390    ns/op    48 B/op   1 allocs/op
BenchmarkParseComplex-4          1000000   1813    ns/op   256 B/op   7 allocs/op
BenchmarkParseAverage-4          1000000   1171    ns/op   163 B/op   4 allocs/op
BenchmarkStringSimple-4         20000000    119    ns/op    16 B/op   1 allocs/op
BenchmarkStringLarger-4         10000000    206    ns/op    32 B/op   2 allocs/op
BenchmarkStringComplex-4         5000000    324    ns/op    80 B/op   3 allocs/op
BenchmarkStringAverage-4         5000000    273    ns/op    53 B/op   2 allocs/op
BenchmarkValidateSimple-4      200000000      9.33 ns/op     0 B/op   0 allocs/op
BenchmarkValidateComplex-4       3000000    469    ns/op     0 B/op   0 allocs/op
BenchmarkValidateAverage-4       5000000    256    ns/op     0 B/op   0 allocs/op
BenchmarkCompareSimple-4       100000000     11.8  ns/op     0 B/op   0 allocs/op
BenchmarkCompareComplex-4       50000000     30.8  ns/op     0 B/op   0 allocs/op
BenchmarkCompareAverage-4       30000000     41.5  ns/op     0 B/op   0 allocs/op
BenchmarkSort-4                  3000000    419    ns/op   256 B/op   2 allocs/op
BenchmarkRangeParseSimple-4      2000000    850    ns/op   192 B/op   5 allocs/op
BenchmarkRangeParseAverage-4     1000000   1677    ns/op   400 B/op  10 allocs/op
BenchmarkRangeParseComplex-4      300000   5214    ns/op  1440 B/op  30 allocs/op
BenchmarkRangeMatchSimple-4     50000000     25.6  ns/op     0 B/op   0 allocs/op
BenchmarkRangeMatchAverage-4    30000000     56.4  ns/op     0 B/op   0 allocs/op
BenchmarkRangeMatchComplex-4    10000000    153    ns/op     0 B/op   0 allocs/op

See benchmark cases at semver_test.go

Motivation

I simply couldn't find any lib supporting the full spec. Others were just wrong or used reflection and regex which i don't like.

Contribution

Feel free to make a pull request. For bigger changes create a issue first to discuss about it.

License

See LICENSE file.

Documentation

Index

• Variables
• func NewBuildVersion(s string) (string, error)
• func Sort(versions []Version)
• type PRVersion
  • func NewPRVersion(s string) (PRVersion, error)
  • func (v PRVersion) Compare(o PRVersion) int
  • func (v PRVersion) IsNumeric() bool
  • func (v PRVersion) String() string
• type Range
  • func MustParseRange(s string) Range
  • func ParseRange(s string) (Range, error)
  • func (rf Range) AND(f Range) Range
  • func (rf Range) OR(f Range) Range
• type Version
  • func Make(s string) (Version, error)
  • func MustParse(s string) Version
  • func New(s string) (vp *Version, err error)
  • func Parse(s string) (Version, error)
  • func ParseTolerant(s string) (Version, error)
  • func (v Version) Compare(o Version) int
  • func (v Version) EQ(o Version) bool
  • func (v Version) Equals(o Version) bool
  • func (v Version) GE(o Version) bool
  • func (v Version) GT(o Version) bool
  • func (v Version) GTE(o Version) bool
  • func (v Version) LE(o Version) bool
  • func (v Version) LT(o Version) bool
  • func (v Version) LTE(o Version) bool
  • func (v Version) MarshalJSON() ([]byte, error)
  • func (v Version) NE(o Version) bool
  • func (v *Version) Scan(src interface{}) (err error)
  • func (v Version) String() string
  • func (v *Version) UnmarshalJSON(data []byte) (err error)
  • func (v Version) Validate() error
  • func (v Version) Value() (driver.Value, error)
• type Versions
  • func (s Versions) Len() int
  • func (s Versions) Less(i, j int) bool
  • func (s Versions) Swap(i, j int)

Variables

var SpecVersion = Version{
	Major: 2,
	Minor: 0,
	Patch: 0,
}

SpecVersion is the latest fully supported spec version of semver

Functions

func NewBuildVersion

func NewBuildVersion(s string) (string, error)

NewBuildVersion creates a new valid build version

func Sort

func Sort(versions []Version)

Sort sorts a slice of versions

Types

type PRVersion

type PRVersion struct {
	VersionStr string
	VersionNum uint64
	IsNum      bool
}

PRVersion represents a PreRelease Version

func NewPRVersion

func NewPRVersion(s string) (PRVersion, error)

NewPRVersion creates a new valid prerelease version

func (PRVersion) Compare

func (v PRVersion) Compare(o PRVersion) int

Compare compares two PreRelease Versions v and o: -1 == v is less than o 0 == v is equal to o 1 == v is greater than o

func (PRVersion) IsNumeric

func (v PRVersion) IsNumeric() bool

IsNumeric checks if prerelease-version is numeric

func (PRVersion) String

func (v PRVersion) String() string

PreRelease version to string

type Range

type Range func(Version) bool

Range represents a range of versions. A Range can be used to check if a Version satisfies it:

range, err := semver.ParseRange(">1.0.0 <2.0.0")
range(semver.MustParse("1.1.1") // returns true

func MustParseRange

func MustParseRange(s string) Range

MustParseRange is like ParseRange but panics if the range cannot be parsed.

func ParseRange

func ParseRange(s string) (Range, error)

ParseRange parses a range and returns a Range. If the range could not be parsed an error is returned.

Valid ranges are:

• "<1.0.0"
• "<=1.0.0"
• ">1.0.0"
• ">=1.0.0"
• "1.0.0", "=1.0.0", "==1.0.0"
• "!1.0.0", "!=1.0.0"

A Range can consist of multiple ranges separated by space: Ranges can be linked by logical AND:

• ">1.0.0 <2.0.0" would match between both ranges, so "1.1.1" and "1.8.7" but not "1.0.0" or "2.0.0"
• ">1.0.0 <3.0.0 !2.0.3-beta.2" would match every version between 1.0.0 and 3.0.0 except 2.0.3-beta.2

Ranges can also be linked by logical OR:

• "<2.0.0 || >=3.0.0" would match "1.x.x" and "3.x.x" but not "2.x.x"

AND has a higher precedence than OR. It's not possible to use brackets.

Ranges can be combined by both AND and OR

• `>1.0.0 <2.0.0 || >3.0.0 !4.2.1` would match `1.2.3`, `1.9.9`, `3.1.1`, but not `4.2.1`, `2.1.1`

func (Range) AND

func (rf Range) AND(f Range) Range

AND combines the existing Range with another Range using logical AND.

func (Range) OR

func (rf Range) OR(f Range) Range

OR combines the existing Range with another Range using logical OR.

type Version

type Version struct {
	Major uint64
	Minor uint64
	Patch uint64
	Pre   []PRVersion
	Build []string //No Precendence
}

Version represents a semver compatible version

func Make

func Make(s string) (Version, error)

Make is an alias for Parse, parses version string and returns a validated Version or error

func MustParse

func MustParse(s string) Version

MustParse is like Parse but panics if the version cannot be parsed.

func New

func New(s string) (vp *Version, err error)

New is an alias for Parse and returns a pointer, parses version string and returns a validated Version or error

func Parse

func Parse(s string) (Version, error)

Parse parses version string and returns a validated Version or error

func ParseTolerant

func ParseTolerant(s string) (Version, error)

ParseTolerant allows for certain version specifications that do not strictly adhere to semver specs to be parsed by this library. It does so by normalizing versions before passing them to Parse(). It currently trims spaces, removes a "v" prefix, and adds a 0 patch number to versions with only major and minor components specified

func (Version) Compare

func (v Version) Compare(o Version) int

Compare compares Versions v to o: -1 == v is less than o 0 == v is equal to o 1 == v is greater than o

func (Version) EQ

func (v Version) EQ(o Version) bool

EQ checks if v is equal to o.

func (Version) Equals

func (v Version) Equals(o Version) bool

Equals checks if v is equal to o.

func (Version) GE

func (v Version) GE(o Version) bool

GE checks if v is greater than or equal to o.

func (Version) GT

func (v Version) GT(o Version) bool

GT checks if v is greater than o.

func (Version) GTE

func (v Version) GTE(o Version) bool

GTE checks if v is greater than or equal to o.

func (Version) LE

func (v Version) LE(o Version) bool

LE checks if v is less than or equal to o.

func (Version) LT

func (v Version) LT(o Version) bool

LT checks if v is less than o.

func (Version) LTE

func (v Version) LTE(o Version) bool

LTE checks if v is less than or equal to o.

func (Version) MarshalJSON

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

MarshalJSON implements the encoding/json.Marshaler interface.

func (Version) NE

func (v Version) NE(o Version) bool

NE checks if v is not equal to o.

func (*Version) Scan

func (v *Version) Scan(src interface{}) (err error)

Scan implements the database/sql.Scanner interface.

func (Version) String

func (v Version) String() string

Version to string

func (*Version) UnmarshalJSON

func (v *Version) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON implements the encoding/json.Unmarshaler interface.

func (Version) Validate

func (v Version) Validate() error

Validate validates v and returns error in case

func (Version) Value

func (v Version) Value() (driver.Value, error)

Value implements the database/sql/driver.Valuer interface.

type Versions

type Versions []Version

Versions represents multiple versions.

func (Versions) Len

func (s Versions) Len() int

Len returns length of version collection

func (Versions) Less

func (s Versions) Less(i, j int) bool

Less checks if version at index i is less than version at index j

func (Versions) Swap

func (s Versions) Swap(i, j int)

Swap swaps two versions inside the collection by its indices