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(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(path 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(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.
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(basePath string) (err error)
CheckPathWithoutVersion is like CheckPath except that it expects a module path without a major version.
func EscapePath(path string) (escaped string, err error)
EscapePath returns the escaped form of the given module path (without the major version suffix). It fails if the module path is invalid.
func EscapeVersion(v string) (escaped string, err error)
EscapeVersion returns the escaped form of the given module version. Versions must be in (possibly non-canonical) semver form and must be valid file names and not contain exclamation marks.
func OSDirFS(p string) fs.FS
OSDirFS is like os.DirFS but the returned value implements OSRootFS by returning p.
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(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).
ImportPath holds the various components of an import path.
type ImportPath struct {
// Path holds the base package/directory path, similar
// to that returned by [Version.BasePath].
Path string
// Version holds the version of the import
// or empty if not present. Note: in general this
// will contain a major version only, but there's no
// guarantee of that.
Version string
// Qualifier holds the package qualifier within the path.
// This will be derived from the last component of Path
// if it wasn't explicitly present in the import path.
// This is not guaranteed to be a valid CUE identifier.
Qualifier string
// ExplicitQualifier holds whether the qualifier was explicitly
// present in the import path.
ExplicitQualifier bool
}
func ParseImportPath(p string) ImportPath
ParseImportPath returns the various components of an import path.
func (parts ImportPath) Canonical() ImportPath
Canonical returns the canonical form of the import path. Specifically, it will only include the package qualifier if it's different from the last component of parts.Path.
func (parts ImportPath) String() string
func (parts ImportPath) Unqualified() ImportPath
Unqualified returns the import path without any package qualifier.
An InvalidPathError indicates a module, import, or file path doesn't satisfy all naming constraints. See CheckPath, CheckImportPath, and CheckFilePath for specific restrictions.
type InvalidPathError struct {
Kind string // "module", "import", or "file"
Path string
Err error
}
func (e *InvalidPathError) Error() string
func (e *InvalidPathError) Unwrap() 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.
type InvalidVersionError struct {
Version string
Err error
}
func (e *InvalidVersionError) Error() string
func (e *InvalidVersionError) Unwrap() error
A ModuleError indicates an error specific to a module.
type ModuleError struct {
Path string
Version string
Err error
}
func (e *ModuleError) Error() string
func (e *ModuleError) Unwrap() error
OSRootFS can be implemented by an fs.FS implementation to return its root directory as an OS file path.
type OSRootFS interface {
fs.FS
// OSRoot returns the root directory of the FS
// as an OS file path. If it wasn't possible to do that,
// it returns the empty string.
OSRoot() string
}
SourceLoc represents the location of some CUE source code.
type SourceLoc struct {
// FS is the filesystem containing the source.
FS fs.FS
// Dir is the directory within the above filesystem.
Dir string
}
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.
type Version struct {
// contains filtered or unexported fields
}
func MustNewVersion(path string, version string) Version
func MustParseVersion(s string) Version
func NewVersion(path string, version 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.
As a special case, the path "local" is used to mean all packages held in the gen, pkg and usr directories.
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 (m Version) BasePath() string
BasePath returns the path part of m without its major version suffix.
func (m Version) Equal(m1 Version) bool
Equal reports whether m is equal to m1.
func (m Version) IsCanonical() bool
IsCanonical reports whether m is valid and has a canonical semver version.
func (m Version) IsLocal() bool
func (m Version) IsValid() bool
IsValid reports whether m is non-zero.
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 (m Version) String() string
String returns the string form of the Version: (Path@Version, or just Path if Version is empty).
func (m Version) Version() string
Version returns the version part of m. This is either a canonical semver version or "none" or the empty string.
Versions implements mvs.Versions[Version].
type Versions struct{}
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(p, v string) (Version, error)
New implements mvs.Versions[Version].New.
func (Versions) Path(v Version) string
New implements mvs.Versions[Version].Path.
func (Versions) Version(v Version) string
New implements mvs.Versions[Version].Version.