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 ¶
- func Check(path, version string) error
- func CheckFilePath(path string) error
- func CheckImportPath(path0 string) error
- func CheckPath(mpath string) (err error)
- func CheckPathMajor(v, pathMajor string) error
- func CheckPathWithoutVersion(basePath string) (err error)
- func MatchPathMajor(v, pathMajor string) bool
- func Sort(list []Version)
- func SplitPathVersion(path string) (prefix, version string, ok bool)
- func VersionError(v Version, err error) error
- type InvalidPathError
- type InvalidVersionError
- type ModuleError
- type Version
- type Versions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Check ¶
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 ¶
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 ¶
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 ¶
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 ¶
CheckPathMajor returns a non-nil error if the semantic version v does not match the path major version pathMajor.
func CheckPathWithoutVersion ¶
CheckPathWithoutVersion is like CheckPath except that it expects a module path without a major version.
func MatchPathMajor ¶
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 ¶
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 ¶
VersionError returns a ModuleError derived from a Version and error, or err itself if it is already such an error.
Types ¶
type InvalidPathError ¶
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 ¶
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 ¶
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 MustParseVersion ¶
func NewVersion ¶
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 ¶
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) Path ¶
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.
type Versions ¶
type Versions struct{}
Versions implements mvs.Versions[Version].
func (Versions) Max ¶
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.
Source Files