vendor/github.com/blang/semver/README.md

   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.