README
¶
Documentation
¶
Overview ¶
Package semver handles the parsing and formatting of Semantic Version strings.
Usage Outline ¶
Create a new semantic version by providing major, minor, and patch versions:
v := semver.New(1, 0, 0)
The resulting version has no release or build metadata.
To extend a version with release or build metadata, use:
v2 := v.WithRelease("rc1").WithBuild("unstable")
To format the version as a string in standard notation, use:
v2.String()
To parse an existing semantic version string:
v, err := semver.Parse("1.0.0-rc1.2+unstable")
If you have a partial version string, with some of the parts not specified or a "v" prefix, use Clean to normalize it:
v, err := semver.Parse(semver.Clean("v1.2-alpha.9"))
Comparison ¶
A V is comparable, and can be used as a map key; however, the rules of semantic version comparison mean that equivalent semantic versions may not be structurally equal. In particular, build metadata are not considered in the comparison of order or equivalence of versions. Use V.Equiv to check whether versions are semantically equivalent.
If using V values as map keys, consider using V.Key.
Example ¶
package main
import (
"fmt"
"log"
"github.com/creachadair/semver"
)
func main() {
v, err := semver.Parse("1.5.3-rc1.4+modified")
if err != nil {
log.Fatal(err)
}
fmt.Println("version:", v)
fmt.Println("core:", v.Core())
fmt.Println("release:", v.Release())
fmt.Println("build:", v.Build())
fmt.Println("clean:", v.WithBuild(""))
w := semver.New(1, 5, 3).WithRelease("rc1.4")
fmt.Println("equiv:", v, w, v.Equiv(w))
}
Output: version: 1.5.3-rc1.4+modified core: 1.5.3 release: rc1.4 build: modified clean: 1.5.3-rc1.4 equiv: 1.5.3-rc1.4+modified 1.5.3-rc1.4 true
Index ¶
- func Clean(s string) string
- func Compare(v1, v2 V) int
- func CompareStrings(s1, s2 string) int
- func IsValid(s string) bool
- type V
- func (v V) Add(dmajor, dminor, dpatch int) V
- func (v V) After(w V) bool
- func (v V) Before(w V) bool
- func (v V) Build() string
- func (v V) Core() V
- func (v V) Equiv(w V) bool
- func (v V) Key() V
- func (v V) Major() int
- func (v V) Minor() int
- func (v V) Patch() int
- func (v V) Release() string
- func (v V) String() string
- func (v V) WithBuild(meta string) V
- func (v V) WithCore(major, minor, patch int) V
- func (v V) WithRelease(id string) V
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Clean ¶ added in v0.0.3
Clean returns a lexically normalized form of a semver-like string. The following changes are made, if possible:
- Leading and trailing whitespace is removed.
- A leading "v" is removed, if present.
- Omitted minor or patch versions are set to "0".
- Empty release and build labels are removed.
If a major version is not present, Clean returns s entirely unmodified. Otherwise, except as described above, the input is not modified. In particular, if s contains invalid characters or non-numeric version numbers, the result may (still) not be a valid version string.
Example ¶
package main
import (
"fmt"
"github.com/creachadair/semver"
)
func main() {
const dirty = " v1.2-rc3..1\t"
fmt.Printf("dirty: %q\n", dirty)
fmt.Println("clean:", semver.Clean(dirty))
}
Output: dirty: " v1.2-rc3..1\t" clean: 1.2.0-rc3.1
func Compare ¶
Compare compares v1 and v2 in standard semantic version order. It returns -1 if v1 < v2, 0 if v1 == v2, and +1 if v1 > v2.
Semantic versions are compared in lexicographic order by major, minor, patch, and pre-release labels. The core major, minor, and patch labels are compared numerically, with smaller values ordered earlier.
Pre-release labels are split into non-empty words separated by period (".") and compared lexicographically. Words comprising only digits are compared numerically; otherwise they are compared lexicographically as strings. When the two lists are of unequal length and the shorter list is equal to a prefix of the longer one, the longer list is ordered earlier.
Build metadata are ignored for comparison, so if v1 and v2 are equal apart from their build metadata, Compare(v1, v2) reports 0.
func CompareStrings ¶ added in v0.0.4
CompareStrings compares s1 and s2 in standard semantic version order. The strings are cleaned (see Clean) before comparison. It returns -1 if s1 < s2, 0 if s1 == s2, and +1 if s1 > s2. If either string is not a valid semver after cleaning, the two strings are compared in ordinary lexicographic order.
Types ¶
type V ¶
type V struct {
// contains filtered or unexported fields
}
V represents a parsed semantic version label. A zero value is ready for use, and represents the semantic version "0.0.0".
func MustParse ¶
MustParse returns the V represented by s, or panics. This is intended for use in program initialization; use Parse to check for errors.
func New ¶
New constructs a V with the specified major, minor, and patch versions. The release and build metadata of the resulting value are empty. New will panic if any of these values is negative.
func Parse ¶
Parse returns the V represented by s.
Example ¶
package main
import (
"fmt"
"log"
"github.com/creachadair/semver"
)
func main() {
v, err := semver.Parse(semver.Clean(" v1.2-alpha..9.\n"))
if err != nil {
log.Fatal(err)
}
fmt.Println(v)
}
Output: 1.2.0-alpha.9
func (V) Add ¶ added in v0.0.6
Add returns a copy of v with the specified offsets added to core versions. Offsets that would cause a version to become negative set it to 0 instead.
Example ¶
package main
import (
"fmt"
"github.com/creachadair/semver"
)
func main() {
v := semver.New(1, 5, 3)
w := v.Add(0, -10, 2)
fmt.Println("v:", v)
fmt.Println("w:", w)
}
Output: v: 1.5.3 w: 1.0.5
func (V) Build ¶
Build reports the build metadata string, if present. The resulting string does not include the "+" prefix.
func (V) Core ¶
Core returns a copy of v with its release and build metadata cleared, corresponding to the "core" version ID (major.minor.patch).
func (V) Equiv ¶
Equiv reports whether v and w are equivalent versions. Note that this is distinct from equality, because semantic version comparison ignores build metadata.
func (V) Key ¶ added in v0.1.3
Key returns a copy of v with empty build metadata, suitable for use as a map key or for equality comparison. This is equivalent to v.WithBuild("").
func (V) Release ¶ added in v0.1.0
Release reports the release string, if present. The resulting string does not include the "-" prefix.
func (V) WithBuild ¶
WithBuild returns a copy of v with its build metadata set. If meta == "", the resulting version has no build metadata.
func (V) WithCore ¶ added in v0.0.6
WithCore returns a copy of v with its core version (major.minor.patch) set. For any argument < 0, the corresponding version is copied unmodified from v.
Example ¶
package main
import (
"fmt"
"github.com/creachadair/semver"
)
func main() {
v := semver.MustParse("1.1.3+unstable")
w := v.WithCore(2, 0, -1)
fmt.Println("v:", v)
fmt.Println("w:", w)
}
Output: v: 1.1.3+unstable w: 2.0.3+unstable
func (V) WithRelease ¶ added in v0.1.0
WithRelease returns a copy of v with its release ID set. If id == "", the resulting version has no release ID.
Source Files