Documentation
¶
Overview ¶
Package versions is a library for wrangling version numbers in Go.
There are many libraries offering some or all of this functionality. This package aims to distinguish itself by offering a more convenient and ergonomic API than seen in some other libraries. Code that is resolving versions and version constraints tends to be hairy and complex already, so an expressive API for talking about these concepts will hopefully help to make that code more readable.
The version model is based on Semantic Versioning as defined at https://semver.org/ . Semantic Versioning does not include any specification for constraints, so the constraint model is based on that used by rubygems, allowing for upper and lower bounds as well as individual version exclusions.
Index ¶
- type List
- func (l List) Filter(set Set) List
- func (l List) IsSorted() bool
- func (l List) Len() int
- func (l List) Less(i, j int) bool
- func (l List) Newest() Version
- func (l List) NewestInSet(set Set) Version
- func (l List) NewestList() List
- func (l List) Set() Set
- func (l List) Sort()
- func (l List) Swap(i, j int)
- type Set
- func AtLeast(v Version) Set
- func AtMost(v Version) Set
- func Intersection(sets ...Set) Set
- func MeetingConstraints(spec constraints.Spec) Set
- func MeetingConstraintsExact(spec constraints.Spec) Set
- func MeetingConstraintsString(spec string) (Set, error)
- func MeetingConstraintsStringRuby(spec string) (Set, error)
- func MustMakeSet(set Set, err error) Set
- func NewerThan(v Version) Set
- func OlderThan(v Version) Set
- func Only(v Version) Set
- func Selection(vs ...Version) Set
- func Union(sets ...Set) Set
- func (s Set) AllRequested() Set
- func (s Set) Exactly(v Version) bool
- func (s Set) Has(v Version) bool
- func (s Set) Intersection(others ...Set) Set
- func (s Set) IsFinite() bool
- func (s Set) List() List
- func (s Set) Requests(v Version) bool
- func (s Set) Subtract(other Set) Set
- func (s Set) Union(others ...Set) Set
- func (s *Set) UnmarshalText(text []byte) error
- func (s Set) WithoutUnrequestedPrereleases() Set
- type Version
- func (v Version) Comparable() Version
- func (v Version) GoString() string
- func (v Version) GreaterThan(other Version) bool
- func (v Version) LessThan(other Version) bool
- func (v Version) MarshalText() (text []byte, err error)
- func (v Version) Same(other Version) bool
- func (v Version) String() string
- func (v *Version) UnmarshalText(text []byte) error
- type VersionExtra
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type List ¶
type List []Version
List is a slice of Version that implements sort.Interface, and also includes some other helper functions.
func (List) Filter ¶
Filter removes from the receiver any elements that are not in the given set, moving retained elements to lower indices to close any gaps and modifying the underlying array in-place. The return value is a slice describing the new bounds within the existing backing array. The relative ordering of the retained elements is preserved.
The result must always be either the same length or shorter than the initial value, so no allocation is required.
As a special case, if the result would be a slice of length zero then a nil slice is returned instead, leaving the backing array untouched.
func (List) IsSorted ¶
IsSorted returns true if the list is already in ascending order by version priority.
func (List) Newest ¶
Newest returns the newest version in the list, or Unspecified if the list is empty.
Since build metadata does not participate in precedence, it is possible that a given list may have multiple equally-new versions; in that case Newest will return an arbitrary version from that subset.
func (List) NewestInSet ¶
NewestInSet is like Filter followed by Newest, except that it does not modify the underlying array. This is convenient for the common case of selecting the newest version from a set derived from a user-supplied constraint.
Similar to Newest, the result is Unspecified if the list is empty or if none of the items are in the given set. Also similar to newest, if there are multiple newest versions (possibly differentiated only by metadata) then one is arbitrarily chosen.
func (List) NewestList ¶
NewestList returns a List containing all of the list items that have the highest precedence.
For an already-sorted list, the returned slice is a sub-slice of the receiver, sharing the same backing array. For an unsorted list, a new array is allocated for the result. For an empty list, the result is always nil.
Relative ordering of elements in the receiver is preserved in the output.
func (List) Set ¶
Set returns a finite Set containing the versions in the receiver.
Although it is possible to recover a list from the return value using its List method, the result may be in a different order and will have any duplicate elements from the receiving list consolidated.
type Set ¶
type Set struct {
// contains filtered or unexported fields
}
Set is a set of versions, usually created by parsing a constraint string.
var All Set
All is an infinite set containing all possible versions.
var InitialDevelopment Set = OlderThan(MustParseVersion("1.0.0"))
var None Set
None is a finite set containing no versions.
var Prerelease Set
Prerelease is a set containing all versions that have a prerelease marker. This is the complement of Released, or in other words it is All.Subtract(Released).
var Released Set
Released is a set containing all versions that have an empty prerelease string.
func AtLeast ¶
AtLeast returns a set containing all versions greater than or equal to the given version.
func AtMost ¶
AtMost returns a set containing all versions less than or equal to the given version, non-inclusive.
func Intersection ¶
Intersection creates a new set that contains the versions that all of the given sets have in common.
The result is finite if any of the given sets are finite.
func MeetingConstraints ¶
func MeetingConstraints(spec constraints.Spec) Set
MeetingConstraints returns a version set that contains all of the versions that meet the given constraints, specified using the Spec type from the constraints package.
The resulting Set has all pre-release versions excluded, except any that are explicitly mentioned as exact selections. For example, the constraint "2.0.0-beta1 || >2" contains 2.0.0-beta1 but not 2.0.0-beta2 or 3.0.0-beta1. This additional constraint on pre-releases can be avoided by calling MeetingConstraintsExact instead, at which point the caller can apply other logic to deal with prereleases.
This function expects an internally-consistent Spec like what would be generated by that package's constraint parsers. Behavior is undefined -- including the possibility of panics -- if specs are hand-created and the expected invariants aren't met.
func MeetingConstraintsExact ¶
func MeetingConstraintsExact(spec constraints.Spec) Set
MeetingConstraintsExact is like MeetingConstraints except that it doesn't apply the extra rules to exclude pre-release versions that are not explicitly requested.
This means that given a constraint ">=1.0.0 <2.0.0" a hypothetical version 2.0.0-beta1 _is_ in the returned set, because prerelease versions have lower precedence than their corresponding release.
A caller can use this to implement its own specialized handling of pre-release versions by applying additional set operations to the result, such as intersecting it with the predefined set versions.Released to remove prerelease versions altogether.
func MeetingConstraintsString ¶
MeetingConstraintsString attempts to parse the given spec as a constraints string in our canonical format, which is most similar to the syntax used by npm, Go's "dep" tool, Rust's "cargo", etc.
This is a covenience wrapper around calling constraints.Parse and then passing the result to MeetingConstraints. Call into the constraints package yourself for access to the constraint tree.
If unsuccessful, the error from the underlying parser is returned verbatim. Parser errors are suitable for showing to an end-user in situations where the given spec came from user input.
func MeetingConstraintsStringRuby ¶
MeetingConstraintsStringRuby attempts to parse the given spec as a "Ruby-style" version constraint string, and returns the set of versions that match the constraint if successful.
If unsuccessful, the error from the underlying parser is returned verbatim. Parser errors are suitable for showing to an end-user in situations where the given spec came from user input.
"Ruby-style" here is not a promise of exact compatibility with rubygems or any other Ruby tools. Rather, it refers to this parser using a syntax that is intended to feel familiar to those who are familiar with rubygems syntax.
Constraints are parsed in "multi" mode, allowing multiple comma-separated constraints that are combined with the Intersection operator. For more control over the parsing process, use the constraints package API directly and then call MeetingConstraints.
func MustMakeSet ¶
MustMakeSet can be used to wrap any function that returns a set and an error to make it panic if an error occurs and return the set otherwise.
This is intended for tests and other situations where input is from known-good constants.
func NewerThan ¶
NewerThan returns a set containing all versions greater than the given version, non-inclusive.
func OlderThan ¶
OlderThan returns a set containing all versions lower than the given version, non-inclusive.
func Only ¶
Only returns a version set containing only the given version.
This function is guaranteed to produce a finite set.
func Selection ¶
Selection returns a version set containing only the versions given as arguments.
This function is guaranteed to produce a finite set.
func Union ¶
Union creates a new set that contains all of the given versions.
The result is finite only if the receiver and all of the other given sets are finite.
func (Set) AllRequested ¶
AllRequested returns a subset of the receiver containing only the requested versions, as defined in the documentation for the method Requests.
This can be used in conjunction with the predefined set "Released" to include pre-release versions only by explicit request, which is supported via the helper method WithoutUnrequestedPrereleases.
The result of AllRequested is always a finite set.
func (Set) Exactly ¶
Exactly returns true if and only if the receiving set is finite and contains only a single version that is the same as the version given.
func (Set) Intersection ¶
Intersection returns a new set that contains all of the versions that the receiver and the given sets have in common.
The result is a finite set if the receiver or any of the given sets are finite.
func (Set) IsFinite ¶
IsFinite returns true if the set represents a finite number of versions, and can thus support List without panicking.
func (Set) List ¶
List returns the specific versions represented by a finite list, in an undefined order. If desired, the caller can sort the resulting list using its Sort method.
If the set is not finite, this method will panic. Use IsFinite to check unless a finite set was guaranteed by whatever operation(s) constructed the set.
func (Set) Requests ¶
Requests returns true if the given version is specifically requested by the receiving set.
Requesting is a stronger form of set membership that represents an explicit request for a particular version, as opposed to the version just happening to match some criteria.
The functions Only and Selection mark their arguments as requested in their returned sets. Exact version constraints given in constraint strings also mark their versions as requested.
The concept of requesting is intended to help deal with pre-release versions in a safe and convenient way. When given generic version constraints like ">= 1.0.0" the user generally does not intend to match a pre-release version like "2.0.0-beta1", but it is important to stil be able to use that version if explicitly requested using the constraint string "2.0.0-beta1".
func (Set) Subtract ¶
Subtract returns a new set that has all of the versions from the receiver except for any versions in the other given set.
If the receiver is finite then the returned set is also finite.
func (Set) Union ¶
Union returns a new set that contains all of the versions from the receiver and all of the versions from each of the other given sets.
The result is finite only if the receiver and all of the other given sets are finite.
func (*Set) UnmarshalText ¶
UnmarshalText is an implementation of encoding.TextUnmarshaler, allowing sets to be automatically unmarshalled from strings in text-based serialization formats, including encoding/json.
The format expected is what is accepted by MeetingConstraintsString. Any parser errors are passed on verbatim to the caller.
func (Set) WithoutUnrequestedPrereleases ¶
WithoutUnrequestedPrereleases returns a new set that includes all released versions from the receiving set, plus any explicitly-requested pre-releases, but does not include any unrequested pre-releases.
"Requested" here is as defined in the documentation for the "Requests" method.
This method is equivalent to the following set operations:
versions.Union(s.AllRequested(), s.Intersection(versions.Released))
type Version ¶
type Version struct {
Major uint64
Minor uint64
Patch uint64
Prerelease VersionExtra
Metadata VersionExtra
}
Version represents a single version.
var Unspecified Version
Unspecified is the zero value of Version and represents the absense of a version number.
Note that this is indistinguishable from the explicit version that results from parsing the string "0.0.0".
func MustParseVersion ¶
MustParseVersion is the same as ParseVersion except that it will panic instead of returning an error.
func ParseVersion ¶
ParseVersion attempts to parse the given string as a semantic version specification, and returns the result if successful.
If the given string is not parseable then an error is returned that is suitable for display directly to a hypothetical end-user that provided this version string, as long as they can read English.
func (Version) Comparable ¶
Comparable returns a version that is the same as the receiver but its metadata is the empty string. For Comparable versions, the standard equality operator == is equivalent to method Same.
func (Version) GreaterThan ¶
GreaterThan returns true if the receiver has a higher precedence than the other given version, as defined by the semantic versioning specification.
func (Version) LessThan ¶
LessThan returns true if the receiver has a lower precedence than the other given version, as defined by the semantic versioning specification.
func (Version) MarshalText ¶
MarshalText is an implementation of encoding.TextMarshaler, allowing versions to be automatically marshalled for text-based serialization formats, including encoding/json.
The format used is that returned by String, which can be parsed using ParseVersion.
func (Version) Same ¶
Same returns true if the receiver has the same precedence as the other given version. In other words, it has the same major, minor and patch version number and an identical prerelease portion. The Metadata, if any, is not considered.
func (Version) String ¶
String is an implementation of fmt.Stringer that returns the receiver in the canonical "semver" format.
func (*Version) UnmarshalText ¶
UnmarshalText is an implementation of encoding.TextUnmarshaler, allowing versions to be automatically unmarshalled from strings in text-based serialization formats, including encoding/json.
The format expected is what is accepted by ParseVersion. Any parser errors are passed on verbatim to the caller.
type VersionExtra ¶
type VersionExtra string
VersionExtra represents a string containing dot-delimited tokens, as used in the pre-release and build metadata portions of a Semantic Versioning version expression.
func (VersionExtra) LessThan ¶
func (e VersionExtra) LessThan(other VersionExtra) bool
LessThan returns true if the receiever has lower precedence than the other given VersionExtra string, per the rules defined in the semver spec for pre-release versions.
Build metadata has no defined precedence rules, so it is not meaningful to call this method on a VersionExtra representing build metadata.
func (VersionExtra) Parts ¶
func (e VersionExtra) Parts() []string
Parts tokenizes the string into its separate parts by splitting on dots.
The result is undefined if the receiver is not valid per the semver spec,
func (VersionExtra) Raw ¶
func (e VersionExtra) Raw() string
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package constraints contains a high-level representation of version constraints that retains enough information for direct analysis and serialization as a string.
|
Package constraints contains a high-level representation of version constraints that retains enough information for direct analysis and serialization as a string. |