vc

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Sep 8, 2023 License: MIT Imports: 6 Imported by: 0

README ¶

vc

Compare version strings to find greater, equal or lesser. Provides the ability to work with Semantic Versions (http://semver.org) in Go.

Inspired by Masterminds/semver.

test Codecov Go Report Card Release License

Get Started

Semver Versions

v, err := vc.NewSemverStr("0.1.2")

v := NewSemver(0, 1, 2, "", "")

Calendar Versions

v, err := vc.NewCalVerStr("2023.07.05")

v := NewCalVer(2023, 7, 5, "")

Constraints

con, _ := NewConstraint(">=1.1 <2", func(s string) (Comparable, error) {
  return NewSemverStr(s)
})
v, _ := NewSemverStr("1.2.3")

a := con.Check(v)
if a != tc.valid {
    fmt.Printf("Constraint '%s' failing with '%s'", tc.con, tc.ver)
}

// Or
a, _ = con.CheckString("1.2.3")
if a != tc.valid {
    fmt.Printf("Constraint '%s' failing with '%s'", tc.con, tc.ver)
}
Basic Comparisons

There are two elements to the comparisons. First, a comparison string is a list of space separated AND comparisons. These are then separated by || (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.0 <=1.4.5
  • 2.3.4 - 4.5 which is equivalent to >=2.3.4 <=4.5.0
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 patch 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.0.0
  • * 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 once a stable (1.0.0) release has occurred. Prior to a 1.0.0 release the minor versions acts as the API stability level. 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
  • ^0.2.3 is equivalent to >=0.2.3 <0.3.0
  • ^0.2 is equivalent to >=0.2.0 <0.3.0
  • ^0.0.3 is equivalent to >=0.0.3 <0.0.4
  • ^0.0 is equivalent to >=0.0.0 <0.1.0
  • ^0 is equivalent to >=0.0.0 <1.0.0
Comparable Interface

An implementation of Comparable interface can be compared with constraints.

type Comparable interface {
	// Version converts major,minor and patch to a string.
	Version() string
	// Major returns the major version.
	Major() uint64
	// Minor returns the minor version.
	Minor() uint64
	// Patch returns the patch version.
	Patch() uint64
	// Prerelease returns the prerelease version.
	Prerelease() string
	// IncMajor produces the next major version.
	IncMajor() Comparable
	// IncMinor produces the next minor version.
	IncMinor() Comparable
	// IncPatch produces the next patch version.
	IncPatch() Comparable
}

🔋 JetBrains OS licenses

vc had been being developed with IntelliJ IDEA under the free JetBrains Open Source license(s) granted by JetBrains s.r.o., hence I would like to express my thanks here.

JetBrains Logo (Main) logo.

Documentation ¶

Overview ¶

Package vc compare version strings to find greater, equal or lesser. Provides the ability to work with Semantic Versions (http://semver.org) in Go.

Index ¶

Constants ¶

View Source 
const (
	OperatorGte   = ">="
	OperatorGt    = ">"
	OperatorLte   = "<="
	OperatorLt    = "<"
	OperatorEq    = "="
	OperatorRange = " - "
	OperatorCaret = "^"
	OperatorTilde = "~"
)
View Source 
const (
	VersionAll      = "*"
	VersionX        = "x"
	VersionMinimum  = "0.0.0"
	VersionAllAlias = OperatorGte + VersionMinimum
)

Variables ¶

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

	// ErrInvalidCalVer is returned a version is found to be invalid when
	// being parsed.
	ErrInvalidCalVer = errors.New("invalid calendar version")

	// ErrInvalidConstraint is returned a constraint is found to be invalid when
	// being parsed.
	ErrInvalidConstraint = errors.New("invalid constraint")

	// ErrSegmentStartsZero is returned when a version segment starts with 0.
	// This is invalid in SemVer.
	ErrSegmentStartsZero = errors.New("version segment starts with 0")

	// 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 ¶

func Compare ¶ 

func Compare(v1, v2 Comparable) int

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

Prerelease is lower than the version without a prerelease. Compare always takes into account prerelease. If you want to work with ranges using typical range syntax that skip prerelease if the range is not looking for them use constraints.

func Eq ¶ 

func Eq(v1, v2 Comparable) bool

Eq 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 Gt ¶ 

func Gt(v1, v2 Comparable) bool

Gt tests if one version is greater than another one.

func Lt ¶ 

func Lt(v1, v2 Comparable) bool

Lt tests if one version is less than another one.

Types ¶

type CalVer ¶ 

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

func NewCalVer ¶ 

func NewCalVer(major, minor, patch uint64, pre string) *CalVer

NewCalVer creates a new instance of CalVer with each of the parts passed in as arguments instead of parsing a version string.

func NewCalVerStr ¶ 

func NewCalVerStr(ver string) (*CalVer, error)

NewCalVerStr parses a given version and returns an instance of CalVer or an error if unable to parse the version. If the version is SemVer-ish it attempts to convert it to CalVer.

func (*CalVer) Compare ¶ 

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

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

func (*CalVer) Eq ¶ 

func (v *CalVer) Eq(o *CalVer) bool

Eq tests if two versions are equal to each other.

func (*CalVer) Gt ¶ 

func (v *CalVer) Gt(o *CalVer) bool

Gt tests if one version is greater than another one.

func (*CalVer) IncMajor ¶ 

func (v *CalVer) IncMajor() Comparable

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

func (*CalVer) IncMinor ¶ 

func (v *CalVer) IncMinor() Comparable

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

func (*CalVer) IncPatch ¶ 

func (v *CalVer) IncPatch() Comparable

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

func (*CalVer) Lt ¶ 

func (v *CalVer) Lt(o *CalVer) bool

Lt tests if one version is less than another one.

func (*CalVer) Major ¶ 

func (v *CalVer) Major() uint64

Major returns the major version.

func (*CalVer) Metadata ¶ 

func (v *CalVer) Metadata() string

Metadata returns empty string.

func (*CalVer) Minor ¶ 

func (v *CalVer) Minor() uint64

Minor returns the minor version.

func (*CalVer) Original ¶ 

func (v *CalVer) Original() string

Original returns the original value passed in to be parsed.

func (*CalVer) Patch ¶ 

func (v *CalVer) Patch() uint64

Patch returns the patch version.

func (*CalVer) Prerelease ¶ 

func (v *CalVer) Prerelease() string

Prerelease returns the prerelease version.

func (*CalVer) String ¶ 

func (v *CalVer) String() string

String converts a CalVer 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 (*CalVer) Version ¶ 

func (v *CalVer) Version() string

Version converts major,minor and patch to a string.

type Comparable ¶ 

type Comparable interface {
	// Version converts major,minor and patch to a string.
	Version() string
	// Major returns the major version.
	Major() uint64
	// Minor returns the minor version.
	Minor() uint64
	// Patch returns the patch version.
	Patch() uint64
	// Prerelease returns the prerelease version.
	Prerelease() string
	// IncMajor produces the next major version.
	IncMajor() Comparable
	// IncMinor produces the next minor version.
	IncMinor() Comparable
	// IncPatch produces the next patch version.
	IncPatch() Comparable
}

Comparable An implementation of Comparable interface can be compared with constraints.

type Constraints ¶ 

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

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

func NewConstraint ¶ 

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

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

func (*Constraints) Check ¶ 

func (c *Constraints) Check(ver Comparable) bool

func (*Constraints) CheckString ¶ 

func (c *Constraints) CheckString(ver string) (bool, error)

type New ¶ 

type New func(string) (Comparable, error)

New a function to generate a Comparable instance.

type Semver ¶ 

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

func NewSemver ¶ 

func NewSemver(major, minor, patch uint64, pre, metadata string) *Semver

NewSemver creates a new instance of Semver with each of the parts passed in as arguments instead of parsing a version string.

func NewSemverStr ¶ 

func NewSemverStr(ver string) (*Semver, error)

NewSemverStr parses a given version and returns an instance of Semver or an error if unable to parse the version. If the version is SemVer-ish it attempts to convert it to Semver.

func (*Semver) Compare ¶ 

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

Compare compares this version to another Semver. 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. Compare always takes into account prereleases. If you want to work with ranges using typical range syntaxes that skip prereleases if the range is not looking for them use constraints.

func (*Semver) Eq ¶ 

func (v *Semver) Eq(o *Semver) bool

Eq 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 (*Semver) Gt ¶ 

func (v *Semver) Gt(o *Semver) bool

Gt tests if one version is greater than another one.

func (*Semver) IncMajor ¶ 

func (v *Semver) IncMajor() Comparable

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

func (*Semver) IncMinor ¶ 

func (v *Semver) IncMinor() Comparable

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

func (*Semver) IncPatch ¶ 

func (v *Semver) IncPatch() Comparable

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 current patch value

func (*Semver) Lt ¶ 

func (v *Semver) Lt(o *Semver) bool

Lt tests if one version is less than another one.

func (*Semver) Major ¶ 

func (v *Semver) Major() uint64

Major returns the major version.

func (*Semver) Metadata ¶ 

func (v *Semver) Metadata() string

Metadata returns the metadata on the version.

func (*Semver) Minor ¶ 

func (v *Semver) Minor() uint64

Minor returns the minor version.

func (*Semver) Original ¶ 

func (v *Semver) Original() string

Original returns the original value passed in to be parsed.

func (*Semver) Patch ¶ 

func (v *Semver) Patch() uint64

Patch returns the patch version.

func (*Semver) Prerelease ¶ 

func (v *Semver) Prerelease() string

Prerelease returns the prerelease version.

func (*Semver) String ¶ 

func (v *Semver) String() string

String converts a Semver 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 (*Semver) Version ¶ 

func (v *Semver) Version() string

Version converts major,minor and patch to a string.

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.