diff options
Diffstat (limited to 'deps/npm/doc/misc/semver.md')
-rw-r--r-- | deps/npm/doc/misc/semver.md | 90 |
1 files changed, 53 insertions, 37 deletions
diff --git a/deps/npm/doc/misc/semver.md b/deps/npm/doc/misc/semver.md index 176fbcba93..6c7d28061c 100644 --- a/deps/npm/doc/misc/semver.md +++ b/deps/npm/doc/misc/semver.md @@ -34,7 +34,7 @@ As a command-line utility: ## Versions -A "version" is described by the v2.0.0 specification found at +A "version" is described by the `v2.0.0` specification found at <http://semver.org/>. A leading `"="` or `"v"` character is stripped off and ignored. @@ -43,9 +43,10 @@ A leading `"="` or `"v"` character is stripped off and ignored. The following range styles are supported: -* `1.2.3` A specific version. When nothing else will do. Note that - build metadata is still ignored, so `1.2.3+build2012` will satisfy - this range. +* `1.2.3` A specific version. When nothing else will do. Must be a full + version number, with major, minor, and patch versions specified. + Note that build metadata is still ignored, so `1.2.3+build2012` will + satisfy this range. * `>1.2.3` Greater than a specific version. * `<1.2.3` Less than a specific version. If there is no prerelease tag on the version range, then no prerelease version will be allowed @@ -56,26 +57,33 @@ The following range styles are supported: * `<=1.2.3` Less than or equal to. In this case, prerelease versions ARE allowed, so `1.2.3-beta` would satisfy. * `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4` -* `~1.2.3` := `>=1.2.3-0 <1.3.0-0` "Reasonably close to 1.2.3". When +* `~1.2.3` := `>=1.2.3-0 <1.3.0-0` "Reasonably close to `1.2.3`". When using tilde operators, prerelease versions are supported as well, but a prerelease of the next significant digit will NOT be satisfactory, so `1.3.0-beta` will not satisfy `~1.2.3`. -* `^1.2.3` := `>=1.2.3-0 <2.0.0-0` "Compatible with 1.2.3". When +* `^1.2.3` := `>=1.2.3-0 <2.0.0-0` "Compatible with `1.2.3`". When using caret operators, anything from the specified version (including prerelease) will be supported up to, but not including, the next major version (or its prereleases). `1.5.1` will satisfy `^1.2.3`, while `1.2.2` and `2.0.0-beta` will not. -* `^0.1.3` := `>=0.1.3-0 <0.2.0-0` "Compatible with 0.1.3". 0.x.x versions are +* `^0.1.3` := `>=0.1.3-0 <0.2.0-0` "Compatible with `0.1.3`". `0.x.x` versions are special: the first non-zero component indicates potentially breaking changes, meaning the caret operator matches any version with the same first non-zero component starting at the specified version. -* `^0.0.2` := `=0.0.2` "Only the version 0.0.2 is considered compatible" -* `~1.2` := `>=1.2.0-0 <1.3.0-0` "Any version starting with 1.2" -* `^1.2` := `>=1.2.0-0 <2.0.0-0` "Any version compatible with 1.2" -* `1.2.x` := `>=1.2.0-0 <1.3.0-0` "Any version starting with 1.2" -* `~1` := `>=1.0.0-0 <2.0.0-0` "Any version starting with 1" -* `^1` := `>=1.0.0-0 <2.0.0-0` "Any version compatible with 1" -* `1.x` := `>=1.0.0-0 <2.0.0-0` "Any version starting with 1" +* `^0.0.2` := `=0.0.2` "Only the version `0.0.2` is considered compatible" +* `~1.2` := `>=1.2.0-0 <1.3.0-0` "Any version starting with `1.2`" +* `^1.2` := `>=1.2.0-0 <2.0.0-0` "Any version compatible with `1.2`" +* `1.2.x` := `>=1.2.0-0 <1.3.0-0` "Any version starting with `1.2`" +* `1.2.*` Same as `1.2.x`. +* `1.2` Same as `1.2.x`. +* `~1` := `>=1.0.0-0 <2.0.0-0` "Any version starting with `1`" +* `^1` := `>=1.0.0-0 <2.0.0-0` "Any version compatible with `1`" +* `1.x` := `>=1.0.0-0 <2.0.0-0` "Any version starting with `1`" +* `1.*` Same as `1.x`. +* `1` Same as `1.x`. +* `*` Any version whatsoever. +* `x` Same as `*`. +* `""` (just an empty string) Same as `*`. Ranges can be joined with either a space (which implies "and") or a @@ -90,42 +98,50 @@ The resulting output will always be 100% strict, of course. Strict-mode Comparators and Ranges will be strict about the SemVer strings that they parse. -* valid(v): Return the parsed version, or null if it's not valid. -* inc(v, release): Return the version incremented by the release type - (major, minor, patch, or prerelease), or null if it's not valid. +* `valid(v)`: Return the parsed version, or null if it's not valid. +* `inc(v, release)`: Return the version incremented by the release + type (`major`, `premajor`, `minor`, `preminor`, `patch`, + `prepatch`, or `prerelease`), or null if it's not valid + * `premajor` in one call will bump the version up to the next major + version and down to a prerelease of that major version. + `preminor`, and `prepatch` work the same way. + * If called from a non-prerelease version, the `prerelease` will work the + same as `prepatch`. It increments the patch version, then makes a + prerelease. If the input version is already a prerelease it simply + increments it. ### Comparison -* gt(v1, v2): `v1 > v2` -* gte(v1, v2): `v1 >= v2` -* lt(v1, v2): `v1 < v2` -* lte(v1, v2): `v1 <= v2` -* eq(v1, v2): `v1 == v2` This is true if they're logically equivalent, +* `gt(v1, v2)`: `v1 > v2` +* `gte(v1, v2)`: `v1 >= v2` +* `lt(v1, v2)`: `v1 < v2` +* `lte(v1, v2)`: `v1 <= v2` +* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent, even if they're not the exact same string. You already know how to compare strings. -* neq(v1, v2): `v1 != v2` The opposite of eq. -* cmp(v1, comparator, v2): Pass in a comparison string, and it'll call +* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`. +* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call the corresponding function above. `"==="` and `"!=="` do simple string comparison, but are included for completeness. Throws if an invalid comparison string is provided. -* compare(v1, v2): Return 0 if v1 == v2, or 1 if v1 is greater, or -1 if - v2 is greater. Sorts in ascending order if passed to Array.sort(). -* rcompare(v1, v2): The reverse of compare. Sorts an array of versions - in descending order when passed to Array.sort(). +* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if + `v2` is greater. Sorts in ascending order if passed to `Array.sort()`. +* `rcompare(v1, v2)`: The reverse of compare. Sorts an array of versions + in descending order when passed to `Array.sort()`. ### Ranges -* validRange(range): Return the valid range or null if it's not valid -* satisfies(version, range): Return true if the version satisfies the +* `validRange(range)`: Return the valid range or null if it's not valid +* `satisfies(version, range)`: Return true if the version satisfies the range. -* maxSatisfying(versions, range): Return the highest version in the list - that satisfies the range, or null if none of them do. -* gtr(version, range): Return true if version is greater than all the +* `maxSatisfying(versions, range)`: Return the highest version in the list + that satisfies the range, or `null` if none of them do. +* `gtr(version, range)`: Return `true` if version is greater than all the versions possible in the range. -* ltr(version, range): Return true if version is less than all the +* `ltr(version, range)`: Return `true` if version is less than all the versions possible in the range. -* outside(version, range, hilo): Return true if the version is outside +* `outside(version, range, hilo)`: Return true if the version is outside the bounds of the range in either the high or low direction. The `hilo` argument must be either the string `'>'` or `'<'`. (This is the function called by `gtr` and `ltr`.) @@ -134,8 +150,8 @@ Note that, since ranges may be non-contiguous, a version might not be greater than a range, less than a range, *or* satisfy a range! For example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9` until `2.0.0`, so the version `1.2.10` would not be greater than the -range (because 2.0.1 satisfies, which is higher), nor less than the -range (since 1.2.8 satisfies, which is lower), and it also does not +range (because `2.0.1` satisfies, which is higher), nor less than the +range (since `1.2.8` satisfies, which is lower), and it also does not satisfy the range. If you want to know if a version satisfies or does not satisfy a |