module
package
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
Stable versionWhen a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Report a Vulnerability
Open Source Insights
Documentation¶
Overview¶
Package module defines the module.Version type along with support code.
Themodule.Version type is a simple Path, Version pair:
type Version struct {Path stringVersion string}There are no restrictions imposed directly by use of this structure,but additional checking functions, most notablyCheck, verify thata particular path, version pair is valid.
Escaped Paths¶
Module paths appear as substrings of file system paths(in the download cache) and of web server URLs in the proxy protocol.In general we cannot rely on file systems to be case-sensitive,nor can we rely on web servers, since they read from file systems.That is, we cannot rely on the file system to keep rsc.io/QUOTEand rsc.io/quote separate. Windows and macOS don't.Instead, we must never require two different casings of a file path.Because we want the download cache to match the proxy protocol,and because we want the proxy protocol to be possible to servefrom a tree of static files (which might be stored on a case-insensitivefile system), the proxy protocol must never require two different casingsof a URL path either.
One possibility would be to make the escaped form be the lowercasehexadecimal encoding of the actual path bytes. This would avoid everneeding different casings of a file path, but it would be fairly illegibleto most programmers when those paths appeared in the file system(including in file paths in compiler errors and stack traces)in web server logs, and so on. Instead, we want a safe escaped form thatleaves most paths unaltered.
The safe escaped form is to replace every uppercase letterwith an exclamation mark followed by the letter's lowercase equivalent.
For example,
github.com/Azure/azure-sdk-for-go -> github.com/!azure/azure-sdk-for-go.github.com/GoogleCloudPlatform/cloudsql-proxy -> github.com/!google!cloud!platform/cloudsql-proxygithub.com/Sirupsen/logrus -> github.com/!sirupsen/logrus.
Import paths that avoid upper-case letters are left unchanged.Note that because import paths are ASCII-only and avoid variousproblematic punctuation (like : < and >), the escaped form is also ASCII-onlyand avoids the same problematic punctuation.
Import paths have never allowed exclamation marks, so there is noneed to define how to escape a literal !.
Unicode Restrictions¶
Today, paths are disallowed from using Unicode.
Although paths are currently disallowed from using Unicode,we would like at some point to allow Unicode letters as well, to assume thatfile systems and URLs are Unicode-safe (storing UTF-8), and applythe !-for-uppercase convention for escaping them in the file system.But there are at least two subtle considerations.
First, note that not all case-fold equivalent distinct runesform an upper/lower pair.For example, U+004B ('K'), U+006B ('k'), and U+212A ('K' for Kelvin)are three distinct runes that case-fold to each other.When we do add Unicode letters, we must not assume that upper/lowerare the only case-equivalent pairs.Perhaps the Kelvin symbol would be disallowed entirely, for example.Or perhaps it would escape as "!!k", or perhaps as "(212A)".
Second, it would be nice to allow Unicode marks as well as letters,but marks include combining marks, and then we must deal notonly with case folding but also normalization: both U+00E9 ('é')and U+0065 U+0301 ('e' followed by combining acute accent)look the same on the page and are treated by some file systemsas the same path. If we do allow Unicode marks in paths, theremust be some kind of normalization to allow only one canonicalencoding of any character used in an import path.
Index¶
- Constants
- func CanonicalVersion(v string) string
- func Check(path, version string) error
- func CheckFilePath(path string) error
- func CheckImportPath(path string) error
- func CheckPath(path string) (err error)
- func CheckPathMajor(v, pathMajor string) error
- func EscapePath(path string) (escaped string, err error)
- func EscapeVersion(v string) (escaped string, err error)
- func IsPseudoVersion(v string) bool
- func IsZeroPseudoVersion(v string) bool
- func MatchPathMajor(v, pathMajor string) bool
- func MatchPrefixPatterns(globs, target string) bool
- func PathMajorPrefix(pathMajor string) string
- func PseudoVersion(major, older string, t time.Time, rev string) string
- func PseudoVersionBase(v string) (string, error)
- func PseudoVersionRev(v string) (rev string, err error)
- func PseudoVersionTime(v string) (time.Time, error)
- func Sort(list []Version)
- func SplitPathVersion(path string) (prefix, pathMajor string, ok bool)
- func UnescapePath(escaped string) (path string, err error)
- func UnescapeVersion(escaped string) (v string, err error)
- func VersionError(v Version, err error) error
- func ZeroPseudoVersion(major string) string
- type InvalidPathError
- type InvalidVersionError
- type ModuleError
- type Version
Constants¶
const PseudoVersionTimestampFormat = "20060102150405"Variables¶
This section is empty.
Functions¶
funcCanonicalVersion¶
CanonicalVersion returns the canonical form of the version string v.It is the same assemver.Canonical except that it preserves the special build suffix "+incompatible".
funcCheck¶
Check checks that a given module path, version pair is valid.In addition to the path being a valid module pathand the version being a valid semantic version,the two must correspond.For example, the path "yaml/v2" only corresponds tosemantic versions beginning with "v2.".
funcCheckFilePath¶
CheckFilePath checks that a slash-separated file path is valid.The definition of a valid file path is the same as the definitionof 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 thetop-level package documentation for additional information aboutsubtleties of Unicode.
funcCheckImportPath¶
CheckImportPath checks that an import path is valid.
A valid import path consists of one or more valid path elementsseparated by slashes (U+002F). (It must not begin with nor end in a slash.)
A valid path element is a non-empty string made up ofASCII letters, ASCII digits, and limited ASCII punctuation: - . _ and ~.It must not end with a dot (U+002E), nor contain two dots in a row.
The element prefix up to the first dot must not be a reserved file nameon Windows, regardless of case (CON, com1, NuL, and so on). The elementmust not have a suffix of a tilde followed by one or more ASCII digits(to exclude paths elements that look like Windows short-names).
CheckImportPath may be less restrictive in the future, but see thetop-level package documentation for additional information aboutsubtleties of Unicode.
funcCheckPath¶
CheckPath checks that a module path is valid.A valid module path is a valid import path, as checked byCheckImportPath,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, for a final path element of the form /vN, where N looks numeric(ASCII digits and dots) must not begin with a leading zero, must not be /v1,and must not contain any dots. For paths beginning with "gopkg.in/",this second requirement is replaced by a requirement that the pathfollow the gopkg.in server's conventions.Third, no path element may begin with a dot.
funcCheckPathMajor¶added inv0.2.0
CheckPathMajor returns a non-nil error if the semantic version vdoes not match the path major version pathMajor.
funcEscapePath¶
EscapePath returns the escaped form of the given module path.It fails if the module path is invalid.
funcEscapeVersion¶
EscapeVersion returns the escaped form of the given module version.Versions are allowed to be in non-semver form but must be valid file namesand not contain exclamation marks.
funcIsPseudoVersion¶added inv0.5.0
IsPseudoVersion reports whether v is a pseudo-version.
funcIsZeroPseudoVersion¶added inv0.5.0
IsZeroPseudoVersion returns whether v is a pseudo-version with a zero base,timestamp, and revision, as returned byZeroPseudoVersion.
funcMatchPathMajor¶
MatchPathMajor reports whether the semantic version vmatches the path major version pathMajor.
MatchPathMajor returns true if and only ifCheckPathMajor returns nil.
funcMatchPrefixPatterns¶added inv0.4.0
MatchPrefixPatterns reports whether any path prefix of target matches one ofthe glob patterns (as defined bypath.Match) in the comma-separated globslist. This implements the algorithm used when matching a module path to theGOPRIVATE environment variable, as described by 'go help module-private'.
It ignores any empty or malformed patterns in the list.Trailing slashes on patterns are ignored.
funcPathMajorPrefix¶added inv0.2.0
PathMajorPrefix returns the major-version tag prefix implied by pathMajor.An empty PathMajorPrefix allows either v0 or v1.
Note thatMatchPathMajor may accept some versions that do not actually beginwith this prefix: namely, it accepts a 'v0.0.0-' prefix for a '.v1'pathMajor, even though that pathMajor implies 'v1' tagging.
funcPseudoVersion¶added inv0.5.0
PseudoVersion returns a pseudo-version for the given major version ("v1")preexisting older tagged version ("" or "v1.2.3" or "v1.2.3-pre"), revision time,and revision identifier (usually a 12-byte commit hash prefix).
funcPseudoVersionBase¶added inv0.5.0
PseudoVersionBase returns the canonical parent version, if any, upon whichthe pseudo-version v is based.
If v has no parent version (that is, if it is "vX.0.0-[…]"),PseudoVersionBase returns the empty string and a nil error.
funcPseudoVersionRev¶added inv0.5.0
PseudoVersionRev returns the revision identifier of the pseudo-version v.It returns an error if v is not a pseudo-version.
funcPseudoVersionTime¶added inv0.5.0
PseudoVersionTime returns the time stamp of the pseudo-version v.It returns an error if v is not a pseudo-version or if the time stampembedded in the pseudo-version is not a valid time.
funcSort¶
func Sort(list []Version)
Sort sorts the list by Path, breaking ties by comparingVersion fields.The Version fields are interpreted as semantic versions (usingsemver.Compare)optionally followed by a tie-breaking suffix introduced by a slash character,like in "v0.0.1/go.mod".
funcSplitPathVersion¶
SplitPathVersion returns prefix and major version such that prefix+pathMajor == pathand version is either empty or "/vN" for N >= 2.As a special case, gopkg.in paths are recognized directly;they require ".vN" instead of "/vN", and for all N, not just N >= 2.SplitPathVersion returns with ok = false when presented witha path whose last path element does not satisfy the constraintsapplied byCheckPath, such as "example.com/pkg/v1" or "example.com/pkg/v1.2".
funcUnescapePath¶
UnescapePath returns the module path for the given escaped path.It fails if the escaped path is invalid or describes an invalid path.
funcUnescapeVersion¶
UnescapeVersion returns the version string for the given escaped version.It fails if the escaped form is invalid or describes an invalid version.Versions are allowed to be in non-semver form but must be valid file namesand not contain exclamation marks.
funcVersionError¶added inv0.2.0
VersionError returns aModuleError derived from aVersion and error,or err itself if it is already such an error.
funcZeroPseudoVersion¶added inv0.5.0
ZeroPseudoVersion returns a pseudo-version with a zero timestamp andrevision, which may be used as a placeholder.
Types¶
typeInvalidPathError¶added inv0.5.0
An InvalidPathError indicates a module, import, or file path doesn'tsatisfy all naming constraints. SeeCheckPath,CheckImportPath,andCheckFilePath for specific restrictions.
func (*InvalidPathError)Error¶added inv0.5.0
func (e *InvalidPathError) Error()string
func (*InvalidPathError)Unwrap¶added inv0.5.0
func (e *InvalidPathError) Unwrap()error
typeInvalidVersionError¶added inv0.2.0
An InvalidVersionError indicates an error specific to a version, with themodule path unknown or specified externally.
AModuleError may wrap an InvalidVersionError, but an InvalidVersionErrormust not wrap a ModuleError.
func (*InvalidVersionError)Error¶added inv0.2.0
func (e *InvalidVersionError) Error()string
func (*InvalidVersionError)Unwrap¶added inv0.2.0
func (e *InvalidVersionError) Unwrap()error
typeModuleError¶added inv0.2.0
A ModuleError indicates an error specific to a module.
func (*ModuleError)Error¶added inv0.2.0
func (e *ModuleError) Error()string
func (*ModuleError)Unwrap¶added inv0.2.0
func (e *ModuleError) Unwrap()error
typeVersion¶
type Version struct {// Path is a module path, like "golang.org/x/text" or "rsc.io/quote/v2".Pathstring// Version is usually a semantic version in canonical form.// There are three exceptions to this general rule.// First, the top-level target of a build has no specific version// and uses Version = "".// Second, during MVS calculations the version "none" is used// to represent the decision to take no version of a given module.// Third, filesystem paths found in "replace" directives are// represented by a path with an empty version.Versionstring `json:",omitempty"`}A Version (for clients, a module.Version) is defined by a module path and version pair.These are stored in their plain (unescaped) form.
Source Files