| <!doctype html> |
| <html> |
| <title>semver</title> |
| <meta http-equiv="content-type" value="text/html;utf-8"> |
| <link rel="stylesheet" type="text/css" href="../../static/style.css"> |
| |
| <body> |
| <div id="wrapper"> |
| <h1><a href="../misc/semver.html">semver</a></h1> <p>The semantic versioner for npm</p> |
| |
| <h2 id="Usage">Usage</h2> |
| |
| <pre><code>$ npm install 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</code></pre> |
| |
| <p>As a command-line utility:</p> |
| |
| <pre><code>$ semver -h |
| |
| Usage: semver <version> [<version> [...]] [-r <range> | -i <inc> | -d <dec>] |
| Test if version(s) satisfy the supplied range(s), and sort them. |
| |
| Multiple versions or ranges may be supplied, unless increment |
| or decrement options are specified. In that case, only a single |
| version may be used, and it is incremented by the specified level |
| |
| Program exits successfully if any valid version satisfies |
| all supplied ranges, and prints all satisfying versions. |
| |
| If no versions are valid, or ranges are not satisfied, |
| 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 v2.0.0 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>The following range styles are supported:</p> |
| |
| <ul><li><code>1.2.3</code> A specific version. When nothing else will do. Note that |
| build metadata is still ignored, so <code>1.2.3+build2012</code> will satisfy |
| this range.</li><li><code>>1.2.3</code> Greater than a specific version.</li><li><code><1.2.3</code> Less than a specific version. If there is no prerelease |
| tag on the version range, then no prerelease version will be allowed |
| either, even though these are technically "less than".</li><li><code>>=1.2.3</code> Greater than or equal to. Note that prerelease versions |
| are NOT equal to their "normal" equivalents, so <code>1.2.3-beta</code> will |
| not satisfy this range, but <code>2.3.0-beta</code> will.</li><li><code><=1.2.3</code> Less than or equal to. In this case, prerelease versions |
| ARE allowed, so <code>1.2.3-beta</code> would satisfy.</li><li><code>1.2.3 - 2.3.4</code> := <code>>=1.2.3 <=2.3.4</code></li><li><code>~1.2.3</code> := <code>>=1.2.3-0 <1.3.0-0</code> "Reasonably close to 1.2.3". When |
| using tilde operators, prerelease versions are supported as well, |
| but a prerelease of the next significant digit will NOT be |
| satisfactory, so <code>1.3.0-beta</code> will not satisfy <code>~1.2.3</code>.</li><li><code>~1.2</code> := <code>>=1.2.0-0 <1.3.0-0</code> "Any version starting with 1.2"</li><li><code>1.2.x</code> := <code>>=1.2.0-0 <1.3.0-0</code> "Any version starting with 1.2"</li><li><code>~1</code> := <code>>=1.0.0-0 <2.0.0-0</code> "Any version starting with 1"</li><li><code>1.x</code> := <code>>=1.0.0-0 <2.0.0-0</code> "Any version starting with 1"</li></ul> |
| |
| <p>Ranges can be joined with either a space (which implies "and") or a |
| <code>||</code> (which implies "or").</p> |
| |
| <h2 id="Functions">Functions</h2> |
| |
| <p>All methods and classes take a final <code>loose</code> boolean argument that, if |
| true, will be more forgiving about not-quite-valid semver strings. |
| The resulting output will always be 100% strict, of course.</p> |
| |
| <p>Strict-mode Comparators and Ranges will be strict about the SemVer |
| strings that they parse.</p> |
| |
| <ul><li>valid(v): Return the parsed version, or null if it's not valid.</li><li>inc(v, release): Return the version incremented by the release type |
| (major, minor, patch, or prerelease), or null if it's not valid.</li></ul> |
| |
| <h3 id="Comparison">Comparison</h3> |
| |
| <ul><li>gt(v1, v2): <code>v1 > v2</code></li><li>gte(v1, v2): <code>v1 >= v2</code></li><li>lt(v1, v2): <code>v1 < v2</code></li><li>lte(v1, v2): <code>v1 <= v2</code></li><li>eq(v1, v2): <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>neq(v1, v2): <code>v1 != v2</code> The opposite of eq.</li><li>cmp(v1, comparator, v2): 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>compare(v1, v2): Return 0 if v1 == v2, or 1 if v1 is greater, or -1 if |
| v2 is greater. Sorts in ascending order if passed to Array.sort().</li><li>rcompare(v1, v2): The reverse of compare. Sorts an array of versions |
| in descending order when passed to Array.sort().</li></ul> |
| |
| <h3 id="Ranges">Ranges</h3> |
| |
| <ul><li>validRange(range): Return the valid range or null if it's not valid</li><li>satisfies(version, range): Return true if the version satisfies the |
| range.</li><li>maxSatisfying(versions, range): Return the highest version in the list |
| that satisfies the range, or null if none of them do.</li></ul> |
| </div> |
| <p id="footer">semver — npm@1.3.21</p> |
| <script> |
| ;(function () { |
| var wrapper = document.getElementById("wrapper") |
| var els = Array.prototype.slice.call(wrapper.getElementsByTagName("*"), 0) |
| .filter(function (el) { |
| return el.parentNode === wrapper |
| && el.tagName.match(/H[1-6]/) |
| && el.id |
| }) |
| var l = 2 |
| , toc = document.createElement("ul") |
| toc.innerHTML = els.map(function (el) { |
| var i = el.tagName.charAt(1) |
| , out = "" |
| while (i > l) { |
| out += "<ul>" |
| l ++ |
| } |
| while (i < l) { |
| out += "</ul>" |
| l -- |
| } |
| out += "<li><a href='#" + el.id + "'>" + |
| ( el.innerText || el.text || el.innerHTML) |
| + "</a>" |
| return out |
| }).join("\n") |
| toc.id = "toc" |
| document.body.appendChild(toc) |
| })() |
| </script> |