gover

Documentation

Overview

Package gover implements support for Go toolchain versions like 1.21.0 and 1.21rc1. (For historical reasons, Go does not use semver for its toolchains.) This package provides the same basic analysis that golang.org/x/mod/semver does for semver. It also provides some helpers for extracting versions from go.mod files and for dealing with module.Versions that may use Go versions or semver depending on the module path.

Index

• Variables
• func Compare(x, y string) int
• func FromToolchain(name string) string
• func IsLang(x string) bool
• func IsPrerelease(x string) bool
• func IsToolchain(path string) bool
• func IsValid(x string) bool
• func Lang(x string) string
• func Max(x, y string) string
• func ModCompare(path string, x, y string) int
• func ModIsPrefix(path, vers string) bool
• func ModIsPrerelease(path, vers string) bool
• func ModIsValid(path, vers string) bool
• func ModMajorMinor(path, vers string) string
• func ModSort(list []module.Version)
• func Prev(x string) string
• func ToolchainMax(x, y string) string
• type Switcher
• type TooNewError
  • func (e *TooNewError) Is(err error) bool

Variables

var ErrTooNew = errors.New("module too new")

var Startup struct {
	GOTOOLCHAIN   string // $GOTOOLCHAIN setting
	AutoFile      string // go.mod or go.work file consulted
	AutoGoVersion string // go line found in file
	AutoToolchain string // toolchain line found in file
}

Startup records the information that went into the startup-time version switch. It is initialized by switchGoToolchain.

Functions

func Compare

func Compare(x, y string) int

Compare returns -1, 0, or +1 depending on whether x < y, x == y, or x > y, interpreted as toolchain versions. The versions x and y must not begin with a "go" prefix: just "1.21" not "go1.21". Malformed versions compare less than well-formed versions and equal to each other. The language version "1.21" compares less than the release candidate and eventual releases "1.21rc1" and "1.21.0".

func FromToolchain

func FromToolchain(name string) string

FromToolchain returns the Go version for the named toolchain, derived from the name itself (not by running the toolchain). A toolchain is named "goVERSION". A suffix after the VERSION introduced by a -, space, or tab is removed. Examples:

FromToolchain("go1.2.3") == "1.2.3"
FromToolchain("go1.2.3-bigcorp") == "1.2.3"
FromToolchain("invalid") == ""

func IsLang

func IsLang(x string) bool

IsLang reports whether v denotes the overall Go language version and not a specific release. Starting with the Go 1.21 release, "1.x" denotes the overall language version; the first release is "1.x.0". The distinction is important because the relative ordering is

1.21 < 1.21rc1 < 1.21.0

meaning that Go 1.21rc1 and Go 1.21.0 will both handle go.mod files that say "go 1.21", but Go 1.21rc1 will not handle files that say "go 1.21.0".

func IsPrerelease

func IsPrerelease(x string) bool

IsPrerelease reports whether v denotes a Go prerelease version.

func IsToolchain

func IsToolchain(path string) bool

IsToolchain reports whether the module path corresponds to the virtual, non-downloadable module tracking go or toolchain directives in the go.mod file.

Note that IsToolchain only matches "go" and "toolchain", not the real, downloadable module "golang.org/toolchain" containing toolchain files.

IsToolchain("go") = true
IsToolchain("toolchain") = true
IsToolchain("golang.org/x/tools") = false
IsToolchain("golang.org/toolchain") = false

func IsValid

func IsValid(x string) bool

IsValid reports whether the version x is valid.

func Lang

func Lang(x string) string

Lang returns the Go language version. For example, Lang("1.2.3") == "1.2".

func Max

func Max(x, y string) string

Max returns the maximum of x and y interpreted as toolchain versions, compared using Compare. If x and y compare equal, Max returns x.

func ModCompare

func ModCompare(path string, x, y string) int

ModCompare returns the result of comparing the versions x and y for the module with the given path. The path is necessary because the "go" and "toolchain" modules use a different version syntax and semantics (gover, this package) than most modules (semver).

func ModIsPrefix

func ModIsPrefix(path, vers string) bool

ModIsPrefix reports whether v is a valid version syntax prefix for the module with the given path. The caller is assumed to have checked that ModIsValid(path, vers) is true.

func ModIsPrerelease

func ModIsPrerelease(path, vers string) bool

ModIsPrerelease reports whether v is a prerelease version for the module with the given path. The caller is assumed to have checked that ModIsValid(path, vers) is true.

func ModIsValid

func ModIsValid(path, vers string) bool

ModIsValid reports whether vers is a valid version syntax for the module with the given path.

func ModMajorMinor

func ModMajorMinor(path, vers string) string

ModMajorMinor returns the "major.minor" truncation of the version v, for use as a prefix in "@patch" queries.

func ModSort

func ModSort(list []module.Version)

ModSort is like module.Sort but understands the "go" and "toolchain" modules and their version ordering.

func Prev

func Prev(x string) string

Prev returns the Go major release immediately preceding v, or v itself if v is the first Go major release (1.0) or not a supported Go version.

Examples:

Prev("1.2") = "1.1"
Prev("1.3rc4") = "1.2"

func ToolchainMax

func ToolchainMax(x, y string) string

ToolchainMax returns the maximum of x and y interpreted as toolchain names, compared using Compare(FromToolchain(x), FromToolchain(y)). If x and y compare equal, Max returns x.

Types

type Switcher

type Switcher interface {
	Error(err error)
	Switch(ctx context.Context)
}

A Switcher provides the ability to switch to a new toolchain in response to TooNewErrors. See cmd/go/internal/toolchain.Switcher for documentation.

type TooNewError

type TooNewError struct {
	What      string
	GoVersion string
	Toolchain string // for callers if they want to use it, but not printed
}

A TooNewError explains that a module is too new for this version of Go.

func (*TooNewError) Is

func (e *TooNewError) Is(err error) bool