semver

package module
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Nov 23, 2023 License: BSD-3-Clause Imports: 7 Imported by: 40

README

go.bug.st/relaxed-semver build status codecov

A library for handling a superset of semantic versioning in golang.

Documentation and examples

See the godoc here: https://godoc.org/go.bug.st/relaxed-semver

Semantic versioning specification followed in this library

This library tries to implement the semantic versioning specification 2.0.0 with an exception: the numeric format major.minor.patch like 1.3.2 may be truncated if a number is zero, so:

  • 1.2.0 or 1.2.0-beta may be written as 1.2 or 1.2-beta respectively
  • 1.0.0 or 1.0.0-beta may be written 1 or 1-beta respectively
  • 0.0.0 may be written as the empty string, but 0.0.0-beta may not be written as -beta

Usage

You can parse a semver version string with the Parse function that returns a Version object that can be used to be compared with other Version objects using the CompareTo, LessThan , LessThanOrEqual, Equal, GreaterThan and GreaterThanOrEqual methods.

The Parse function returns an error if the string does not comply to the above specification. Alternatively the MustParse function can be used, it returns only the Version object or panics if a parsing error occurs.

Why Relaxed?

This library allows the use of an even more relaxed semver specification using the RelaxedVersion object. It works with the following rules:

  • If the parsed string is a valid semver (following the rules above), then the RelaxedVersion will behave exactly as a normal Version object
  • if the parsed string is not a valid semver, then the string is kept as-is inside the RelaxedVersion object as a custom version string
  • when comparing two RelaxedVersion the rule is simple: if both are valid semver, the semver rules applies; if both are custom version string they are compared as alphanumeric strings; if one is valid semver and the other is a custom version string the valid semver is always greater
  • two RelaxedVersion are compatible (by the CompatibleWith operation) only if
    • they are equal
    • they are both valid semver and they are compatible as per semver specification

The RelaxedVersion object is basically made to allow systems that do not use semver to soft transition to semantic versioning, because it allows an intermediate period where the invalid version is still tolerated.

To parse a RelaxedVersion you can use the ParseRelaxed function.

Version constraints

Dependency version matching can be specified via version constraints, which might be a version range or an exact version.

The following operators are supported:
= equal to
> greater than
>= greater than or equal to
< less than
<= less than or equal to
^ compatible-with
! NOT
&& AND
|| OR
(, ) constraint group
Examples

Given the following releases of a dependency:

  • 0.1.0
  • 0.1.1
  • 0.2.0
  • 1.0.0
  • 2.0.0
  • 2.0.5
  • 2.0.6
  • 2.1.0
  • 3.0.0

constraints conditions would match as follows:

The following condition... will match with versions...
=1.0.0 1.0.0
>1.0.0 2.0.0, 2.0.5, 2.0.6, 2.1.0, 3.0.0
>=1.0.0 1.0.0, 2.0.0, 2.0.5, 2.0.6, 2.1.0, 3.0.0
<2.0.0 0.1.0, 0.1.1, 0.2.0, 1.0.0
<=2.0.0 0.1.0, 0.1.1, 0.2.0, 1.0.0, 2.0.0
!=1.0.0 0.1.0, 0.1.1, 0.2.0, 2.0.0, 2.0.5, 2.0.6, 2.1.0, 3.0.0
>1.0.0 && <2.1.0 2.0.0, 2.0.5, 2.0.6
<1.0.0 || >2.0.0 0.1.0, 0.1.1, 0.2.0, 2.0.5, 2.0.6, 2.1.0, 3.0.0
(>0.1.0 && <2.0.0) || >2.0.5 0.1.1, 0.2.0, 1.0.0, 2.0.6, 2.1.0, 3.0.0
^2.0.5 2.0.5, 2.0.6, 2.1.0
^0.1.0 0.1.0, 0.1.1

Json parsable

The Version and RelaxedVersion have the JSON un/marshaler implemented so they can be JSON decoded/encoded.

Binary/GOB encoding support

The Version and RelaxedVersion provides optimized MarshalBinary/UnmarshalBinary methods for binary encoding.

