diff options
Diffstat (limited to 'deps/node/deps/npm/man/man7/semver.7')
| -rw-r--r-- | deps/node/deps/npm/man/man7/semver.7 | 497 |
1 files changed, 497 insertions, 0 deletions
diff --git a/deps/node/deps/npm/man/man7/semver.7 b/deps/node/deps/npm/man/man7/semver.7 new file mode 100644 index 00000000..60f62c7e --- /dev/null +++ b/deps/node/deps/npm/man/man7/semver.7 @@ -0,0 +1,497 @@ +.TH "SEMVER" "7" "January 2019" "" "" +.SH "NAME" +\fBsemver\fR \- The semantic versioner for npm +.SH Install +.P +.RS 2 +.nf +npm install \-\-save semver +` +.fi +.RE +.SH Usage +.P +As a node module: +.P +.RS 2 +.nf +const semver = require('semver') + +semver\.valid('1\.2\.3') // '1\.2\.3' +semver\.valid('a\.b\.c') // null +semver\.clean(' =v1\.2\.3 ') // '1\.2\.3' +semver\.satisfies('1\.2\.3', '1\.x || >=2\.5\.0 || 5\.0\.0 \- 7\.2\.3') // true +semver\.gt('1\.2\.3', '9\.8\.7') // false +semver\.lt('1\.2\.3', '9\.8\.7') // true +semver\.valid(semver\.coerce('v2')) // '2\.0\.0' +semver\.valid(semver\.coerce('42\.6\.7\.9\.3\-alpha')) // '42\.6\.7' +.fi +.RE +.P +As a command\-line utility: +.P +.RS 2 +.nf +$ semver \-h + +A JavaScript implementation of the http://semver\.org/ specification +Copyright Isaac Z\. Schlueter + +Usage: semver [options] <version> [<version> [\.\.\.]] +Prints valid versions sorted by SemVer precedence + +Options: +\-r \-\-range <range> + Print versions that match the specified range\. + +\-i \-\-increment [<level>] + Increment a version by the specified level\. Level can + be one of: major, minor, patch, premajor, preminor, + prepatch, or prerelease\. Default level is 'patch'\. + Only one version may be specified\. + +\-\-preid <identifier> + Identifier to be used to prefix premajor, preminor, + prepatch or prerelease version increments\. + +\-l \-\-loose + Interpret versions and ranges loosely + +\-p \-\-include\-prerelease + Always include prerelease versions in range matching + +\-c \-\-coerce + Coerce a string into SemVer if possible + (does not imply \-\-loose) + +Program exits successfully if any valid version satisfies +all supplied ranges, and prints all satisfying versions\. + +If no satisfying versions are found, then exits failure\. + +Versions are printed in ascending order, so supplying +multiple versions to the utility will just sort them\. +.fi +.RE +.SH Versions +.P +A "version" is described by the \fBv2\.0\.0\fP specification found at +http://semver\.org/\|\. +.P +A leading \fB"="\fP or \fB"v"\fP character is stripped off and ignored\. +.SH Ranges +.P +A \fBversion range\fP is a set of \fBcomparators\fP which specify versions +that satisfy the range\. +.P +A \fBcomparator\fP is composed of an \fBoperator\fP and a \fBversion\fP\|\. The set +of primitive \fBoperators\fP is: +.RS 0 +.IP \(bu 2 +\fB<\fP Less than +.IP \(bu 2 +\fB<=\fP Less than or equal to +.IP \(bu 2 +\fB>\fP Greater than +.IP \(bu 2 +\fB>=\fP Greater than or equal to +.IP \(bu 2 +\fB=\fP Equal\. If no operator is specified, then equality is assumed, +so this operator is optional, but MAY be included\. + +.RE +.P +For example, the comparator \fB>=1\.2\.7\fP would match the versions +\fB1\.2\.7\fP, \fB1\.2\.8\fP, \fB2\.5\.3\fP, and \fB1\.3\.9\fP, but not the versions \fB1\.2\.6\fP +or \fB1\.1\.0\fP\|\. +.P +Comparators can be joined by whitespace to form a \fBcomparator set\fP, +which is satisfied by the \fBintersection\fR of all of the comparators +it includes\. +.P +A range is composed of one or more comparator sets, joined by \fB||\fP\|\. A +version matches a range if and only if every comparator in at least +one of the \fB||\fP\-separated comparator sets is satisfied by the version\. +.P +For example, the range \fB>=1\.2\.7 <1\.3\.0\fP would match the versions +\fB1\.2\.7\fP, \fB1\.2\.8\fP, and \fB1\.2\.99\fP, but not the versions \fB1\.2\.6\fP, \fB1\.3\.0\fP, +or \fB1\.1\.0\fP\|\. +.P +The range \fB1\.2\.7 || >=1\.2\.9 <2\.0\.0\fP would match the versions \fB1\.2\.7\fP, +\fB1\.2\.9\fP, and \fB1\.4\.6\fP, but not the versions \fB1\.2\.8\fP or \fB2\.0\.0\fP\|\. +.SS Prerelease Tags +.P +If a version has a prerelease tag (for example, \fB1\.2\.3\-alpha\.3\fP) then +it will only be allowed to satisfy comparator sets if at least one +comparator with the same \fB[major, minor, patch]\fP tuple also has a +prerelease tag\. +.P +For example, the range \fB>1\.2\.3\-alpha\.3\fP would be allowed to match the +version \fB1\.2\.3\-alpha\.7\fP, but it would \fInot\fR be satisfied by +\fB3\.4\.5\-alpha\.9\fP, even though \fB3\.4\.5\-alpha\.9\fP is technically "greater +than" \fB1\.2\.3\-alpha\.3\fP according to the SemVer sort rules\. The version +range only accepts prerelease tags on the \fB1\.2\.3\fP version\. The +version \fB3\.4\.5\fP \fIwould\fR satisfy the range, because it does not have a +prerelease flag, and \fB3\.4\.5\fP is greater than \fB1\.2\.3\-alpha\.7\fP\|\. +.P +The purpose for this behavior is twofold\. First, prerelease versions +frequently are updated very quickly, and contain many breaking changes +that are (by the author's design) not yet fit for public consumption\. +Therefore, by default, they are excluded from range matching +semantics\. +.P +Second, a user who has opted into using a prerelease version has +clearly indicated the intent to use \fIthat specific\fR set of +alpha/beta/rc versions\. By including a prerelease tag in the range, +the user is indicating that they are aware of the risk\. However, it +is still not appropriate to assume that they have opted into taking a +similar risk on the \fInext\fR set of prerelease versions\. +.SS Prerelease Identifiers +.P +The method \fB\|\.inc\fP takes an additional \fBidentifier\fP string argument that +will append the value of the string as a prerelease identifier: +.P +.RS 2 +.nf +semver\.inc('1\.2\.3', 'prerelease', 'beta') +// '1\.2\.4\-beta\.0' +.fi +.RE +.P +command\-line example: +.P +.RS 2 +.nf +$ semver 1\.2\.3 \-i prerelease \-\-preid beta +1\.2\.4\-beta\.0 +.fi +.RE +.P +Which then can be used to increment further: +.P +.RS 2 +.nf +$ semver 1\.2\.4\-beta\.0 \-i prerelease +1\.2\.4\-beta\.1 +.fi +.RE +.SS Advanced Range Syntax +.P +Advanced range syntax desugars to primitive comparators in +deterministic ways\. +.P +Advanced ranges may be combined in the same way as primitive +comparators using white space or \fB||\fP\|\. +.SS Hyphen Ranges \fBX\.Y\.Z \- A\.B\.C\fP +.P +Specifies an inclusive set\. +.RS 0 +.IP \(bu 2 +\fB1\.2\.3 \- 2\.3\.4\fP := \fB>=1\.2\.3 <=2\.3\.4\fP + +.RE +.P +If a partial version is provided as the first version in the inclusive +range, then the missing pieces are replaced with zeroes\. +.RS 0 +.IP \(bu 2 +\fB1\.2 \- 2\.3\.4\fP := \fB>=1\.2\.0 <=2\.3\.4\fP + +.RE +.P +If a partial version is provided as the second version in the +inclusive range, then all versions that start with the supplied parts +of the tuple are accepted, but nothing that would be greater than the +provided tuple parts\. +.RS 0 +.IP \(bu 2 +\fB1\.2\.3 \- 2\.3\fP := \fB>=1\.2\.3 <2\.4\.0\fP +.IP \(bu 2 +\fB1\.2\.3 \- 2\fP := \fB>=1\.2\.3 <3\.0\.0\fP + +.RE +.SS X\-Ranges \fB1\.2\.x\fP \fB1\.X\fP \fB1\.2\.*\fP \fB*\fP +.P +Any of \fBX\fP, \fBx\fP, or \fB*\fP may be used to "stand in" for one of the +numeric values in the \fB[major, minor, patch]\fP tuple\. +.RS 0 +.IP \(bu 2 +\fB*\fP := \fB>=0\.0\.0\fP (Any version satisfies) +.IP \(bu 2 +\fB1\.x\fP := \fB>=1\.0\.0 <2\.0\.0\fP (Matching major version) +.IP \(bu 2 +\fB1\.2\.x\fP := \fB>=1\.2\.0 <1\.3\.0\fP (Matching major and minor versions) + +.RE +.P +A partial version range is treated as an X\-Range, so the special +character is in fact optional\. +.RS 0 +.IP \(bu 2 +\fB""\fP (empty string) := \fB*\fP := \fB>=0\.0\.0\fP +.IP \(bu 2 +\fB1\fP := \fB1\.x\.x\fP := \fB>=1\.0\.0 <2\.0\.0\fP +.IP \(bu 2 +\fB1\.2\fP := \fB1\.2\.x\fP := \fB>=1\.2\.0 <1\.3\.0\fP + +.RE +.SS Tilde Ranges \fB~1\.2\.3\fP \fB~1\.2\fP \fB~1\fP +.P +Allows patch\-level changes if a minor version is specified on the +comparator\. Allows minor\-level changes if not\. +.RS 0 +.IP \(bu 2 +\fB~1\.2\.3\fP := \fB>=1\.2\.3 <1\.(2+1)\.0\fP := \fB>=1\.2\.3 <1\.3\.0\fP +.IP \(bu 2 +\fB~1\.2\fP := \fB>=1\.2\.0 <1\.(2+1)\.0\fP := \fB>=1\.2\.0 <1\.3\.0\fP (Same as \fB1\.2\.x\fP) +.IP \(bu 2 +\fB~1\fP := \fB>=1\.0\.0 <(1+1)\.0\.0\fP := \fB>=1\.0\.0 <2\.0\.0\fP (Same as \fB1\.x\fP) +.IP \(bu 2 +\fB~0\.2\.3\fP := \fB>=0\.2\.3 <0\.(2+1)\.0\fP := \fB>=0\.2\.3 <0\.3\.0\fP +.IP \(bu 2 +\fB~0\.2\fP := \fB>=0\.2\.0 <0\.(2+1)\.0\fP := \fB>=0\.2\.0 <0\.3\.0\fP (Same as \fB0\.2\.x\fP) +.IP \(bu 2 +\fB~0\fP := \fB>=0\.0\.0 <(0+1)\.0\.0\fP := \fB>=0\.0\.0 <1\.0\.0\fP (Same as \fB0\.x\fP) +.IP \(bu 2 +\fB~1\.2\.3\-beta\.2\fP := \fB>=1\.2\.3\-beta\.2 <1\.3\.0\fP Note that prereleases in +the \fB1\.2\.3\fP version will be allowed, if they are greater than or +equal to \fBbeta\.2\fP\|\. So, \fB1\.2\.3\-beta\.4\fP would be allowed, but +\fB1\.2\.4\-beta\.2\fP would not, because it is a prerelease of a +different \fB[major, minor, patch]\fP tuple\. + +.RE +.SS Caret Ranges \fB^1\.2\.3\fP \fB^0\.2\.5\fP \fB^0\.0\.4\fP +.P +Allows changes that do not modify the left\-most non\-zero digit in the +\fB[major, minor, patch]\fP tuple\. In other words, this allows patch and +minor updates for versions \fB1\.0\.0\fP and above, patch updates for +versions \fB0\.X >=0\.1\.0\fP, and \fIno\fR updates for versions \fB0\.0\.X\fP\|\. +.P +Many authors treat a \fB0\.x\fP version as if the \fBx\fP were the major +"breaking\-change" indicator\. +.P +Caret ranges are ideal when an author may make breaking changes +between \fB0\.2\.4\fP and \fB0\.3\.0\fP releases, which is a common practice\. +However, it presumes that there will \fInot\fR be breaking changes between +\fB0\.2\.4\fP and \fB0\.2\.5\fP\|\. It allows for changes that are presumed to be +additive (but non\-breaking), according to commonly observed practices\. +.RS 0 +.IP \(bu 2 +\fB^1\.2\.3\fP := \fB>=1\.2\.3 <2\.0\.0\fP +.IP \(bu 2 +\fB^0\.2\.3\fP := \fB>=0\.2\.3 <0\.3\.0\fP +.IP \(bu 2 +\fB^0\.0\.3\fP := \fB>=0\.0\.3 <0\.0\.4\fP +.IP \(bu 2 +\fB^1\.2\.3\-beta\.2\fP := \fB>=1\.2\.3\-beta\.2 <2\.0\.0\fP Note that prereleases in +the \fB1\.2\.3\fP version will be allowed, if they are greater than or +equal to \fBbeta\.2\fP\|\. So, \fB1\.2\.3\-beta\.4\fP would be allowed, but +\fB1\.2\.4\-beta\.2\fP would not, because it is a prerelease of a +different \fB[major, minor, patch]\fP tuple\. +.IP \(bu 2 +\fB^0\.0\.3\-beta\fP := \fB>=0\.0\.3\-beta <0\.0\.4\fP Note that prereleases in the +\fB0\.0\.3\fP version \fIonly\fR will be allowed, if they are greater than or +equal to \fBbeta\fP\|\. So, \fB0\.0\.3\-pr\.2\fP would be allowed\. + +.RE +.P +When parsing caret ranges, a missing \fBpatch\fP value desugars to the +number \fB0\fP, but will allow flexibility within that value, even if the +major and minor versions are both \fB0\fP\|\. +.RS 0 +.IP \(bu 2 +\fB^1\.2\.x\fP := \fB>=1\.2\.0 <2\.0\.0\fP +.IP \(bu 2 +\fB^0\.0\.x\fP := \fB>=0\.0\.0 <0\.1\.0\fP +.IP \(bu 2 +\fB^0\.0\fP := \fB>=0\.0\.0 <0\.1\.0\fP + +.RE +.P +A missing \fBminor\fP and \fBpatch\fP values will desugar to zero, but also +allow flexibility within those values, even if the major version is +zero\. +.RS 0 +.IP \(bu 2 +\fB^1\.x\fP := \fB>=1\.0\.0 <2\.0\.0\fP +.IP \(bu 2 +\fB^0\.x\fP := \fB>=0\.0\.0 <1\.0\.0\fP + +.RE +.SS Range Grammar +.P +Putting all this together, here is a Backus\-Naur grammar for ranges, +for the benefit of parser authors: +.P +.RS 2 +.nf +range\-set ::= range ( logical\-or range ) * +logical\-or ::= ( ' ' ) * '||' ( ' ' ) * +range ::= hyphen | simple ( ' ' simple ) * | '' +hyphen ::= partial ' \- ' partial +simple ::= primitive | partial | tilde | caret +primitive ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial +partial ::= xr ( '\.' xr ( '\.' xr qualifier ? )? )? +xr ::= 'x' | 'X' | '*' | nr +nr ::= '0' | ['1'\-'9'] ( ['0'\-'9'] ) * +tilde ::= '~' partial +caret ::= '^' partial +qualifier ::= ( '\-' pre )? ( '+' build )? +pre ::= parts +build ::= parts +parts ::= part ( '\.' part ) * +part ::= nr | [\-0\-9A\-Za\-z]+ +.fi +.RE +.SH Functions +.P +All methods and classes take a final \fBoptions\fP object argument\. All +options in this object are \fBfalse\fP by default\. The options supported +are: +.RS 0 +.IP \(bu 2 +\fBloose\fP Be more forgiving about not\-quite\-valid semver strings\. +(Any resulting output will always be 100% strict compliant, of +course\.) For backwards compatibility reasons, if the \fBoptions\fP +argument is a boolean value instead of an object, it is interpreted +to be the \fBloose\fP param\. +.IP \(bu 2 +\fBincludePrerelease\fP Set to suppress the default +behavior \fIhttps://github\.com/npm/node\-semver#prerelease\-tags\fR of +excluding prerelease tagged versions from ranges unless they are +explicitly opted into\. + +.RE +.P +Strict\-mode Comparators and Ranges will be strict about the SemVer +strings that they parse\. +.RS 0 +.IP \(bu 2 +\fBvalid(v)\fP: Return the parsed version, or null if it's not valid\. +.IP \(bu 2 +\fBinc(v, release)\fP: Return the version incremented by the release +type (\fBmajor\fP, \fBpremajor\fP, \fBminor\fP, \fBpreminor\fP, \fBpatch\fP, +\fBprepatch\fP, or \fBprerelease\fP), or null if it's not valid +.RS 0 +.IP \(bu 2 +\fBpremajor\fP in one call will bump the version up to the next major +version and down to a prerelease of that major version\. +\fBpreminor\fP, and \fBprepatch\fP work the same way\. +.IP \(bu 2 +If called from a non\-prerelease version, the \fBprerelease\fP will work the +same as \fBprepatch\fP\|\. It increments the patch version, then makes a +prerelease\. If the input version is already a prerelease it simply +increments it\. + +.RE +.IP \(bu 2 +\fBprerelease(v)\fP: Returns an array of prerelease components, or null +if none exist\. Example: \fBprerelease('1\.2\.3\-alpha\.1') \-> ['alpha', 1]\fP +.IP \(bu 2 +\fBmajor(v)\fP: Return the major version number\. +.IP \(bu 2 +\fBminor(v)\fP: Return the minor version number\. +.IP \(bu 2 +\fBpatch(v)\fP: Return the patch version number\. +.IP \(bu 2 +\fBintersects(r1, r2, loose)\fP: Return true if the two supplied ranges +or comparators intersect\. + +.RE +.SS Comparison +.RS 0 +.IP \(bu 2 +\fBgt(v1, v2)\fP: \fBv1 > v2\fP +.IP \(bu 2 +\fBgte(v1, v2)\fP: \fBv1 >= v2\fP +.IP \(bu 2 +\fBlt(v1, v2)\fP: \fBv1 < v2\fP +.IP \(bu 2 +\fBlte(v1, v2)\fP: \fBv1 <= v2\fP +.IP \(bu 2 +\fBeq(v1, v2)\fP: \fBv1 == v2\fP This is true if they're logically equivalent, +even if they're not the exact same string\. You already know how to +compare strings\. +.IP \(bu 2 +\fBneq(v1, v2)\fP: \fBv1 != v2\fP The opposite of \fBeq\fP\|\. +.IP \(bu 2 +\fBcmp(v1, comparator, v2)\fP: Pass in a comparison string, and it'll call +the corresponding function above\. \fB"==="\fP and \fB"!=="\fP do simple +string comparison, but are included for completeness\. Throws if an +invalid comparison string is provided\. +.IP \(bu 2 +\fBcompare(v1, v2)\fP: Return \fB0\fP if \fBv1 == v2\fP, or \fB1\fP if \fBv1\fP is greater, or \fB\-1\fP if +\fBv2\fP is greater\. Sorts in ascending order if passed to \fBArray\.sort()\fP\|\. +.IP \(bu 2 +\fBrcompare(v1, v2)\fP: The reverse of compare\. Sorts an array of versions +in descending order when passed to \fBArray\.sort()\fP\|\. +.IP \(bu 2 +\fBdiff(v1, v2)\fP: Returns difference between two versions by the release type +(\fBmajor\fP, \fBpremajor\fP, \fBminor\fP, \fBpreminor\fP, \fBpatch\fP, \fBprepatch\fP, or \fBprerelease\fP), +or null if the versions are the same\. + +.RE +.SS Comparators +.RS 0 +.IP \(bu 2 +\fBintersects(comparator)\fP: Return true if the comparators intersect + +.RE +.SS Ranges +.RS 0 +.IP \(bu 2 +\fBvalidRange(range)\fP: Return the valid range or null if it's not valid +.IP \(bu 2 +\fBsatisfies(version, range)\fP: Return true if the version satisfies the +range\. +.IP \(bu 2 +\fBmaxSatisfying(versions, range)\fP: Return the highest version in the list +that satisfies the range, or \fBnull\fP if none of them do\. +.IP \(bu 2 +\fBminSatisfying(versions, range)\fP: Return the lowest version in the list +that satisfies the range, or \fBnull\fP if none of them do\. +.IP \(bu 2 +\fBgtr(version, range)\fP: Return \fBtrue\fP if version is greater than all the +versions possible in the range\. +.IP \(bu 2 +\fBltr(version, range)\fP: Return \fBtrue\fP if version is less than all the +versions possible in the range\. +.IP \(bu 2 +\fBoutside(version, range, hilo)\fP: Return true if the version is outside +the bounds of the range in either the high or low direction\. The +\fBhilo\fP argument must be either the string \fB\|'>'\fP or \fB\|'<'\fP\|\. (This is +the function called by \fBgtr\fP and \fBltr\fP\|\.) +.IP \(bu 2 +\fBintersects(range)\fP: Return true if any of the ranges comparators intersect + +.RE +.P +Note that, since ranges may be non\-contiguous, a version might not be +greater than a range, less than a range, \fIor\fR satisfy a range! For +example, the range \fB1\.2 <1\.2\.9 || >2\.0\.0\fP would have a hole from \fB1\.2\.9\fP +until \fB2\.0\.0\fP, so the version \fB1\.2\.10\fP would not be greater than the +range (because \fB2\.0\.1\fP satisfies, which is higher), nor less than the +range (since \fB1\.2\.8\fP satisfies, which is lower), and it also does not +satisfy the range\. +.P +If you want to know if a version satisfies or does not satisfy a +range, use the \fBsatisfies(version, range)\fP function\. +.SS Coercion +.RS 0 +.IP \(bu 2 +\fBcoerce(version)\fP: Coerces a string to semver if possible + +.RE +.P +This aims to provide a very forgiving translation of a non\-semver +string to semver\. It looks for the first digit in a string, and +consumes all remaining characters which satisfy at least a partial semver +(e\.g\., \fB1\fP, \fB1\.2\fP, \fB1\.2\.3\fP) up to the max permitted length (256 characters)\. +Longer versions are simply truncated (\fB4\.6\.3\.9\.2\-alpha2\fP becomes \fB4\.6\.3\fP)\. +All surrounding text is simply ignored (\fBv3\.4 replaces v3\.3\.1\fP becomes \fB3\.4\.0\fP)\. +Only text which lacks digits will fail coercion (\fBversion one\fP is not valid)\. +The maximum length for any semver component considered for coercion is 16 characters; +longer components will be ignored (\fB10000000000000000\.4\.7\.4\fP becomes \fB4\.7\.4\fP)\. +The maximum value for any semver component is \fBInteger\.MAX_SAFE_INTEGER || (2**53 \- 1)\fP; +higher value components are invalid (\fB9999999999999999\.4\.7\.4\fP is likely invalid)\. + |