diff options
Diffstat (limited to 'deps/node/deps/npm/html/doc/misc/semver.html')
| -rw-r--r-- | deps/node/deps/npm/html/doc/misc/semver.html | 365 |
1 files changed, 0 insertions, 365 deletions
diff --git a/deps/node/deps/npm/html/doc/misc/semver.html b/deps/node/deps/npm/html/doc/misc/semver.html deleted file mode 100644 index 28db44aa..00000000 --- a/deps/node/deps/npm/html/doc/misc/semver.html +++ /dev/null @@ -1,365 +0,0 @@ -<!doctype html> -<html> - <title>semver</title> - <meta charset="utf-8"> - <link rel="stylesheet" type="text/css" href="../../static/style.css"> - <link rel="canonical" href="https://www.npmjs.org/doc/misc/semver.html"> - <script async=true src="../../static/toc.js"></script> - - <body> - <div id="wrapper"> - -<h1><a href="../misc/semver.html">semver</a></h1> <p>The semantic versioner for npm</p> -<h2 id="install">Install</h2> -<pre><code class="language-bash">npm install --save semver</code></pre> -<h2 id="usage">Usage</h2> -<p>As a node module:</p> -<pre><code class="language-js">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'</code></pre> -<p>As a command-line utility:</p> -<pre><code>$ 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.</code></pre><h2 id="versions">Versions</h2> -<p>A "version" is described by the <code>v2.0.0</code> specification found at -<a href="http://semver.org/">http://semver.org/</a>.</p> -<p>A leading <code>"="</code> or <code>"v"</code> character is stripped off and ignored.</p> -<h2 id="ranges">Ranges</h2> -<p>A <code>version range</code> is a set of <code>comparators</code> which specify versions -that satisfy the range.</p> -<p>A <code>comparator</code> is composed of an <code>operator</code> and a <code>version</code>. The set -of primitive <code>operators</code> is:</p> -<ul> -<li><code><</code> Less than</li> -<li><code><=</code> Less than or equal to</li> -<li><code>></code> Greater than</li> -<li><code>>=</code> Greater than or equal to</li> -<li><code>=</code> Equal. If no operator is specified, then equality is assumed, -so this operator is optional, but MAY be included.</li> -</ul> -<p>For example, the comparator <code>>=1.2.7</code> would match the versions -<code>1.2.7</code>, <code>1.2.8</code>, <code>2.5.3</code>, and <code>1.3.9</code>, but not the versions <code>1.2.6</code> -or <code>1.1.0</code>.</p> -<p>Comparators can be joined by whitespace to form a <code>comparator set</code>, -which is satisfied by the <strong>intersection</strong> of all of the comparators -it includes.</p> -<p>A range is composed of one or more comparator sets, joined by <code>||</code>. A -version matches a range if and only if every comparator in at least -one of the <code>||</code>-separated comparator sets is satisfied by the version.</p> -<p>For example, the range <code>>=1.2.7 <1.3.0</code> would match the versions -<code>1.2.7</code>, <code>1.2.8</code>, and <code>1.2.99</code>, but not the versions <code>1.2.6</code>, <code>1.3.0</code>, -or <code>1.1.0</code>.</p> -<p>The range <code>1.2.7 || >=1.2.9 <2.0.0</code> would match the versions <code>1.2.7</code>, -<code>1.2.9</code>, and <code>1.4.6</code>, but not the versions <code>1.2.8</code> or <code>2.0.0</code>.</p> -<h3 id="prerelease-tags">Prerelease Tags</h3> -<p>If a version has a prerelease tag (for example, <code>1.2.3-alpha.3</code>) then -it will only be allowed to satisfy comparator sets if at least one -comparator with the same <code>[major, minor, patch]</code> tuple also has a -prerelease tag.</p> -<p>For example, the range <code>>1.2.3-alpha.3</code> would be allowed to match the -version <code>1.2.3-alpha.7</code>, but it would <em>not</em> be satisfied by -<code>3.4.5-alpha.9</code>, even though <code>3.4.5-alpha.9</code> is technically "greater -than" <code>1.2.3-alpha.3</code> according to the SemVer sort rules. The version -range only accepts prerelease tags on the <code>1.2.3</code> version. The -version <code>3.4.5</code> <em>would</em> satisfy the range, because it does not have a -prerelease flag, and <code>3.4.5</code> is greater than <code>1.2.3-alpha.7</code>.</p> -<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> -<p>Second, a user who has opted into using a prerelease version has -clearly indicated the intent to use <em>that specific</em> 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 <em>next</em> set of prerelease versions.</p> -<h4 id="prerelease-identifiers">Prerelease Identifiers</h4> -<p>The method <code>.inc</code> takes an additional <code>identifier</code> string argument that -will append the value of the string as a prerelease identifier:</p> -<pre><code class="language-javascript">semver.inc('1.2.3', 'prerelease', 'beta') -// '1.2.4-beta.0'</code></pre> -<p>command-line example:</p> -<pre><code class="language-bash">$ semver 1.2.3 -i prerelease --preid beta -1.2.4-beta.0</code></pre> -<p>Which then can be used to increment further:</p> -<pre><code class="language-bash">$ semver 1.2.4-beta.0 -i prerelease -1.2.4-beta.1</code></pre> -<h3 id="advanced-range-syntax">Advanced Range Syntax</h3> -<p>Advanced range syntax desugars to primitive comparators in -deterministic ways.</p> -<p>Advanced ranges may be combined in the same way as primitive -comparators using white space or <code>||</code>.</p> -<h4 id="hyphen-ranges-xyz---abc">Hyphen Ranges <code>X.Y.Z - A.B.C</code></h4> -<p>Specifies an inclusive set.</p> -<ul> -<li><code>1.2.3 - 2.3.4</code> := <code>>=1.2.3 <=2.3.4</code></li> -</ul> -<p>If a partial version is provided as the first version in the inclusive -range, then the missing pieces are replaced with zeroes.</p> -<ul> -<li><code>1.2 - 2.3.4</code> := <code>>=1.2.0 <=2.3.4</code></li> -</ul> -<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.</p> -<ul> -<li><code>1.2.3 - 2.3</code> := <code>>=1.2.3 <2.4.0</code></li> -<li><code>1.2.3 - 2</code> := <code>>=1.2.3 <3.0.0</code></li> -</ul> -<h4 id="x-ranges-12x-1x-12-">X-Ranges <code>1.2.x</code> <code>1.X</code> <code>1.2.*</code> <code>*</code></h4> -<p>Any of <code>X</code>, <code>x</code>, or <code>*</code> may be used to "stand in" for one of the -numeric values in the <code>[major, minor, patch]</code> tuple.</p> -<ul> -<li><code>*</code> := <code>>=0.0.0</code> (Any version satisfies)</li> -<li><code>1.x</code> := <code>>=1.0.0 <2.0.0</code> (Matching major version)</li> -<li><code>1.2.x</code> := <code>>=1.2.0 <1.3.0</code> (Matching major and minor versions)</li> -</ul> -<p>A partial version range is treated as an X-Range, so the special -character is in fact optional.</p> -<ul> -<li><code>""</code> (empty string) := <code>*</code> := <code>>=0.0.0</code></li> -<li><code>1</code> := <code>1.x.x</code> := <code>>=1.0.0 <2.0.0</code></li> -<li><code>1.2</code> := <code>1.2.x</code> := <code>>=1.2.0 <1.3.0</code></li> -</ul> -<h4 id="tilde-ranges-123-12-1">Tilde Ranges <code>~1.2.3</code> <code>~1.2</code> <code>~1</code></h4> -<p>Allows patch-level changes if a minor version is specified on the -comparator. Allows minor-level changes if not.</p> -<ul> -<li><code>~1.2.3</code> := <code>>=1.2.3 <1.(2+1).0</code> := <code>>=1.2.3 <1.3.0</code></li> -<li><code>~1.2</code> := <code>>=1.2.0 <1.(2+1).0</code> := <code>>=1.2.0 <1.3.0</code> (Same as <code>1.2.x</code>)</li> -<li><code>~1</code> := <code>>=1.0.0 <(1+1).0.0</code> := <code>>=1.0.0 <2.0.0</code> (Same as <code>1.x</code>)</li> -<li><code>~0.2.3</code> := <code>>=0.2.3 <0.(2+1).0</code> := <code>>=0.2.3 <0.3.0</code></li> -<li><code>~0.2</code> := <code>>=0.2.0 <0.(2+1).0</code> := <code>>=0.2.0 <0.3.0</code> (Same as <code>0.2.x</code>)</li> -<li><code>~0</code> := <code>>=0.0.0 <(0+1).0.0</code> := <code>>=0.0.0 <1.0.0</code> (Same as <code>0.x</code>)</li> -<li><code>~1.2.3-beta.2</code> := <code>>=1.2.3-beta.2 <1.3.0</code> Note that prereleases in -the <code>1.2.3</code> version will be allowed, if they are greater than or -equal to <code>beta.2</code>. So, <code>1.2.3-beta.4</code> would be allowed, but -<code>1.2.4-beta.2</code> would not, because it is a prerelease of a -different <code>[major, minor, patch]</code> tuple.</li> -</ul> -<h4 id="caret-ranges-123-025-004">Caret Ranges <code>^1.2.3</code> <code>^0.2.5</code> <code>^0.0.4</code></h4> -<p>Allows changes that do not modify the left-most non-zero digit in the -<code>[major, minor, patch]</code> tuple. In other words, this allows patch and -minor updates for versions <code>1.0.0</code> and above, patch updates for -versions <code>0.X >=0.1.0</code>, and <em>no</em> updates for versions <code>0.0.X</code>.</p> -<p>Many authors treat a <code>0.x</code> version as if the <code>x</code> were the major -"breaking-change" indicator.</p> -<p>Caret ranges are ideal when an author may make breaking changes -between <code>0.2.4</code> and <code>0.3.0</code> releases, which is a common practice. -However, it presumes that there will <em>not</em> be breaking changes between -<code>0.2.4</code> and <code>0.2.5</code>. It allows for changes that are presumed to be -additive (but non-breaking), according to commonly observed practices.</p> -<ul> -<li><code>^1.2.3</code> := <code>>=1.2.3 <2.0.0</code></li> -<li><code>^0.2.3</code> := <code>>=0.2.3 <0.3.0</code></li> -<li><code>^0.0.3</code> := <code>>=0.0.3 <0.0.4</code></li> -<li><code>^1.2.3-beta.2</code> := <code>>=1.2.3-beta.2 <2.0.0</code> Note that prereleases in -the <code>1.2.3</code> version will be allowed, if they are greater than or -equal to <code>beta.2</code>. So, <code>1.2.3-beta.4</code> would be allowed, but -<code>1.2.4-beta.2</code> would not, because it is a prerelease of a -different <code>[major, minor, patch]</code> tuple.</li> -<li><code>^0.0.3-beta</code> := <code>>=0.0.3-beta <0.0.4</code> Note that prereleases in the -<code>0.0.3</code> version <em>only</em> will be allowed, if they are greater than or -equal to <code>beta</code>. So, <code>0.0.3-pr.2</code> would be allowed.</li> -</ul> -<p>When parsing caret ranges, a missing <code>patch</code> value desugars to the -number <code>0</code>, but will allow flexibility within that value, even if the -major and minor versions are both <code>0</code>.</p> -<ul> -<li><code>^1.2.x</code> := <code>>=1.2.0 <2.0.0</code></li> -<li><code>^0.0.x</code> := <code>>=0.0.0 <0.1.0</code></li> -<li><code>^0.0</code> := <code>>=0.0.0 <0.1.0</code></li> -</ul> -<p>A missing <code>minor</code> and <code>patch</code> values will desugar to zero, but also -allow flexibility within those values, even if the major version is -zero.</p> -<ul> -<li><code>^1.x</code> := <code>>=1.0.0 <2.0.0</code></li> -<li><code>^0.x</code> := <code>>=0.0.0 <1.0.0</code></li> -</ul> -<h3 id="range-grammar">Range Grammar</h3> -<p>Putting all this together, here is a Backus-Naur grammar for ranges, -for the benefit of parser authors:</p> -<pre><code class="language-bnf">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]+</code></pre> -<h2 id="functions">Functions</h2> -<p>All methods and classes take a final <code>options</code> object argument. All -options in this object are <code>false</code> by default. The options supported -are:</p> -<ul> -<li><code>loose</code> 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 <code>options</code> -argument is a boolean value instead of an object, it is interpreted -to be the <code>loose</code> param.</li> -<li><code>includePrerelease</code> Set to suppress the <a href="https://github.com/npm/node-semver#prerelease-tags">default -behavior</a> of -excluding prerelease tagged versions from ranges unless they are -explicitly opted into.</li> -</ul> -<p>Strict-mode Comparators and Ranges will be strict about the SemVer -strings that they parse.</p> -<ul> -<li><code>valid(v)</code>: Return the parsed version, or null if it's not valid.</li> -<li><code>inc(v, release)</code>: Return the version incremented by the release -type (<code>major</code>, <code>premajor</code>, <code>minor</code>, <code>preminor</code>, <code>patch</code>, -<code>prepatch</code>, or <code>prerelease</code>), or null if it's not valid<ul> -<li><code>premajor</code> in one call will bump the version up to the next major -version and down to a prerelease of that major version. -<code>preminor</code>, and <code>prepatch</code> work the same way.</li> -<li>If called from a non-prerelease version, the <code>prerelease</code> will work the -same as <code>prepatch</code>. It increments the patch version, then makes a -prerelease. If the input version is already a prerelease it simply -increments it.</li> -</ul> -</li> -<li><code>prerelease(v)</code>: Returns an array of prerelease components, or null -if none exist. Example: <code>prerelease('1.2.3-alpha.1') -> ['alpha', 1]</code></li> -<li><code>major(v)</code>: Return the major version number.</li> -<li><code>minor(v)</code>: Return the minor version number.</li> -<li><code>patch(v)</code>: Return the patch version number.</li> -<li><code>intersects(r1, r2, loose)</code>: Return true if the two supplied ranges -or comparators intersect.</li> -</ul> -<h3 id="comparison">Comparison</h3> -<ul> -<li><code>gt(v1, v2)</code>: <code>v1 > v2</code></li> -<li><code>gte(v1, v2)</code>: <code>v1 >= v2</code></li> -<li><code>lt(v1, v2)</code>: <code>v1 < v2</code></li> -<li><code>lte(v1, v2)</code>: <code>v1 <= v2</code></li> -<li><code>eq(v1, v2)</code>: <code>v1 == v2</code> This is true if they're logically equivalent, -even if they're not the exact same string. You already know how to -compare strings.</li> -<li><code>neq(v1, v2)</code>: <code>v1 != v2</code> The opposite of <code>eq</code>.</li> -<li><code>cmp(v1, comparator, v2)</code>: Pass in a comparison string, and it'll call -the corresponding function above. <code>"==="</code> and <code>"!=="</code> do simple -string comparison, but are included for completeness. Throws if an -invalid comparison string is provided.</li> -<li><code>compare(v1, v2)</code>: Return <code>0</code> if <code>v1 == v2</code>, or <code>1</code> if <code>v1</code> is greater, or <code>-1</code> if -<code>v2</code> is greater. Sorts in ascending order if passed to <code>Array.sort()</code>.</li> -<li><code>rcompare(v1, v2)</code>: The reverse of compare. Sorts an array of versions -in descending order when passed to <code>Array.sort()</code>.</li> -<li><code>diff(v1, v2)</code>: Returns difference between two versions by the release type -(<code>major</code>, <code>premajor</code>, <code>minor</code>, <code>preminor</code>, <code>patch</code>, <code>prepatch</code>, or <code>prerelease</code>), -or null if the versions are the same.</li> -</ul> -<h3 id="comparators">Comparators</h3> -<ul> -<li><code>intersects(comparator)</code>: Return true if the comparators intersect</li> -</ul> -<h3 id="ranges-1">Ranges</h3> -<ul> -<li><code>validRange(range)</code>: Return the valid range or null if it's not valid</li> -<li><code>satisfies(version, range)</code>: Return true if the version satisfies the -range.</li> -<li><code>maxSatisfying(versions, range)</code>: Return the highest version in the list -that satisfies the range, or <code>null</code> if none of them do.</li> -<li><code>minSatisfying(versions, range)</code>: Return the lowest version in the list -that satisfies the range, or <code>null</code> if none of them do.</li> -<li><code>gtr(version, range)</code>: Return <code>true</code> if version is greater than all the -versions possible in the range.</li> -<li><code>ltr(version, range)</code>: Return <code>true</code> if version is less than all the -versions possible in the range.</li> -<li><code>outside(version, range, hilo)</code>: Return true if the version is outside -the bounds of the range in either the high or low direction. The -<code>hilo</code> argument must be either the string <code>'>'</code> or <code>'<'</code>. (This is -the function called by <code>gtr</code> and <code>ltr</code>.)</li> -<li><code>intersects(range)</code>: Return true if any of the ranges comparators intersect</li> -</ul> -<p>Note that, since ranges may be non-contiguous, a version might not be -greater than a range, less than a range, <em>or</em> satisfy a range! For -example, the range <code>1.2 <1.2.9 || >2.0.0</code> would have a hole from <code>1.2.9</code> -until <code>2.0.0</code>, so the version <code>1.2.10</code> would not be greater than the -range (because <code>2.0.1</code> satisfies, which is higher), nor less than the -range (since <code>1.2.8</code> satisfies, which is lower), and it also does not -satisfy the range.</p> -<p>If you want to know if a version satisfies or does not satisfy a -range, use the <code>satisfies(version, range)</code> function.</p> -<h3 id="coercion">Coercion</h3> -<ul> -<li><code>coerce(version)</code>: Coerces a string to semver if possible</li> -</ul> -<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., <code>1</code>, <code>1.2</code>, <code>1.2.3</code>) up to the max permitted length (256 characters). -Longer versions are simply truncated (<code>4.6.3.9.2-alpha2</code> becomes <code>4.6.3</code>). -All surrounding text is simply ignored (<code>v3.4 replaces v3.3.1</code> becomes <code>3.4.0</code>). -Only text which lacks digits will fail coercion (<code>version one</code> is not valid). -The maximum length for any semver component considered for coercion is 16 characters; -longer components will be ignored (<code>10000000000000000.4.7.4</code> becomes <code>4.7.4</code>). -The maximum value for any semver component is <code>Integer.MAX_SAFE_INTEGER || (2**53 - 1)</code>; -higher value components are invalid (<code>9999999999999999.4.7.4</code> is likely invalid).</p> - -</div> - -<table border=0 cellspacing=0 cellpadding=0 id=npmlogo> -<tr><td style="width:180px;height:10px;background:rgb(237,127,127)" colspan=18> </td></tr> -<tr><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td colspan=6 style="width:60px;height:10px;background:#fff"> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td></tr> -<tr><td colspan=2 style="width:20px;height:30px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=4 colspan=2> </td><td style="width:10px;height:20px;background:rgb(237,127,127)" rowspan=2> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=3 colspan=2> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td></tr> -<tr><td style="width:10px;height:10px;background:#fff" rowspan=2> </td></tr> -<tr><td style="width:10px;height:10px;background:#fff"> </td></tr> -<tr><td style="width:60px;height:10px;background:rgb(237,127,127)" colspan=6> </td><td colspan=10 style="width:10px;height:10px;background:rgb(237,127,127)"> </td></tr> -<tr><td colspan=5 style="width:50px;height:10px;background:#fff"> </td><td style="width:40px;height:10px;background:rgb(237,127,127)" colspan=4> </td><td style="width:90px;height:10px;background:#fff" colspan=9> </td></tr> -</table> -<p id="footer">semver — npm@6.7.0</p> - |