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