diff options
Diffstat (limited to 'deps/npm/man/man7/semver.7')
| -rw-r--r-- | deps/npm/man/man7/semver.7 | 510 |
1 files changed, 0 insertions, 510 deletions
diff --git a/deps/npm/man/man7/semver.7 b/deps/npm/man/man7/semver.7 deleted file mode 100644 index 0a08bf9abb3..00000000000 --- a/deps/npm/man/man7/semver.7 +++ /dev/null @@ -1,510 +0,0 @@ -.TH "SEMVER" "7" "December 2020" "" "" -.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\.minVersion('>=1\.0\.0') // '1\.0\.0' -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 https://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 -https://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\. -.P -Note that this behavior can be suppressed (treating all prerelease -versions as if they were normal versions, for the purpose of range -matching) by setting the \fBincludePrerelease\fP flag on the options -object to any -functions \fIhttps://github\.com/npm/node\-semver#functions\fR that do -range matching\. -.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 -.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\. -.IP \(bu 2 -\fBparse(v)\fP: Attempt to parse a string as a semantic version, returning either -a \fBSemVer\fP object or \fBnull\fP\|\. - -.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 -\fBminVersion(range)\fP: Return the lowest version that can possibly match -the given range\. -.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 \fBNumber\.MAX_SAFE_INTEGER || (2**53 \- 1)\fP; higher value -components are invalid (\fB9999999999999999\.4\.7\.4\fP is likely invalid)\. |