README.md
1semver for golang [](https://travis-ci.org/blang/semver) [](https://godoc.org/github.com/blang/semver/v4) [](https://coveralls.io/r/blang/semver?branch=master) [](https://goreportcard.com/report/github.com/blang/semver)
2======
3
4semver is a [Semantic Versioning](http://semver.org/) library written in golang. It fully covers spec version `2.0.0`.
5
6Versioning
7----------
8Old v1-v3 versions exist in the root of the repository for compatiblity reasons and will only receive bug fixes.
9
10The current stable version is [*v4*](v4/).
11
12Usage
13-----
14```bash
15$ go get github.com/blang/semver/v4
16```
17Note: Always vendor your dependencies or fix on a specific version tag.
18
19```go
20import github.com/blang/semver/v4
21v1, err := semver.Make("1.0.0-beta")
22v2, err := semver.Make("2.0.0-beta")
23v1.Compare(v2)
24```
25
26Also check the [GoDocs](http://godoc.org/github.com/blang/semver/v4).
27
28Why should I use this lib?
29-----
30
31- Fully spec compatible
32- No reflection
33- No regex
34- Fully tested (Coverage >99%)
35- Readable parsing/validation errors
36- Fast (See [Benchmarks](#benchmarks))
37- Only Stdlib
38- Uses values instead of pointers
39- Many features, see below
40
41
42Features
43-----
44
45- Parsing and validation at all levels
46- Comparator-like comparisons
47- Compare Helper Methods
48- InPlace manipulation
49- Ranges `>=1.0.0 <2.0.0 || >=3.0.0 !3.0.1-beta.1`
50- Wildcards `>=1.x`, `<=2.5.x`
51- Sortable (implements sort.Interface)
52- database/sql compatible (sql.Scanner/Valuer)
53- encoding/json compatible (json.Marshaler/Unmarshaler)
54
55Ranges
56------
57
58A `Range` is a set of conditions which specify which versions satisfy the range.
59
60A condition is composed of an operator and a version. The supported operators are:
61
62- `<1.0.0` Less than `1.0.0`
63- `<=1.0.0` Less than or equal to `1.0.0`
64- `>1.0.0` Greater than `1.0.0`
65- `>=1.0.0` Greater than or equal to `1.0.0`
66- `1.0.0`, `=1.0.0`, `==1.0.0` Equal to `1.0.0`
67- `!1.0.0`, `!=1.0.0` Not equal to `1.0.0`. Excludes version `1.0.0`.
68
69Note that spaces between the operator and the version will be gracefully tolerated.
70
71A `Range` can link multiple `Ranges` separated by space:
72
73Ranges can be linked by logical AND:
74
75 - `>1.0.0 <2.0.0` would match between both ranges, so `1.1.1` and `1.8.7` but not `1.0.0` or `2.0.0`
76 - `>1.0.0 <3.0.0 !2.0.3-beta.2` would match every version between `1.0.0` and `3.0.0` except `2.0.3-beta.2`
77
78Ranges can also be linked by logical OR:
79
80 - `<2.0.0 || >=3.0.0` would match `1.x.x` and `3.x.x` but not `2.x.x`
81
82AND has a higher precedence than OR. It's not possible to use brackets.
83
84Ranges can be combined by both AND and OR
85
86 - `>1.0.0 <2.0.0 || >3.0.0 !4.2.1` would match `1.2.3`, `1.9.9`, `3.1.1`, but not `4.2.1`, `2.1.1`
87
88Range usage:
89
90```
91v, err := semver.Parse("1.2.3")
92expectedRange, err := semver.ParseRange(">1.0.0 <2.0.0 || >=3.0.0")
93if expectedRange(v) {
94 //valid
95}
96
97```
98
99Example
100-----
101
102Have a look at full examples in [examples/main.go](examples/main.go)
103
104```go
105import github.com/blang/semver/v4
106
107v, err := semver.Make("0.0.1-alpha.preview+123.github")
108fmt.Printf("Major: %d\n", v.Major)
109fmt.Printf("Minor: %d\n", v.Minor)
110fmt.Printf("Patch: %d\n", v.Patch)
111fmt.Printf("Pre: %s\n", v.Pre)
112fmt.Printf("Build: %s\n", v.Build)
113
114// Prerelease versions array
115if len(v.Pre) > 0 {
116 fmt.Println("Prerelease versions:")
117 for i, pre := range v.Pre {
118 fmt.Printf("%d: %q\n", i, pre)
119 }
120}
121
122// Build meta data array
123if len(v.Build) > 0 {
124 fmt.Println("Build meta data:")
125 for i, build := range v.Build {
126 fmt.Printf("%d: %q\n", i, build)
127 }
128}
129
130v001, err := semver.Make("0.0.1")
131// Compare using helpers: v.GT(v2), v.LT, v.GTE, v.LTE
132v001.GT(v) == true
133v.LT(v001) == true
134v.GTE(v) == true
135v.LTE(v) == true
136
137// Or use v.Compare(v2) for comparisons (-1, 0, 1):
138v001.Compare(v) == 1
139v.Compare(v001) == -1
140v.Compare(v) == 0
141
142// Manipulate Version in place:
143v.Pre[0], err = semver.NewPRVersion("beta")
144if err != nil {
145 fmt.Printf("Error parsing pre release version: %q", err)
146}
147
148fmt.Println("\nValidate versions:")
149v.Build[0] = "?"
150
151err = v.Validate()
152if err != nil {
153 fmt.Printf("Validation failed: %s\n", err)
154}
155```
156
157
158Benchmarks
159-----
160
161 BenchmarkParseSimple-4 5000000 390 ns/op 48 B/op 1 allocs/op
162 BenchmarkParseComplex-4 1000000 1813 ns/op 256 B/op 7 allocs/op
163 BenchmarkParseAverage-4 1000000 1171 ns/op 163 B/op 4 allocs/op
164 BenchmarkStringSimple-4 20000000 119 ns/op 16 B/op 1 allocs/op
165 BenchmarkStringLarger-4 10000000 206 ns/op 32 B/op 2 allocs/op
166 BenchmarkStringComplex-4 5000000 324 ns/op 80 B/op 3 allocs/op
167 BenchmarkStringAverage-4 5000000 273 ns/op 53 B/op 2 allocs/op
168 BenchmarkValidateSimple-4 200000000 9.33 ns/op 0 B/op 0 allocs/op
169 BenchmarkValidateComplex-4 3000000 469 ns/op 0 B/op 0 allocs/op
170 BenchmarkValidateAverage-4 5000000 256 ns/op 0 B/op 0 allocs/op
171 BenchmarkCompareSimple-4 100000000 11.8 ns/op 0 B/op 0 allocs/op
172 BenchmarkCompareComplex-4 50000000 30.8 ns/op 0 B/op 0 allocs/op
173 BenchmarkCompareAverage-4 30000000 41.5 ns/op 0 B/op 0 allocs/op
174 BenchmarkSort-4 3000000 419 ns/op 256 B/op 2 allocs/op
175 BenchmarkRangeParseSimple-4 2000000 850 ns/op 192 B/op 5 allocs/op
176 BenchmarkRangeParseAverage-4 1000000 1677 ns/op 400 B/op 10 allocs/op
177 BenchmarkRangeParseComplex-4 300000 5214 ns/op 1440 B/op 30 allocs/op
178 BenchmarkRangeMatchSimple-4 50000000 25.6 ns/op 0 B/op 0 allocs/op
179 BenchmarkRangeMatchAverage-4 30000000 56.4 ns/op 0 B/op 0 allocs/op
180 BenchmarkRangeMatchComplex-4 10000000 153 ns/op 0 B/op 0 allocs/op
181
182See benchmark cases at [semver_test.go](semver_test.go)
183
184
185Motivation
186-----
187
188I simply couldn't find any lib supporting the full spec. Others were just wrong or used reflection and regex which i don't like.
189
190
191Contribution
192-----
193
194Feel free to make a pull request. For bigger changes create a issue first to discuss about it.
195
196
197License
198-----
199
200See [LICENSE](LICENSE) file.
201
){kind=link}
){kind=link}
){kind=link}