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