Yaml parsable with gopkg.in/yaml.v3

The Version and RelaxedVersion have the YAML un/marshaler implemented so they can be YAML decoded/encoded with the excellent gopkg.in/yaml.v3 library.

Documentation

Index

Examples

Constants

This section is empty.

Variables

View Source 
var WarnInvalidVersionWhenParsingRelaxed = false

WarnInvalidVersionWhenParsingRelaxed must be set to true to show warnings while parsing RelaxedVersion if an invalid semver string is found. This allows a soft transition to strict semver

Functions

This section is empty.

Types

type And 

type And struct {
	Operands []Constraint
}

And will match if ALL the Operands Constraint will match

func (*And) Match 

func (and *And) Match(v *Version) bool

Match returns true if v satisfies the condition

func (*And) String 

func (and *And) String() string

type CompatibleWith added in v0.10.0 

type CompatibleWith struct {
	Version *Version
}

CompatibleWith is the "compatible with" (^) constraint

func (*CompatibleWith) Match added in v0.10.0 

func (cw *CompatibleWith) Match(v *Version) bool

Match returns true if v satisfies the condition

func (*CompatibleWith) String added in v0.10.0 

func (cw *CompatibleWith) String() string

type Constraint 

type Constraint interface {
	// Match returns true if the Version satisfies the condition
	Match(*Version) bool

	String() string
}

Constraint is a condition that a Version can match or not

func ParseConstraint 

func ParseConstraint(in string) (Constraint, error)

ParseConstraint converts a string into a Constraint. The resulting Constraint may be converted back to string using the String() method.

type Dependency 

type Dependency interface {
	GetName() string
	GetConstraint() Constraint
}

Dependency represents a dependency, it must provide methods to return Name and Constraints

type Equals 

type Equals struct {
	Version *Version
}

Equals is the equality (=) constraint

func (*Equals) Match 

func (eq *Equals) Match(v *Version) bool

Match returns true if v satisfies the condition

func (*Equals) String 

func (eq *Equals) String() string

type GreaterThan 

type GreaterThan struct {
	Version *Version
}

GreaterThan is the "greater than" (>) constraint

func (*GreaterThan) Match 

func (gt *GreaterThan) Match(v *Version) bool

Match returns true if v satisfies the condition

func (*GreaterThan) String 

func (gt *GreaterThan) String() string

type GreaterThanOrEqual 

type GreaterThanOrEqual struct {
	Version *Version
}

GreaterThanOrEqual is the "greater than or equal" (>=) constraint

func (*GreaterThanOrEqual) Match 

func (gte *GreaterThanOrEqual) Match(v *Version) bool

Match returns true if v satisfies the condition

func (*GreaterThanOrEqual) String 

func (gte *GreaterThanOrEqual) String() string

type LessThan 

type LessThan struct {
	Version *Version
}

LessThan is the less than (<) constraint

func (*LessThan) Match 

func (lt *LessThan) Match(v *Version) bool

Match returns true if v satisfies the condition

func (*LessThan) String 

func (lt *LessThan) String() string

type LessThanOrEqual 

type LessThanOrEqual struct {
	Version *Version
}

LessThanOrEqual is the "less than or equal" (<=) constraint

func (*LessThanOrEqual) Match 

func (lte *LessThanOrEqual) Match(v *Version) bool

Match returns true if v satisfies the condition

func (*LessThanOrEqual) String 

func (lte *LessThanOrEqual) String() string

type List 

type List []*Version

List is a list of Versions

func (List) Len 

func (l List) Len() int

func (List) Less 

func (l List) Less(i, j int) bool

func (List) Swap 

func (l List) Swap(i, j int)

type NormalizedString added in v0.10.0 

type NormalizedString string

NormalizedString is a datatype to be used in maps and other places where the version is used as a key.

type Not 

type Not struct {
	Operand Constraint
}

Not match if Operand does not match and viceversa

func (*Not) Match 

func (not *Not) Match(v *Version) bool

Match returns ture if v does NOT satisfies the condition

func (*Not) String 

func (not *Not) String() string

