semver

README

semver — pkgx-compatible versions & ranges for Go

A faithful Go port of pkgx's version scheme (libpkgx's semver.ts). It is deliberately not strict SemVer 2.0: the open-source world ships many "almost valid" versions that node-semver and the Go semver libraries (Masterminds/semver, golang.org/x/mod/semver, blang/semver) reject —

• openssl 1.1.1w — a trailing letter (→ its 1-based alphabet index)
• ghc 5.64.3.2 — four components
• bare v prefixes

— plus pkgx's own @ range operator and CalVer sorting. This is the shared implementation for the go-pkgx family (bottle / pkgm / pkgx / mirror / bk), so every tool resolves versions identically.

Usage

v, _ := semver.ParseVersion("1.1.1w")   // openssl-style
r, _ := semver.ParseRange("^1.1")       // ^ ~ < = @ >=x<y * , ||
r.Satisfies(v)                          // true

a, _ := semver.NewRange("^1")
b, _ := semver.NewRange(">=1.2 <1.5")
c, _ := semver.Intersect(a, b)          // range algebra

• ParseVersion / MustParseVersion — the loose version parser.
• Version.Compare and EQ/NEQ/GT/GTE/LT/LTE — CalVer (major > 1996) sorts before SemVer.
• NewRange (strict) / ParseRange (tolerant: a bare 5.1 becomes @5.1).
• Range.Satisfies, Range.Max, Range.Single, Range.String, and Intersect.

100% statement coverage; builds CGO_ENABLED=0 on every arch. BSD-3-Clause.

Documentation

Overview

Package semver is a faithful Go port of pkgx's version scheme (libpkgx's semver.ts). It is deliberately NOT strict SemVer 2.0: open-source ships many "almost valid" versions that node-semver and the Go semver libraries reject — openssl 1.1.1w (a trailing letter), ghc 5.64.3.2 (four components), bare v-prefixes — plus pkgx's own `@` range operator and CalVer sorting. This is the shared implementation for the go-pkgx family (bottle/pkgm/pkgx/mirror/bk).

Index

• type Range
  • func Intersect(a, b *Range) (*Range, error)
  • func NewRange(input string) (*Range, error)
  • func ParseRange(input string) (*Range, error)
  • func (r *Range) Max(versions []*Version) *Version
  • func (r *Range) Satisfies(version *Version) bool
  • func (r *Range) Single() *Version
  • func (r *Range) String() string
• type Version
  • func MustParseVersion(input string) *Version
  • func ParseVersion(input string) (*Version, error)
  • func (v *Version) Compare(that *Version) int
  • func (v *Version) EQ(o *Version) bool
  • func (v *Version) GT(o *Version) bool
  • func (v *Version) GTE(o *Version) bool
  • func (v *Version) LT(o *Version) bool
  • func (v *Version) LTE(o *Version) bool
  • func (v *Version) NEQ(o *Version) bool
  • func (v *Version) String() string

Types

type Range

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

Range is a pkgx version constraint: `*`, `^1`, `~1.2`, `<3`, `=1.2.3`, `@5`, `>=1 <2`, or several of those joined by `,` / `||`.

func Intersect

func Intersect(a, b *Range) (*Range, error)

Intersect returns the range satisfied by both a and b, or an error when they are disjoint.

func NewRange

func NewRange(input string) (*Range, error)

NewRange parses a range string. It is strict: use Parse for the tolerant form.

func ParseRange

func ParseRange(input string) (*Range, error)

ParseRange is the tolerant range parser: a bare version (eg. "5.1") that isn't a valid range is treated as `@5.1`, matching what users expect.

func (*Range) Max

func (r *Range) Max(versions []*Version) *Version

Max returns the greatest version satisfying the range, or nil.

func (*Range) Satisfies

func (r *Range) Satisfies(version *Version) bool

Satisfies reports whether version is within the range.

func (*Range) Single

func (r *Range) Single() *Version

Single returns the sole exact version a range denotes, or nil.

func (*Range) String

func (r *Range) String() string

String renders the range back to pkgx range syntax.

type Version

type Version struct {
	Components          []int
	Major, Minor, Patch int
	Raw                 string
	// contains filtered or unexported fields
}

Version is a parsed pkgx version. Components holds every numeric part (a trailing letter like the "w" in 1.1.1w becomes its 1-based alphabet index).

func MustParseVersion

func MustParseVersion(input string) *Version

MustParseVersion is ParseVersion but panics on error — for constants/tests.

func ParseVersion

func ParseVersion(input string) (*Version, error)

ParseVersion parses a version string, tolerating pkgx's loose scheme.

func (*Version) Compare

func (v *Version) Compare(that *Version) int

Compare returns -1, 0 or 1. Components beyond one operand default to 0, and a CalVer major (>1996) sorts before a SemVer major (pkgx labels pre-releases with CalVer).

func (*Version) EQ

func (v *Version) EQ(o *Version) bool

Comparison helpers.

func (*Version) GT

func (v *Version) GT(o *Version) bool

func (*Version) GTE

func (v *Version) GTE(o *Version) bool

func (*Version) LT

func (v *Version) LT(o *Version) bool

func (*Version) LTE

func (v *Version) LTE(o *Version) bool

func (*Version) NEQ

func (v *Version) NEQ(o *Version) bool

func (*Version) String

func (v *Version) String() string

String renders the version: its pretty form (for lettered versions), else the canonical major.minor.patch, or the full component join for 4+ components.