version

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Feb 3, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package version provides semantic versioning utilities for the ApertureStack ecosystem.

This package handles version parsing, comparison, compatibility checking, and version negotiation for tool and protocol versions.

Parsing Versions

Parse semantic version strings: 

v, err := version.Parse("1.2.3")
v, err := version.Parse("v2.0.0-beta.1+build.123")

Comparing Versions 

v1 := version.MustParse("1.0.0")
v2 := version.MustParse("2.0.0")

v1.LessThan(v2)    // true
v1.GreaterThan(v2) // false
v1.Equal(v2)       // false
v1.Compatible(v2)  // false (different major)

Version Constraints

Parse and check version constraints: 

c, _ := version.ParseConstraint(">=1.0.0")
c.Check(version.MustParse("1.5.0")) // true
c.Check(version.MustParse("0.9.0")) // false

Supported constraint operators:

  • "=" or "" - exact match
  • ">" - greater than
  • ">=" - greater than or equal
  • "<" - less than
  • "<=" - less than or equal
  • "^" - compatible (same major)
  • "~" - approximately (same major.minor)

Compatibility Matrix

Track version compatibility across components: 

matrix := version.NewMatrix()
matrix.Add(version.Compatibility{
    Component:  "toolfoundation",
    MinVersion: version.MustParse("0.1.0"),
})

ok, msg := matrix.Check("toolfoundation", version.MustParse("0.2.0"))

Version Negotiation

Find the best compatible version from available options: 

available := []version.Version{
    version.MustParse("1.0.0"),
    version.MustParse("1.1.0"),
    version.MustParse("2.0.0"),
}
best, err := matrix.Negotiate("component", available)

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Compatibility 

type Compatibility struct {
	Component  string
	MinVersion Version
	MaxVersion *Version // nil means no upper bound
	Deprecated bool
	Message    string
}

Compatibility represents version compatibility between components.

Example (Deprecated) 
package main

import (
	"fmt"

	"github.com/jonwraymond/toolfoundation/version"
)

func main() {
	matrix := version.NewMatrix()

	// Mark a component as deprecated
	matrix.Add(version.Compatibility{
		Component:  "old-api",
		MinVersion: version.MustParse("1.0.0"),
		Deprecated: true,
		Message:    "Use new-api instead",
	})

	ok, msg := matrix.Check("old-api", version.MustParse("1.5.0"))
	fmt.Println("Still compatible:", ok)
	fmt.Println("Deprecation notice:", msg)
}

Output:

Still compatible: true
Deprecation notice: Use new-api instead

type Constraint 

type Constraint struct {
	Op      string // "", "=", ">", ">=", "<", "<=", "^", "~"
	Version Version
}

Constraint represents a version constraint (e.g., ">=1.0.0", "^2.0.0").

func ParseConstraint 

func ParseConstraint(s string) (Constraint, error)

ParseConstraint parses a version constraint string.

Example 
package main

import (
	"fmt"

	"github.com/jonwraymond/toolfoundation/version"
)

func main() {
	constraints := []string{
		">=1.0.0",
		"<2.0.0",
		"^1.5.0",
		"~1.2.0",
	}

	testVersion := version.MustParse("1.8.0")

	for _, cs := range constraints {
		c, _ := version.ParseConstraint(cs)
		fmt.Printf("%s matches 1.8.0: %v\n", cs, c.Check(testVersion))
	}
}

Output:

>=1.0.0 matches 1.8.0: true
<2.0.0 matches 1.8.0: true
^1.5.0 matches 1.8.0: true
~1.2.0 matches 1.8.0: false

func (Constraint) Check 

func (c Constraint) Check(v Version) bool

Check returns true if the given version satisfies the constraint.

Example 
package main

import (
	"fmt"

	"github.com/jonwraymond/toolfoundation/version"
)

func main() {
	// Caret constraint: same major version
	caret, _ := version.ParseConstraint("^1.0.0")

	fmt.Println("^1.0.0 accepts 1.5.0:", caret.Check(version.MustParse("1.5.0")))
	fmt.Println("^1.0.0 accepts 2.0.0:", caret.Check(version.MustParse("2.0.0")))

	// Tilde constraint: same major.minor version
	tilde, _ := version.ParseConstraint("~1.2.0")

	fmt.Println("~1.2.0 accepts 1.2.5:", tilde.Check(version.MustParse("1.2.5")))
	fmt.Println("~1.2.0 accepts 1.3.0:", tilde.Check(version.MustParse("1.3.0")))
}

Output:

^1.0.0 accepts 1.5.0: true
^1.0.0 accepts 2.0.0: false
~1.2.0 accepts 1.2.5: true
~1.2.0 accepts 1.3.0: false

func (Constraint) String 

func (c Constraint) String() string

String returns the constraint as a string.

type Matrix 

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

Matrix holds compatibility information for multiple components. Matrix is safe for concurrent use by multiple goroutines.

Example 
package main

import (
	"fmt"

	"github.com/jonwraymond/toolfoundation/version"
)