type Or 

type Or struct {
	Operands []Constraint
}

Or will match if ANY of the Operands Constraint will match

func (*Or) Match 

func (or *Or) Match(v *Version) bool

Match returns true if v satisfies the condition

func (*Or) String 

func (or *Or) String() string

type RelaxedVersion 

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

RelaxedVersion allows any possible version string. If the version does not comply with semantic versioning it is saved as-is and only Equal comparison will match.

func ParseRelaxed 

func ParseRelaxed(in string) *RelaxedVersion

ParseRelaxed parse a RelaxedVersion

Example 
WarnInvalidVersionWhenParsingRelaxed = true
ParseRelaxed("bad")
WarnInvalidVersionWhenParsingRelaxed = false

Output:

WARNING invalid semver version bad: no major version found

func (*RelaxedVersion) CompareTo 

func (v *RelaxedVersion) CompareTo(u *RelaxedVersion) int

CompareTo compares the RelaxedVersion with the one passed as parameter. Returns -1, 0 or 1 if the version is respectively less than, equal or greater than the compared Version

func (*RelaxedVersion) CompatibleWith added in v0.10.0 

func (v *RelaxedVersion) CompatibleWith(u *RelaxedVersion) bool

CompatibleWith returns true if the RelaxedVersion is compatible with the RelaxedVersion passed as paramater

func (*RelaxedVersion) Equal 

func (v *RelaxedVersion) Equal(u *RelaxedVersion) bool

Equal returns true if the RelaxedVersion is equal to the RelaxedVersion passed as parameter

func (*RelaxedVersion) GreaterThan 

func (v *RelaxedVersion) GreaterThan(u *RelaxedVersion) bool

GreaterThan returns true if the RelaxedVersion is greater than the RelaxedVersion passed as parameter

func (*RelaxedVersion) GreaterThanOrEqual 

func (v *RelaxedVersion) GreaterThanOrEqual(u *RelaxedVersion) bool

GreaterThanOrEqual returns true if the RelaxedVersion is greater than or equal to the RelaxedVersion passed as parameter

func (*RelaxedVersion) LessThan 

func (v *RelaxedVersion) LessThan(u *RelaxedVersion) bool

LessThan returns true if the RelaxedVersion is less than the RelaxedVersion passed as parameter

func (*RelaxedVersion) LessThanOrEqual 

func (v *RelaxedVersion) LessThanOrEqual(u *RelaxedVersion) bool

LessThanOrEqual returns true if the RelaxedVersion is less than or equal to the RelaxedVersion passed as parameter

func (*RelaxedVersion) MarshalBinary added in v0.10.0 

func (v *RelaxedVersion) MarshalBinary() ([]byte, error)

MarshalBinary implements json.Marshaler

func (*RelaxedVersion) MarshalJSON 

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

MarshalJSON implements json.Marshaler

func (*RelaxedVersion) MarshalYAML added in v0.11.0 

func (v *RelaxedVersion) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler

func (*RelaxedVersion) NormalizedString added in v0.10.0 

func (v *RelaxedVersion) NormalizedString() NormalizedString

NormalizedString return a string representation of the version that is normalized (always have a major, minor and patch version when semver compliant). This is useful to be used in maps and other places where the version is used as a key.

func (*RelaxedVersion) String 

func (v *RelaxedVersion) String() string

func (*RelaxedVersion) UnmarshalBinary added in v0.10.0 

func (v *RelaxedVersion) UnmarshalBinary(data []byte) error

UnmarshalBinary implements json.Unmarshaler

func (*RelaxedVersion) UnmarshalJSON 

func (v *RelaxedVersion) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler

func (*RelaxedVersion) UnmarshalYAML added in v0.11.0 

func (v *RelaxedVersion) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler

type Release 

type Release[D Dependency] interface {
	GetName() string
	GetVersion() *Version
	GetDependencies() []D
}

Release represents a release, it must provide methods to return Name, Version and Dependencies

type Releases 

type Releases[R Release[D], D Dependency] []R

Releases is a list of Release of the same package (all releases with the same Name but different Version)

