Update .bashrc
[dotfiles/.git] / .config / coc / extensions / node_modules / coc-prettier / node_modules / tslint / node_modules / semver / README.md
1 semver(1) -- The semantic versioner for npm
2 ===========================================
3
4 ## Install
5
6 ```bash
7 npm install --save semver
8 ````
9
10 ## Usage
11
12 As a node module:
13
14 ```js
15 const semver = require('semver')
16
17 semver.valid('1.2.3') // '1.2.3'
18 semver.valid('a.b.c') // null
19 semver.clean('  =v1.2.3   ') // '1.2.3'
20 semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
21 semver.gt('1.2.3', '9.8.7') // false
22 semver.lt('1.2.3', '9.8.7') // true
23 semver.minVersion('>=1.0.0') // '1.0.0'
24 semver.valid(semver.coerce('v2')) // '2.0.0'
25 semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
26 ```
27
28 As a command-line utility:
29
30 ```
31 $ semver -h
32
33 A JavaScript implementation of the https://semver.org/ specification
34 Copyright Isaac Z. Schlueter
35
36 Usage: semver [options] <version> [<version> [...]]
37 Prints valid versions sorted by SemVer precedence
38
39 Options:
40 -r --range <range>
41         Print versions that match the specified range.
42
43 -i --increment [<level>]
44         Increment a version by the specified level.  Level can
45         be one of: major, minor, patch, premajor, preminor,
46         prepatch, or prerelease.  Default level is 'patch'.
47         Only one version may be specified.
48
49 --preid <identifier>
50         Identifier to be used to prefix premajor, preminor,
51         prepatch or prerelease version increments.
52
53 -l --loose
54         Interpret versions and ranges loosely
55
56 -p --include-prerelease
57         Always include prerelease versions in range matching
58
59 -c --coerce
60         Coerce a string into SemVer if possible
61         (does not imply --loose)
62
63 Program exits successfully if any valid version satisfies
64 all supplied ranges, and prints all satisfying versions.
65
66 If no satisfying versions are found, then exits failure.
67
68 Versions are printed in ascending order, so supplying
69 multiple versions to the utility will just sort them.
70 ```
71
72 ## Versions
73
74 A "version" is described by the `v2.0.0` specification found at
75 <https://semver.org/>.
76
77 A leading `"="` or `"v"` character is stripped off and ignored.
78
79 ## Ranges
80
81 A `version range` is a set of `comparators` which specify versions
82 that satisfy the range.
83
84 A `comparator` is composed of an `operator` and a `version`.  The set
85 of primitive `operators` is:
86
87 * `<` Less than
88 * `<=` Less than or equal to
89 * `>` Greater than
90 * `>=` Greater than or equal to
91 * `=` Equal.  If no operator is specified, then equality is assumed,
92   so this operator is optional, but MAY be included.
93
94 For example, the comparator `>=1.2.7` would match the versions
95 `1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
96 or `1.1.0`.
97
98 Comparators can be joined by whitespace to form a `comparator set`,
99 which is satisfied by the **intersection** of all of the comparators
100 it includes.
101
102 A range is composed of one or more comparator sets, joined by `||`.  A
103 version matches a range if and only if every comparator in at least
104 one of the `||`-separated comparator sets is satisfied by the version.
105
106 For example, the range `>=1.2.7 <1.3.0` would match the versions
107 `1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
108 or `1.1.0`.
109
110 The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
111 `1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.
112
113 ### Prerelease Tags
114
115 If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
116 it will only be allowed to satisfy comparator sets if at least one
117 comparator with the same `[major, minor, patch]` tuple also has a
118 prerelease tag.
119
120 For example, the range `>1.2.3-alpha.3` would be allowed to match the
121 version `1.2.3-alpha.7`, but it would *not* be satisfied by
122 `3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
123 than" `1.2.3-alpha.3` according to the SemVer sort rules.  The version
124 range only accepts prerelease tags on the `1.2.3` version.  The
125 version `3.4.5` *would* satisfy the range, because it does not have a
126 prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.
127
128 The purpose for this behavior is twofold.  First, prerelease versions
129 frequently are updated very quickly, and contain many breaking changes
130 that are (by the author's design) not yet fit for public consumption.
131 Therefore, by default, they are excluded from range matching
132 semantics.
133
134 Second, a user who has opted into using a prerelease version has
135 clearly indicated the intent to use *that specific* set of
136 alpha/beta/rc versions.  By including a prerelease tag in the range,
137 the user is indicating that they are aware of the risk.  However, it
138 is still not appropriate to assume that they have opted into taking a
139 similar risk on the *next* set of prerelease versions.
140
141 Note that this behavior can be suppressed (treating all prerelease
142 versions as if they were normal versions, for the purpose of range
143 matching) by setting the `includePrerelease` flag on the options
144 object to any
145 [functions](https://github.com/npm/node-semver#functions) that do
146 range matching.
147
148 #### Prerelease Identifiers
149
150 The method `.inc` takes an additional `identifier` string argument that
151 will append the value of the string as a prerelease identifier:
152
153 ```javascript
154 semver.inc('1.2.3', 'prerelease', 'beta')
155 // '1.2.4-beta.0'
156 ```
157
158 command-line example:
159
160 ```bash
161 $ semver 1.2.3 -i prerelease --preid beta
162 1.2.4-beta.0
163 ```
164
165 Which then can be used to increment further:
166
167 ```bash
168 $ semver 1.2.4-beta.0 -i prerelease
169 1.2.4-beta.1
170 ```
171
172 ### Advanced Range Syntax
173
174 Advanced range syntax desugars to primitive comparators in
175 deterministic ways.
176
177 Advanced ranges may be combined in the same way as primitive
178 comparators using white space or `||`.
179
180 #### Hyphen Ranges `X.Y.Z - A.B.C`
181
182 Specifies an inclusive set.
183
184 * `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`
185
186 If a partial version is provided as the first version in the inclusive
187 range, then the missing pieces are replaced with zeroes.
188
189 * `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`
190
191 If a partial version is provided as the second version in the
192 inclusive range, then all versions that start with the supplied parts
193 of the tuple are accepted, but nothing that would be greater than the
194 provided tuple parts.
195
196 * `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
197 * `1.2.3 - 2` := `>=1.2.3 <3.0.0`
198
199 #### X-Ranges `1.2.x` `1.X` `1.2.*` `*`
200
201 Any of `X`, `x`, or `*` may be used to "stand in" for one of the
202 numeric values in the `[major, minor, patch]` tuple.
203
204 * `*` := `>=0.0.0` (Any version satisfies)
205 * `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
206 * `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)
207
208 A partial version range is treated as an X-Range, so the special
209 character is in fact optional.
210
211 * `""` (empty string) := `*` := `>=0.0.0`
212 * `1` := `1.x.x` := `>=1.0.0 <2.0.0`
213 * `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`
214
215 #### Tilde Ranges `~1.2.3` `~1.2` `~1`
216
217 Allows patch-level changes if a minor version is specified on the
218 comparator.  Allows minor-level changes if not.
219
220 * `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
221 * `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
222 * `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
223 * `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
224 * `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
225 * `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
226 * `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
227   the `1.2.3` version will be allowed, if they are greater than or
228   equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
229   `1.2.4-beta.2` would not, because it is a prerelease of a
230   different `[major, minor, patch]` tuple.
231
232 #### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`
233
234 Allows changes that do not modify the left-most non-zero digit in the
235 `[major, minor, patch]` tuple.  In other words, this allows patch and
236 minor updates for versions `1.0.0` and above, patch updates for
237 versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.
238
239 Many authors treat a `0.x` version as if the `x` were the major
240 "breaking-change" indicator.
241
242 Caret ranges are ideal when an author may make breaking changes
243 between `0.2.4` and `0.3.0` releases, which is a common practice.
244 However, it presumes that there will *not* be breaking changes between
245 `0.2.4` and `0.2.5`.  It allows for changes that are presumed to be
246 additive (but non-breaking), according to commonly observed practices.
247
248 * `^1.2.3` := `>=1.2.3 <2.0.0`
249 * `^0.2.3` := `>=0.2.3 <0.3.0`
250 * `^0.0.3` := `>=0.0.3 <0.0.4`
251 * `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
252   the `1.2.3` version will be allowed, if they are greater than or
253   equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
254   `1.2.4-beta.2` would not, because it is a prerelease of a
255   different `[major, minor, patch]` tuple.
256 * `^0.0.3-beta` := `>=0.0.3-beta <0.0.4`  Note that prereleases in the
257   `0.0.3` version *only* will be allowed, if they are greater than or
258   equal to `beta`.  So, `0.0.3-pr.2` would be allowed.
259
260 When parsing caret ranges, a missing `patch` value desugars to the
261 number `0`, but will allow flexibility within that value, even if the
262 major and minor versions are both `0`.
263
264 * `^1.2.x` := `>=1.2.0 <2.0.0`
265 * `^0.0.x` := `>=0.0.0 <0.1.0`
266 * `^0.0` := `>=0.0.0 <0.1.0`
267
268 A missing `minor` and `patch` values will desugar to zero, but also
269 allow flexibility within those values, even if the major version is
270 zero.
271
272 * `^1.x` := `>=1.0.0 <2.0.0`
273 * `^0.x` := `>=0.0.0 <1.0.0`
274
275 ### Range Grammar
276
277 Putting all this together, here is a Backus-Naur grammar for ranges,
278 for the benefit of parser authors:
279
280 ```bnf
281 range-set  ::= range ( logical-or range ) *
282 logical-or ::= ( ' ' ) * '||' ( ' ' ) *
283 range      ::= hyphen | simple ( ' ' simple ) * | ''
284 hyphen     ::= partial ' - ' partial
285 simple     ::= primitive | partial | tilde | caret
286 primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
287 partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
288 xr         ::= 'x' | 'X' | '*' | nr
289 nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
290 tilde      ::= '~' partial
291 caret      ::= '^' partial
292 qualifier  ::= ( '-' pre )? ( '+' build )?
293 pre        ::= parts
294 build      ::= parts
295 parts      ::= part ( '.' part ) *
296 part       ::= nr | [-0-9A-Za-z]+
297 ```
298
299 ## Functions
300
301 All methods and classes take a final `options` object argument.  All
302 options in this object are `false` by default.  The options supported
303 are:
304
305 - `loose`  Be more forgiving about not-quite-valid semver strings.
306   (Any resulting output will always be 100% strict compliant, of
307   course.)  For backwards compatibility reasons, if the `options`
308   argument is a boolean value instead of an object, it is interpreted
309   to be the `loose` param.
310 - `includePrerelease`  Set to suppress the [default
311   behavior](https://github.com/npm/node-semver#prerelease-tags) of
312   excluding prerelease tagged versions from ranges unless they are
313   explicitly opted into.
314
315 Strict-mode Comparators and Ranges will be strict about the SemVer
316 strings that they parse.
317
318 * `valid(v)`: Return the parsed version, or null if it's not valid.
319 * `inc(v, release)`: Return the version incremented by the release
320   type (`major`,   `premajor`, `minor`, `preminor`, `patch`,
321   `prepatch`, or `prerelease`), or null if it's not valid
322   * `premajor` in one call will bump the version up to the next major
323     version and down to a prerelease of that major version.
324     `preminor`, and `prepatch` work the same way.
325   * If called from a non-prerelease version, the `prerelease` will work the
326     same as `prepatch`. It increments the patch version, then makes a
327     prerelease. If the input version is already a prerelease it simply
328     increments it.
329 * `prerelease(v)`: Returns an array of prerelease components, or null
330   if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
331 * `major(v)`: Return the major version number.
332 * `minor(v)`: Return the minor version number.
333 * `patch(v)`: Return the patch version number.
334 * `intersects(r1, r2, loose)`: Return true if the two supplied ranges
335   or comparators intersect.
336 * `parse(v)`: Attempt to parse a string as a semantic version, returning either
337   a `SemVer` object or `null`.
338
339 ### Comparison
340
341 * `gt(v1, v2)`: `v1 > v2`
342 * `gte(v1, v2)`: `v1 >= v2`
343 * `lt(v1, v2)`: `v1 < v2`
344 * `lte(v1, v2)`: `v1 <= v2`
345 * `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
346   even if they're not the exact same string.  You already know how to
347   compare strings.
348 * `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
349 * `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
350   the corresponding function above.  `"==="` and `"!=="` do simple
351   string comparison, but are included for completeness.  Throws if an
352   invalid comparison string is provided.
353 * `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
354   `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
355 * `rcompare(v1, v2)`: The reverse of compare.  Sorts an array of versions
356   in descending order when passed to `Array.sort()`.
357 * `diff(v1, v2)`: Returns difference between two versions by the release type
358   (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
359   or null if the versions are the same.
360
361 ### Comparators
362
363 * `intersects(comparator)`: Return true if the comparators intersect
364
365 ### Ranges
366
367 * `validRange(range)`: Return the valid range or null if it's not valid
368 * `satisfies(version, range)`: Return true if the version satisfies the
369   range.
370 * `maxSatisfying(versions, range)`: Return the highest version in the list
371   that satisfies the range, or `null` if none of them do.
372 * `minSatisfying(versions, range)`: Return the lowest version in the list
373   that satisfies the range, or `null` if none of them do.
374 * `minVersion(range)`: Return the lowest version that can possibly match
375   the given range.
376 * `gtr(version, range)`: Return `true` if version is greater than all the
377   versions possible in the range.
378 * `ltr(version, range)`: Return `true` if version is less than all the
379   versions possible in the range.
380 * `outside(version, range, hilo)`: Return true if the version is outside
381   the bounds of the range in either the high or low direction.  The
382   `hilo` argument must be either the string `'>'` or `'<'`.  (This is
383   the function called by `gtr` and `ltr`.)
384 * `intersects(range)`: Return true if any of the ranges comparators intersect
385
386 Note that, since ranges may be non-contiguous, a version might not be
387 greater than a range, less than a range, *or* satisfy a range!  For
388 example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
389 until `2.0.0`, so the version `1.2.10` would not be greater than the
390 range (because `2.0.1` satisfies, which is higher), nor less than the
391 range (since `1.2.8` satisfies, which is lower), and it also does not
392 satisfy the range.
393
394 If you want to know if a version satisfies or does not satisfy a
395 range, use the `satisfies(version, range)` function.
396
397 ### Coercion
398
399 * `coerce(version)`: Coerces a string to semver if possible
400
401 This aims to provide a very forgiving translation of a non-semver string to
402 semver. It looks for the first digit in a string, and consumes all
403 remaining characters which satisfy at least a partial semver (e.g., `1`,
404 `1.2`, `1.2.3`) up to the max permitted length (256 characters).  Longer
405 versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).  All
406 surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
407 `3.4.0`).  Only text which lacks digits will fail coercion (`version one`
408 is not valid).  The maximum  length for any semver component considered for
409 coercion is 16 characters; longer components will be ignored
410 (`10000000000000000.4.7.4` becomes `4.7.4`).  The maximum value for any
411 semver component is `Number.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
412 components are invalid (`9999999999999999.4.7.4` is likely invalid).