func main() {
	matrix := version.NewMatrix()

	// Define compatibility requirements
	matrix.Add(version.Compatibility{
		Component:  "toolfoundation",
		MinVersion: version.MustParse("0.1.0"),
	})

	// Check a version
	ok, msg := matrix.Check("toolfoundation", version.MustParse("0.2.0"))
	fmt.Println("0.2.0 compatible:", ok)
	if msg == "" {
		fmt.Println("Message: (empty)")
	} else {
		fmt.Println("Message:", msg)
	}

	// Check an incompatible version
	ok, _ = matrix.Check("toolfoundation", version.MustParse("0.0.5"))
	fmt.Println("0.0.5 compatible:", ok)
}

Output:

0.2.0 compatible: true
Message: (empty)
0.0.5 compatible: false

func NewMatrix 

func NewMatrix() *Matrix

NewMatrix creates a new compatibility matrix.

func (*Matrix) Add 

func (m *Matrix) Add(comp Compatibility)

Add adds a compatibility entry for a component. Add is safe for concurrent use.

func (*Matrix) Check 

func (m *Matrix) Check(component string, v Version) (bool, string)

Check checks if a version is compatible for a component. Check is safe for concurrent use.

func (*Matrix) Negotiate 

func (m *Matrix) Negotiate(component string, available []Version) (Version, error)

Negotiate finds the best compatible version from a list. Negotiate is safe for concurrent use.

Example 
package main

import (
	"fmt"
	"log"

	"github.com/jonwraymond/toolfoundation/version"
)

func main() {
	matrix := version.NewMatrix()
	matrix.Add(version.Compatibility{
		Component:  "api",
		MinVersion: version.MustParse("2.0.0"),
	})

	available := []version.Version{
		version.MustParse("1.0.0"),
		version.MustParse("2.0.0"),
		version.MustParse("2.5.0"),
		version.MustParse("3.0.0"),
	}

	best, err := matrix.Negotiate("api", available)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Best compatible version:", best.String())
}

Output:

Best compatible version: v3.0.0

type Version 

type Version struct {
	Major      int
	Minor      int
	Patch      int
	Prerelease string
	Build      string
}

Version represents a semantic version (major.minor.patch-prerelease+build).

func MustParse 

func MustParse(s string) Version

MustParse parses a version string and panics on error.

Example 
package main

import (
	"fmt"

	"github.com/jonwraymond/toolfoundation/version"
)

func main() {
	v := version.MustParse("1.0.0")
	fmt.Println(v.String())
}

Output:

v1.0.0

func Parse 

func Parse(s string) (Version, error)

Parse parses a semantic version string.

Example 
package main

import (
	"fmt"
	"log"

	"github.com/jonwraymond/toolfoundation/version"
)

func main() {
	v, err := version.Parse("1.2.3")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Major: %d, Minor: %d, Patch: %d\n", v.Major, v.Minor, v.Patch)

	// Also accepts 'v' prefix
	v2, _ := version.Parse("v2.0.0-beta.1")
	fmt.Printf("Version: %s, Prerelease: %s\n", v2.String(), v2.Prerelease)
}

Output:

Major: 1, Minor: 2, Patch: 3
Version: v2.0.0-beta.1, Prerelease: beta.1

func (Version) Compare 

func (v Version) Compare(other Version) int

Compare returns -1, 0, or 1 if v < other, v == other, or v > other.

Example 
package main

import (
	"fmt"

	"github.com/jonwraymond/toolfoundation/version"
)

func main() {
	v1 := version.MustParse("1.0.0")
	v2 := version.MustParse("2.0.0")
	v3 := version.MustParse("1.0.0")

	fmt.Println("1.0.0 vs 2.0.0:", v1.Compare(v2))
	fmt.Println("2.0.0 vs 1.0.0:", v2.Compare(v1))
	fmt.Println("1.0.0 vs 1.0.0:", v1.Compare(v3))
}

Output:

1.0.0 vs 2.0.0: -1
2.0.0 vs 1.0.0: 1
1.0.0 vs 1.0.0: 0

func (Version) Compatible 

func (v Version) Compatible(other Version) bool

Compatible returns true if v is compatible with other (same major, v >= other).

Example 
package main

import (
	"fmt"

	"github.com/jonwraymond/toolfoundation/version"
)

func main() {
	v1 := version.MustParse("1.5.0")
	v2 := version.MustParse("1.0.0")
	v3 := version.MustParse("2.0.0")

	// Same major version, v1 >= v2
	fmt.Println("1.5.0 compatible with 1.0.0:", v1.Compatible(v2))

	// Different major versions are incompatible
	fmt.Println("1.5.0 compatible with 2.0.0:", v1.Compatible(v3))
}

Output:

1.5.0 compatible with 1.0.0: true
1.5.0 compatible with 2.0.0: false

func (Version) Equal 

func (v Version) Equal(other Version) bool

Equal returns true if v == other (ignoring build metadata).

func (Version) GreaterThan 

func (v Version) GreaterThan(other Version) bool

GreaterThan returns true if v > other.

func (Version) LessThan 

func (v Version) LessThan(other Version) bool

LessThan returns true if v < other.

Example 
package main

import (
	"fmt"

	"github.com/jonwraymond/toolfoundation/version"
)

func main() {
	v1 := version.MustParse("1.0.0")
	v2 := version.MustParse("2.0.0")

	if v1.LessThan(v2) {
		fmt.Println("Upgrade available!")
	}
}

Output:

Upgrade available!

func (Version) String 

func (v Version) String() string

String returns the version as a string (with v prefix).

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.