func (Releases[R, D]) FilterBy 

func (set Releases[R, D]) FilterBy(c Constraint) Releases[R, D]

FilterBy return a subset of the Releases matching the provided Constraint

func (Releases[R, D]) SortDescent 

func (set Releases[R, D]) SortDescent()

SortDescent sort the Releases in this set in descending order (the lastest release is the first)

type Resolver added in v0.12.0 

type Resolver[R Release[D], D Dependency] struct {
	// contains filtered or unexported fields
}

Resolver is a container with references to all Releases to consider for dependency resolution

func NewResolver added in v0.12.0 

func NewResolver[R Release[D], D Dependency]() *Resolver[R, D]

NewResolver creates a new archive

func (*Resolver[R, D]) AddRelease added in v0.12.0 

func (ar *Resolver[R, D]) AddRelease(rel R)

AddRelease adds a release to this archive

func (*Resolver[R, D]) AddReleases added in v0.12.0 

func (ar *Resolver[R, D]) AddReleases(rels ...R)

AddReleases adds all the releases to this archive

func (*Resolver[R, D]) Resolve added in v0.12.0 

func (ar *Resolver[R, D]) Resolve(release R) Releases[R, D]

Resolve will try to depp-resolve dependencies from the Release passed as arguent using a backtracking algorithm. This function is NOT thread-safe.

type True 

type True struct {
}

True is the empty constraint

func (*True) Match 

func (t *True) Match(v *Version) bool

Match always return true

func (*True) String 

func (t *True) String() string

type Version 

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

Version contains the results of parsed version string

func MustParse 

func MustParse(inVersion string) *Version

MustParse parse a version string and panic if the parsing fails

func Parse 

func Parse(inVersion string) (*Version, error)

Parse parse a version string

func (*Version) CompareTo 

func (v *Version) CompareTo(u *Version) int

CompareTo compares the Version with the one passed as parameter. Returns -1, 0 or 1 if the version is respectively less than, equal or greater than the compared Version

func (*Version) CompatibleWith added in v0.10.0 

func (v *Version) CompatibleWith(u *Version) bool

CompatibleWith returns true if the Version is compatible with the version passed as paramater

func (*Version) Equal 

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

Equal returns true if the Version is equal to the Version passed as parameter

func (*Version) GreaterThan 

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

GreaterThan returns true if the Version is greater than the Version passed as parameter

func (*Version) GreaterThanOrEqual 

func (v *Version) GreaterThanOrEqual(u *Version) bool

GreaterThanOrEqual returns true if the Version is greater than or equal to the Version passed as parameter

func (*Version) LessThan 

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

LessThan returns true if the Version is less than the Version passed as parameter

func (*Version) LessThanOrEqual 

func (v *Version) LessThanOrEqual(u *Version) bool

LessThanOrEqual returns true if the Version is less than or equal to the Version passed as parameter

func (*Version) MarshalBinary added in v0.10.0 

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

MarshalBinary implements binary custom encoding

func (*Version) MarshalJSON 

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

MarshalJSON implements json.Marshaler

func (*Version) MarshalYAML added in v0.11.0 

func (v *Version) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler

func (*Version) Normalize 

func (v *Version) Normalize()

Normalize transforms a truncated semver version in a strictly compliant semver version by adding minor and patch versions. For example: "1" is trasformed to "1.0.0" or "2.5-dev" to "2.5.0-dev"

func (*Version) NormalizedString added in v0.10.0 

func (v *Version) NormalizedString() NormalizedString

NormalizedString return a string representation of the version that is normalized to always have a major, minor and patch version. This is useful to be used in maps and other places where the version is used as a key.

func (*Version) String 

func (v *Version) String() string

func (*Version) UnmarshalBinary added in v0.10.0 

func (v *Version) UnmarshalBinary(data []byte) error

UnmarshalJSON implements binary custom decoding

func (*Version) UnmarshalJSON 

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

UnmarshalJSON implements json.Unmarshaler

func (*Version) UnmarshalYAML added in v0.11.0 

func (v *Version) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler

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.