module

package
v0.7.1 Latest Latest
Warning

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

Go to latest
Published: Feb 12, 2024 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package module defines the module.Version type along with support code.

The module.Version type is a simple Path, Version pair:

type Version struct {
	Path string
	Version string
}

There are no restrictions imposed directly by use of this structure, but additional checking functions, most notably Check, verify that a particular path, version pair is valid.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Check

func Check(path, version string) error

Check checks that a given module path, version pair is valid. In addition to the path being a valid module path and the version being a valid semantic version, the two must correspond. For example, the path "foo.com/bar@v2" only corresponds to semantic versions beginning with "v2.".

func CheckFilePath

func CheckFilePath(path string) error

CheckFilePath checks that a slash-separated file path is valid. The definition of a valid file path is the same as the definition of a valid import path except that the set of allowed characters is larger: all Unicode letters, ASCII digits, the ASCII space character (U+0020), and the ASCII punctuation characters “!#$%&()+,-.=@[]^_{}~”. (The excluded punctuation characters, " * < > ? ` ' | / \ and :, have special meanings in certain shells or operating systems.)

CheckFilePath may be less restrictive in the future, but see the top-level package documentation for additional information about subtleties of Unicode.

func CheckImportPath

func CheckImportPath(path0 string) error

CheckImportPath checks that an import path is valid.

A valid import path consists of one or more valid path elements separated by slashes (U+002F), optionally followed by an @vN (major version) qualifier. The path part must not begin with nor end in a slash.

A valid path element is a non-empty string made up of lower case ASCII letters, ASCII digits, and limited ASCII punctuation: - . and _ Punctuation characters may not be adjacent and must be between non-punctuation characters.

The element prefix up to the first dot must not be a reserved file name on Windows, regardless of case (CON, com1, NuL, and so on).

func CheckPath

func CheckPath(mpath string) (err error)

CheckPath checks that a module path is valid. A valid module path is a valid import path, as checked by CheckImportPath, with three additional constraints.

First, the leading path element (up to the first slash, if any), by convention a domain name, must contain only lower-case ASCII letters, ASCII digits, dots (U+002E), and dashes (U+002D); it must contain at least one dot and cannot start with a dash.

Second, there must be a final major version of the form @vN where N looks numeric (ASCII digits) and must not begin with a leading zero.

Third, no path element may begin with a dot.

TODO we probably need function to check module paths that may not contain a major version.

func CheckPathMajor

func CheckPathMajor(v, pathMajor string) error

CheckPathMajor returns a non-nil error if the semantic version v does not match the path major version pathMajor.

func CheckPathWithoutVersion

func CheckPathWithoutVersion(basePath string) (err error)

CheckPathWithoutVersion is like CheckPath except that it expects a module path without a major version.

func MatchPathMajor

func MatchPathMajor(v, pathMajor string) bool

MatchPathMajor reports whether the semantic version v matches the path major version pathMajor.

MatchPathMajor returns true if and only if CheckPathMajor returns nil.

func Sort

func Sort(list []Version)

Sort sorts the list by Path, breaking ties by comparing Version fields. The Version fields are interpreted as semantic versions (using semver.Compare) optionally followed by a tie-breaking suffix introduced by a slash character, like in "v0.0.1/module.cue".

func SplitPathVersion

func SplitPathVersion(path string) (prefix, version string, ok bool)

SplitPathVersion returns a prefix and version suffix such that prefix+"@"+version == path. SplitPathVersion returns with ok=false when presented with a path with an invalid version suffix.

For example, SplitPathVersion("foo.com/bar@v0.1") returns ("foo.com/bar", "v0.1", true).

func VersionError

func VersionError(v Version, err error) error

VersionError returns a ModuleError derived from a Version and error, or err itself if it is already such an error.

Types

type InvalidPathError

type InvalidPathError struct {
	Kind string // "module", "import", or "file"
	Path string
	Err  error
}

An InvalidPathError indicates a module, import, or file path doesn't satisfy all naming constraints. See CheckPath, CheckImportPath, and CheckFilePath for specific restrictions.

func (*InvalidPathError) Error

func (e *InvalidPathError) Error() string

func (*InvalidPathError) Unwrap

func (e *InvalidPathError) Unwrap() error

type InvalidVersionError

type InvalidVersionError struct {
	Version string
	Err     error
}

An InvalidVersionError indicates an error specific to a version, with the module path unknown or specified externally.

A ModuleError may wrap an InvalidVersionError, but an InvalidVersionError must not wrap a ModuleError.

func (*InvalidVersionError) Error

func (e *InvalidVersionError) Error() string

func (*InvalidVersionError) Unwrap

func (e *InvalidVersionError) Unwrap() error

type ModuleError

type ModuleError struct {
	Path    string
	Version string
	Err     error
}

A ModuleError indicates an error specific to a module.

func (*ModuleError) Error

func (e *ModuleError) Error() string

func (*ModuleError) Unwrap

func (e *ModuleError) Unwrap() error

type Version

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

A Version (for clients, a module.Version) is defined by a module path and version pair. These are stored in their plain (unescaped) form. This type is comparable.

func MustNewVersion

func MustNewVersion(path string, vers string) Version

func MustParseVersion

func MustParseVersion(s string) Version

func NewVersion

func NewVersion(path string, vers string) (Version, error)

NewVersion forms a Version from the given path and version. The version must be canonical, empty or "none". If the path doesn't have a major version suffix, one will be added if the version isn't empty; if the version is empty, it's an error.

func ParseVersion

func ParseVersion(s string) (Version, error)

ParseVersion parses a $module@$version string into a Version. The version must be canonical (i.e. it can't be just a major version).

func (Version) BasePath

func (m Version) BasePath() string

func (Version) Equal

func (m Version) Equal(m1 Version) bool

func (Version) Path

func (m Version) Path() string

Path returns the module path part of the Version, which always includes the major version suffix unless a module path, like "github.com/foo/bar@v0". Note that in general the path should include the major version suffix even though it's implied from the version. The Canonical method can be used to add the major version suffix if not present. The BasePath method can be used to obtain the path without the suffix.

func (Version) String

func (m Version) String() string

String returns the string form of the Version: (Path@Version, or just Path if Version is empty).

func (Version) Version

func (m Version) Version() string

type Versions

type Versions struct{}

Versions implements mvs.Versions[Version].

func (Versions) Max

func (Versions) Max(v1, v2 string) string

Max implements mvs.Reqs.Max.

It is consistent with semver.Compare except that as a special case, the version "" is considered higher than all other versions. The main module (also known as the target) has no version and must be chosen over other versions of the same module in the module dependency graph.

See [mvs.Reqs] for more detail.

func (Versions) New

func (Versions) New(p, v string) (Version, error)

New implements mvs.Versions[Version].New.

func (Versions) Path

func (Versions) Path(v Version) string

New implements mvs.Versions[Version].Path.

func (Versions) Version

func (Versions) Version(v Version) string

New implements mvs.Versions[Version].Version.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL