org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/doc/misc/semver.md

   1 semver(7) -- The semantic versioner for npm
   2 ===========================================
   3
   4 ## Usage
   5
   6     $ npm install semver
   7
   8     semver.valid('1.2.3') // '1.2.3'
   9     semver.valid('a.b.c') // null
  10     semver.clean('  =v1.2.3   ') // '1.2.3'
  11     semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
  12     semver.gt('1.2.3', '9.8.7') // false
  13     semver.lt('1.2.3', '9.8.7') // true
  14
  15 As a command-line utility:
  16
  17     $ semver -h
  18
  19     Usage: semver <version> [<version> [...]] [-r <range> | -i <inc> | --preid <identifier> | -l | -rv]
  20     Test if version(s) satisfy the supplied range(s), and sort them.
  21
  22     Multiple versions or ranges may be supplied, unless increment
  23     option is specified.  In that case, only a single version may
  24     be used, and it is incremented by the specified level
  25
  26     Program exits successfully if any valid version satisfies
  27     all supplied ranges, and prints all satisfying versions.
  28
  29     If no versions are valid, or ranges are not satisfied,
  30     then exits failure.
  31
  32     Versions are printed in ascending order, so supplying
  33     multiple versions to the utility will just sort them.
  34
  35 ## Versions
  36
  37 A "version" is described by the `v2.0.0` specification found at
  38 <http://semver.org/>.
  39
  40 A leading `"="` or `"v"` character is stripped off and ignored.
  41
  42 ## Ranges
  43
  44 A `version range` is a set of `comparators` which specify versions
  45 that satisfy the range.
  46
  47 A `comparator` is composed of an `operator` and a `version`.  The set
  48 of primitive `operators` is:
  49
  50 * `<` Less than
  51 * `<=` Less than or equal to
  52 * `>` Greater than
  53 * `>=` Greater than or equal to
  54 * `=` Equal.  If no operator is specified, then equality is assumed,
  55   so this operator is optional, but MAY be included.
  56
  57 For example, the comparator `>=1.2.7` would match the versions
  58 `1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
  59 or `1.1.0`.
  60
  61 Comparators can be joined by whitespace to form a `comparator set`,
  62 which is satisfied by the **intersection** of all of the comparators
  63 it includes.
  64
  65 A range is composed of one or more comparator sets, joined by `||`.  A
  66 version matches a range if and only if every comparator in at least
  67 one of the `||`-separated comparator sets is satisfied by the version.
  68
  69 For example, the range `>=1.2.7 <1.3.0` would match the versions
  70 `1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
  71 or `1.1.0`.
  72
  73 The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
  74 `1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.
  75
  76 ### Prerelease Tags
  77
  78 If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
  79 it will only be allowed to satisfy comparator sets if at least one
  80 comparator with the same `[major, minor, patch]` tuple also has a
  81 prerelease tag.
  82
  83 For example, the range `>1.2.3-alpha.3` would be allowed to match the
  84 version `1.2.3-alpha.7`, but it would *not* be satisfied by
  85 `3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
  86 than" `1.2.3-alpha.3` according to the SemVer sort rules.  The version
  87 range only accepts prerelease tags on the `1.2.3` version.  The
  88 version `3.4.5` *would* satisfy the range, because it does not have a
  89 prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.
  90
  91 The purpose for this behavior is twofold.  First, prerelease versions
  92 frequently are updated very quickly, and contain many breaking changes
  93 that are (by the author's design) not yet fit for public consumption.
  94 Therefore, by default, they are excluded from range matching
  95 semantics.
  96
  97 Second, a user who has opted into using a prerelease version has
  98 clearly indicated the intent to use *that specific* set of
  99 alpha/beta/rc versions.  By including a prerelease tag in the range,
 100 the user is indicating that they are aware of the risk.  However, it
 101 is still not appropriate to assume that they have opted into taking a
 102 similar risk on the *next* set of prerelease versions.
 103
 104 #### Prerelease Identifiers
 105
 106 The method `.inc` takes an additional `identifier` string argument that
 107 will append the value of the string as a prerelease identifier:
 108
 109 ```javascript
 110 > semver.inc('1.2.3', 'prerelease', 'beta')
 111 '1.2.4-beta.0'
 112 ```
 113
 114 command-line example:
 115
 116 ```shell
 117 $ semver 1.2.3 -i prerelease --preid beta
 118 1.2.4-beta.0
 119 ```
 120
 121 Which then can be used to increment further:
 122
 123 ```shell
 124 $ semver 1.2.4-beta.0 -i prerelease
 125 1.2.4-beta.1
 126 ```
 127
 128 ### Advanced Range Syntax
 129
 130 Advanced range syntax desugars to primitive comparators in
 131 deterministic ways.
 132
 133 Advanced ranges may be combined in the same way as primitive
 134 comparators using white space or `||`.
 135
 136 #### Hyphen Ranges `X.Y.Z - A.B.C`
 137
 138 Specifies an inclusive set.
 139
 140 * `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`
 141
 142 If a partial version is provided as the first version in the inclusive
 143 range, then the missing pieces are replaced with zeroes.
 144
 145 * `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`
 146
 147 If a partial version is provided as the second version in the
 148 inclusive range, then all versions that start with the supplied parts
 149 of the tuple are accepted, but nothing that would be greater than the
 150 provided tuple parts.
 151
 152 * `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
 153 * `1.2.3 - 2` := `>=1.2.3 <3.0.0`
 154
 155 #### X-Ranges `1.2.x` `1.X` `1.2.*` `*`
 156
 157 Any of `X`, `x`, or `*` may be used to "stand in" for one of the
 158 numeric values in the `[major, minor, patch]` tuple.
 159
 160 * `*` := `>=0.0.0` (Any version satisfies)
 161 * `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
 162 * `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)
 163
 164 A partial version range is treated as an X-Range, so the special
 165 character is in fact optional.
 166
 167 * `""` (empty string) := `*` := `>=0.0.0`
 168 * `1` := `1.x.x` := `>=1.0.0 <2.0.0`
 169 * `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`
 170
 171 #### Tilde Ranges `~1.2.3` `~1.2` `~1`
 172
 173 Allows patch-level changes if a minor version is specified on the
 174 comparator.  Allows minor-level changes if not.
 175
 176 * `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
 177 * `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
 178 * `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
 179 * `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
 180 * `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
 181 * `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
 182 * `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
 183   the `1.2.3` version will be allowed, if they are greater than or
 184   equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
 185   `1.2.4-beta.2` would not, because it is a prerelease of a
 186   different `[major, minor, patch]` tuple.
 187
 188 #### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`
 189
 190 Allows changes that do not modify the left-most non-zero digit in the
 191 `[major, minor, patch]` tuple.  In other words, this allows patch and
 192 minor updates for versions `1.0.0` and above, patch updates for
 193 versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.
 194
 195 Many authors treat a `0.x` version as if the `x` were the major
 196 "breaking-change" indicator.
 197
 198 Caret ranges are ideal when an author may make breaking changes
 199 between `0.2.4` and `0.3.0` releases, which is a common practice.
 200 However, it presumes that there will *not* be breaking changes between
 201 `0.2.4` and `0.2.5`.  It allows for changes that are presumed to be
 202 additive (but non-breaking), according to commonly observed practices.
 203
 204 * `^1.2.3` := `>=1.2.3 <2.0.0`
 205 * `^0.2.3` := `>=0.2.3 <0.3.0`
 206 * `^0.0.3` := `>=0.0.3 <0.0.4`
 207 * `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
 208   the `1.2.3` version will be allowed, if they are greater than or
 209   equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
 210   `1.2.4-beta.2` would not, because it is a prerelease of a
 211   different `[major, minor, patch]` tuple.
 212 * `^0.0.3-beta` := `>=0.0.3-beta <0.0.4`  Note that prereleases in the
 213   `0.0.3` version *only* will be allowed, if they are greater than or
 214   equal to `beta`.  So, `0.0.3-pr.2` would be allowed.
 215
 216 When parsing caret ranges, a missing `patch` value desugars to the
 217 number `0`, but will allow flexibility within that value, even if the
 218 major and minor versions are both `0`.
 219
 220 * `^1.2.x` := `>=1.2.0 <2.0.0`
 221 * `^0.0.x` := `>=0.0.0 <0.1.0`
 222 * `^0.0` := `>=0.0.0 <0.1.0`
 223
 224 A missing `minor` and `patch` values will desugar to zero, but also
 225 allow flexibility within those values, even if the major version is
 226 zero.
 227
 228 * `^1.x` := `>=1.0.0 <2.0.0`
 229 * `^0.x` := `>=0.0.0 <1.0.0`
 230
 231 ### Range Grammar
 232
 233 Putting all this together, here is a Backus-Naur grammar for ranges,
 234 for the benefit of parser authors:
 235
 236 ```bnf
 237 range-set  ::= range ( logical-or range ) *
 238 logical-or ::= ( ' ' ) * '||' ( ' ' ) *
 239 range      ::= hyphen | simple ( ' ' simple ) * | ''
 240 hyphen     ::= partial ' - ' partial
 241 simple     ::= primitive | partial | tilde | caret
 242 primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' | ) partial
 243 partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
 244 xr         ::= 'x' | 'X' | '*' | nr
 245 nr         ::= '0' | ['1'-'9']['0'-'9']+
 246 tilde      ::= '~' partial
 247 caret      ::= '^' partial
 248 qualifier  ::= ( '-' pre )? ( '+' build )?
 249 pre        ::= parts
 250 build      ::= parts
 251 parts      ::= part ( '.' part ) *
 252 part       ::= nr | [-0-9A-Za-z]+
 253 ```
 254
 255 ## Functions
 256
 257 All methods and classes take a final `loose` boolean argument that, if
 258 true, will be more forgiving about not-quite-valid semver strings.
 259 The resulting output will always be 100% strict, of course.
 260
 261 Strict-mode Comparators and Ranges will be strict about the SemVer
 262 strings that they parse.
 263
 264 * `valid(v)`: Return the parsed version, or null if it's not valid.
 265 * `inc(v, release)`: Return the version incremented by the release
 266   type (`major`,   `premajor`, `minor`, `preminor`, `patch`,
 267   `prepatch`, or `prerelease`), or null if it's not valid
 268   * `premajor` in one call will bump the version up to the next major
 269     version and down to a prerelease of that major version.
 270     `preminor`, and `prepatch` work the same way.
 271   * If called from a non-prerelease version, the `prerelease` will work the
 272     same as `prepatch`. It increments the patch version, then makes a
 273     prerelease. If the input version is already a prerelease it simply
 274     increments it.
 275 * `major(v)`: Return the major version number.
 276 * `minor(v)`: Return the minor version number.
 277 * `patch(v)`: Return the patch version number.
 278
 279 ### Comparison
 280
 281 * `gt(v1, v2)`: `v1 > v2`
 282 * `gte(v1, v2)`: `v1 >= v2`
 283 * `lt(v1, v2)`: `v1 < v2`
 284 * `lte(v1, v2)`: `v1 <= v2`
 285 * `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
 286   even if they're not the exact same string.  You already know how to
 287   compare strings.
 288 * `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
 289 * `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
 290   the corresponding function above.  `"==="` and `"!=="` do simple
 291   string comparison, but are included for completeness.  Throws if an
 292   invalid comparison string is provided.
 293 * `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
 294   `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
 295 * `rcompare(v1, v2)`: The reverse of compare.  Sorts an array of versions
 296   in descending order when passed to `Array.sort()`.
 297 * `diff(v1, v2)`: Returns difference between two versions by the release type
 298   (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
 299   or null if the versions are the same.
 300
 301
 302 ### Ranges
 303
 304 * `validRange(range)`: Return the valid range or null if it's not valid
 305 * `satisfies(version, range)`: Return true if the version satisfies the
 306   range.
 307 * `maxSatisfying(versions, range)`: Return the highest version in the list
 308   that satisfies the range, or `null` if none of them do.
 309 * `gtr(version, range)`: Return `true` if version is greater than all the
 310   versions possible in the range.
 311 * `ltr(version, range)`: Return `true` if version is less than all the
 312   versions possible in the range.
 313 * `outside(version, range, hilo)`: Return true if the version is outside
 314   the bounds of the range in either the high or low direction.  The
 315   `hilo` argument must be either the string `'>'` or `'<'`.  (This is
 316   the function called by `gtr` and `ltr`.)
 317
 318 Note that, since ranges may be non-contiguous, a version might not be
 319 greater than a range, less than a range, *or* satisfy a range!  For
 320 example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
 321 until `2.0.0`, so the version `1.2.10` would not be greater than the
 322 range (because `2.0.1` satisfies, which is higher), nor less than the
 323 range (since `1.2.8` satisfies, which is lower), and it also does not
 324 satisfy the range.
 325
 326 If you want to know if a version satisfies or does not satisfy a
 327 range, use the `satisfies(version, range)` function.