deps/npm/man/man7/semver.7

   1 .\" Generated with Ronnjs 0.3.8
   2 .\" http://github.com/kapouer/ronnjs/
   3 .
   4 .TH "SEMVER" "7" "November 2013" "" ""
   5 .
   6 .SH "NAME"
   7 \fBsemver\fR \-\- The semantic versioner for npm
   8 .
   9 .SH "Usage"
  10 .
  11 .nf
  12 $ npm install semver
  13 semver\.valid(\'1\.2\.3\') // \'1\.2\.3\'
  14 semver\.valid(\'a\.b\.c\') // null
  15 semver\.clean(\'  =v1\.2\.3   \') // \'1\.2\.3\'
  16 semver\.satisfies(\'1\.2\.3\', \'1\.x || >=2\.5\.0 || 5\.0\.0 \- 7\.2\.3\') // true
  17 semver\.gt(\'1\.2\.3\', \'9\.8\.7\') // false
  18 semver\.lt(\'1\.2\.3\', \'9\.8\.7\') // true
  19 .
  20 .fi
  21 .
  22 .P
  23 As a command\-line utility:
  24 .
  25 .IP "" 4
  26 .
  27 .nf
  28 $ semver \-h
  29 Usage: semver <version> [<version> [\.\.\.]] [\-r <range> | \-i <inc> | \-d <dec>]
  30 Test if version(s) satisfy the supplied range(s), and sort them\.
  31 Multiple versions or ranges may be supplied, unless increment
  32 or decrement options are specified\.  In that case, only a single
  33 version may be used, and it is incremented by the specified level
  34 Program exits successfully if any valid version satisfies
  35 all supplied ranges, and prints all satisfying versions\.
  36 If no versions are valid, or ranges are not satisfied,
  37 then exits failure\.
  38 Versions are printed in ascending order, so supplying
  39 multiple versions to the utility will just sort them\.
  40 .
  41 .fi
  42 .
  43 .IP "" 0
  44 .
  45 .SH "Versions"
  46 A "version" is described by the v2\.0\.0 specification found at \fIhttp://semver\.org/\fR\|\.
  47 .
  48 .P
  49 A leading \fB"="\fR or \fB"v"\fR character is stripped off and ignored\.
  50 .
  51 .SH "Ranges"
  52 The following range styles are supported:
  53 .
  54 .IP "\(bu" 4
  55 \fB1\.2\.3\fR A specific version\.  When nothing else will do\.  Note that
  56 build metadata is still ignored, so \fB1\.2\.3+build2012\fR will satisfy
  57 this range\.
  58 .
  59 .IP "\(bu" 4
  60 \fB>1\.2\.3\fR Greater than a specific version\.
  61 .
  62 .IP "\(bu" 4
  63 \fB<1\.2\.3\fR Less than a specific version\.  If there is no prerelease
  64 tag on the version range, then no prerelease version will be allowed
  65 either, even though these are technically "less than"\.
  66 .
  67 .IP "\(bu" 4
  68 \fB>=1\.2\.3\fR Greater than or equal to\.  Note that prerelease versions
  69 are NOT equal to their "normal" equivalents, so \fB1\.2\.3\-beta\fR will
  70 not satisfy this range, but \fB2\.3\.0\-beta\fR will\.
  71 .
  72 .IP "\(bu" 4
  73 \fB<=1\.2\.3\fR Less than or equal to\.  In this case, prerelease versions
  74 ARE allowed, so \fB1\.2\.3\-beta\fR would satisfy\.
  75 .
  76 .IP "\(bu" 4
  77 \fB1\.2\.3 \- 2\.3\.4\fR := \fB>=1\.2\.3 <=2\.3\.4\fR
  78 .
  79 .IP "\(bu" 4
  80 \fB~1\.2\.3\fR := \fB>=1\.2\.3\-0 <1\.3\.0\-0\fR  "Reasonably close to 1\.2\.3"\.  When
  81 using tilde operators, prerelease versions are supported as well,
  82 but a prerelease of the next significant digit will NOT be
  83 satisfactory, so \fB1\.3\.0\-beta\fR will not satisfy \fB~1\.2\.3\fR\|\.
  84 .
  85 .IP "\(bu" 4
  86 \fB~1\.2\fR := \fB>=1\.2\.0\-0 <1\.3\.0\-0\fR "Any version starting with 1\.2"
  87 .
  88 .IP "\(bu" 4
  89 \fB1\.2\.x\fR := \fB>=1\.2\.0\-0 <1\.3\.0\-0\fR "Any version starting with 1\.2"
  90 .
  91 .IP "\(bu" 4
  92 \fB~1\fR := \fB>=1\.0\.0\-0 <2\.0\.0\-0\fR "Any version starting with 1"
  93 .
  94 .IP "\(bu" 4
  95 \fB1\.x\fR := \fB>=1\.0\.0\-0 <2\.0\.0\-0\fR "Any version starting with 1"
  96 .
  97 .IP "" 0
  98 .
  99 .P
 100 Ranges can be joined with either a space (which implies "and") or a \fB||\fR (which implies "or")\.
 101 .
 102 .SH "Functions"
 103 All methods and classes take a final \fBloose\fR boolean argument that, if
 104 true, will be more forgiving about not\-quite\-valid semver strings\.
 105 The resulting output will always be 100% strict, of course\.
 106 .
 107 .P
 108 Strict\-mode Comparators and Ranges will be strict about the SemVer
 109 strings that they parse\.
 110 .
 111 .IP "\(bu" 4
 112 valid(v): Return the parsed version, or null if it\'s not valid\.
 113 .
 114 .IP "\(bu" 4
 115 inc(v, release): Return the version incremented by the release type
 116 (major, minor, patch, or prerelease), or null if it\'s not valid\.
 117 .
 118 .IP "" 0
 119 .
 120 .SS "Comparison"
 121 .
 122 .IP "\(bu" 4
 123 gt(v1, v2): \fBv1 > v2\fR
 124 .
 125 .IP "\(bu" 4
 126 gte(v1, v2): \fBv1 >= v2\fR
 127 .
 128 .IP "\(bu" 4
 129 lt(v1, v2): \fBv1 < v2\fR
 130 .
 131 .IP "\(bu" 4
 132 lte(v1, v2): \fBv1 <= v2\fR
 133 .
 134 .IP "\(bu" 4
 135 eq(v1, v2): \fBv1 == v2\fR This is true if they\'re logically equivalent,
 136 even if they\'re not the exact same string\.  You already know how to
 137 compare strings\.
 138 .
 139 .IP "\(bu" 4
 140 neq(v1, v2): \fBv1 != v2\fR The opposite of eq\.
 141 .
 142 .IP "\(bu" 4
 143 cmp(v1, comparator, v2): Pass in a comparison string, and it\'ll call
 144 the corresponding function above\.  \fB"==="\fR and \fB"!=="\fR do simple
 145 string comparison, but are included for completeness\.  Throws if an
 146 invalid comparison string is provided\.
 147 .
 148 .IP "\(bu" 4
 149 compare(v1, v2): Return 0 if v1 == v2, or 1 if v1 is greater, or \-1 if
 150 v2 is greater\.  Sorts in ascending order if passed to Array\.sort()\.
 151 .
 152 .IP "\(bu" 4
 153 rcompare(v1, v2): The reverse of compare\.  Sorts an array of versions
 154 in descending order when passed to Array\.sort()\.
 155 .
 156 .IP "" 0
 157 .
 158 .SS "Ranges"
 159 .
 160 .IP "\(bu" 4
 161 validRange(range): Return the valid range or null if it\'s not valid
 162 .
 163 .IP "\(bu" 4
 164 satisfies(version, range): Return true if the version satisfies the
 165 range\.
 166 .
 167 .IP "\(bu" 4
 168 maxSatisfying(versions, range): Return the highest version in the list
 169 that satisfies the range, or null if none of them do\.
 170 .
 171 .IP "" 0
 172