1/*
2Package semver provides the ability to work with Semantic Versions (http://semver.org) in Go.
3
4Specifically it provides the ability to:
5
6    * Parse semantic versions
7    * Sort semantic versions
8    * Check if a semantic version fits within a set of constraints
9    * Optionally work with a `v` prefix
10
11Parsing Semantic Versions
12
13To parse a semantic version use the `NewVersion` function. For example,
14
15    v, err := semver.NewVersion("1.2.3-beta.1+build345")
16
17If there is an error the version wasn't parseable. The version object has methods
18to get the parts of the version, compare it to other versions, convert the
19version back into a string, and get the original string. For more details
20please see the documentation at https://godoc.org/github.com/Masterminds/semver.
21
22Sorting Semantic Versions
23
24A set of versions can be sorted using the `sort` package from the standard library.
25For example,
26
27    raw := []string{"1.2.3", "1.0", "1.3", "2", "0.4.2",}
28    vs := make([]*semver.Version, len(raw))
29	for i, r := range raw {
30		v, err := semver.NewVersion(r)
31		if err != nil {
32			t.Errorf("Error parsing version: %s", err)
33		}
34
35		vs[i] = v
36	}
37
38	sort.Sort(semver.Collection(vs))
39
40Checking Version Constraints
41
42Checking a version against version constraints is one of the most featureful
43parts of the package.
44
45    c, err := semver.NewConstraint(">= 1.2.3")
46    if err != nil {
47        // Handle constraint not being parseable.
48    }
49
50    v, _ := semver.NewVersion("1.3")
51    if err != nil {
52        // Handle version not being parseable.
53    }
54    // Check if the version meets the constraints. The a variable will be true.
55    a := c.Check(v)
56
57Basic Comparisons
58
59There are two elements to the comparisons. First, a comparison string is a list
60of comma separated and comparisons. These are then separated by || separated or
61comparisons. For example, `">= 1.2, < 3.0.0 || >= 4.2.3"` is looking for a
62comparison that's greater than or equal to 1.2 and less than 3.0.0 or is
63greater than or equal to 4.2.3.
64
65The basic comparisons are:
66
67    * `=`: equal (aliased to no operator)
68    * `!=`: not equal
69    * `>`: greater than
70    * `<`: less than
71    * `>=`: greater than or equal to
72    * `<=`: less than or equal to
73
74Hyphen Range Comparisons
75
76There are multiple methods to handle ranges and the first is hyphens ranges.
77These look like:
78
79    * `1.2 - 1.4.5` which is equivalent to `>= 1.2, <= 1.4.5`
80    * `2.3.4 - 4.5` which is equivalent to `>= 2.3.4, <= 4.5`
81
82Wildcards In Comparisons
83
84The `x`, `X`, and `*` characters can be used as a wildcard character. This works
85for all comparison operators. When used on the `=` operator it falls
86back to the pack level comparison (see tilde below). For example,
87
88    * `1.2.x` is equivalent to `>= 1.2.0, < 1.3.0`
89    * `>= 1.2.x` is equivalent to `>= 1.2.0`
90    * `<= 2.x` is equivalent to `<= 3`
91    * `*` is equivalent to `>= 0.0.0`
92
93Tilde Range Comparisons (Patch)
94
95The tilde (`~`) comparison operator is for patch level ranges when a minor
96version is specified and major level changes when the minor number is missing.
97For example,
98
99    * `~1.2.3` is equivalent to `>= 1.2.3, < 1.3.0`
100    * `~1` is equivalent to `>= 1, < 2`
101    * `~2.3` is equivalent to `>= 2.3, < 2.4`
102    * `~1.2.x` is equivalent to `>= 1.2.0, < 1.3.0`
103    * `~1.x` is equivalent to `>= 1, < 2`
104
105Caret Range Comparisons (Major)
106
107The caret (`^`) comparison operator is for major level changes. This is useful
108when comparisons of API versions as a major change is API breaking. For example,
109
110    * `^1.2.3` is equivalent to `>= 1.2.3, < 2.0.0`
111    * `^1.2.x` is equivalent to `>= 1.2.0, < 2.0.0`
112    * `^2.3` is equivalent to `>= 2.3, < 3`
113    * `^2.x` is equivalent to `>= 2.0.0, < 3`
114*/
115package semver
116