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.New("1.0.0-beta")
v2, err := semver.New("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
• Sortable (implements sort.Interface)
• database/sql compatible (sql.Scanner/Valuer)
• encoding/json compatible (json.Marshaler/Unmarshaler)

Example

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

import github.com/blang/semver

v, err := semver.New("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.New("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         5000000      328    ns/op    49 B/op   1 allocs/op
BenchmarkParseComplex        1000000     2105    ns/op   263 B/op   7 allocs/op
BenchmarkParseAverage        1000000     1301    ns/op   168 B/op   4 allocs/op
BenchmarkStringSimple       10000000      130    ns/op     5 B/op   1 allocs/op
BenchmarkStringLarger        5000000      280    ns/op    32 B/op   2 allocs/op
BenchmarkStringComplex       3000000      512    ns/op    80 B/op   3 allocs/op
BenchmarkStringAverage       5000000      387    ns/op    47 B/op   2 allocs/op
BenchmarkValidateSimple    500000000        7.92 ns/op     0 B/op   0 allocs/op
BenchmarkValidateComplex     2000000      923    ns/op     0 B/op   0 allocs/op
BenchmarkValidateAverage     5000000      452    ns/op     0 B/op   0 allocs/op
BenchmarkCompareSimple     100000000       11.2  ns/op     0 B/op   0 allocs/op
BenchmarkCompareComplex     50000000       40.9  ns/op     0 B/op   0 allocs/op
BenchmarkCompareAverage     50000000       43.8  ns/op     0 B/op   0 allocs/op
BenchmarkSort                5000000      436    ns/op   259 B/op   2 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 Version
  • func MustParse(s string) Version
  • func New(s string) (Version, error)
  • func Parse(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 (s 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 SPEC_VERSION = Version{
	Major: 2,
	Minor: 0,
	Patch: 0,
}

Latest fully supported spec version

Functions

func NewBuildVersion

func NewBuildVersion(s string) (string, error)

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
}

PreRelease Version

func NewPRVersion

func NewPRVersion(s string) (PRVersion, error)

Creates a new valid prerelease version

func (PRVersion) Compare

func (v PRVersion) Compare(o PRVersion) int

Compares PreRelease Versions v to 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

Is pre release version numeric?

func (PRVersion) String

func (v PRVersion) String() string

PreRelease version to string

type Version

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

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) (Version, error)

Alias for Parse, parses version string and returns a validated Version or error

func Parse

func Parse(s string) (Version, error)

Parses version string and returns a validated Version or error

func (Version) Compare

func (v Version) Compare(o Version) int

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

Checks if v is equal to o.

func (Version) Equals

func (v Version) Equals(o Version) bool

Checks if v is equal to o.

func (Version) GE

func (v Version) GE(o Version) bool

Checks if v is greater than or equal to o.

func (Version) GT

func (v Version) GT(o Version) bool

Checks if v is greater than o.

func (Version) GTE

func (v Version) GTE(o Version) bool

Checks if v is greater than or equal to o.

func (Version) LE

func (v Version) LE(o Version) bool

Checks if v is less than or equal to o.

func (Version) LT

func (v Version) LT(o Version) bool

Checks if v is less than o.

func (Version) LTE

func (v Version) LTE(o Version) bool

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

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

Validates v and returns error in case

func (Version) Value

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

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

type Versions

type Versions []Version

func (Versions) Len

func (s Versions) Len() int

func (Versions) Less

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

func (Versions) Swap

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