@@ -41,53 +41,170 @@ A leading `"="` or `"v"` character is stripped off and ignored.
4141
4242## Ranges
4343
44- The following range styles are supported:
45-
46- * ` 1.2.3 ` A specific version. When nothing else will do. Must be a full
47- version number, with major, minor, and patch versions specified.
48- Note that build metadata is still ignored, so ` 1.2.3+build2012 ` will
49- satisfy this range.
50- * ` >1.2.3 ` Greater than a specific version.
51- * ` <1.2.3 ` Less than a specific version. If there is no prerelease
52- tag on the version range, then no prerelease version will be allowed
53- either, even though these are technically "less than".
54- * ` >=1.2.3 ` Greater than or equal to. Note that prerelease versions
55- are NOT equal to their "normal" equivalents, so ` 1.2.3-beta ` will
56- not satisfy this range, but ` 2.3.0-beta ` will.
57- * ` <=1.2.3 ` Less than or equal to. In this case, prerelease versions
58- ARE allowed, so ` 1.2.3-beta ` would satisfy.
44+ A ` version range ` is a set of ` comparators ` which specify versions
45+ that satisfy the range.
46+
47+ A ` comparator ` is composed of an ` operator ` and a ` version ` . The set
48+ of primitive ` operators ` is:
49+
50+ * ` < ` Less than
51+ * ` <= ` Less than or equal to
52+ * ` > ` Greater than
53+ * ` >= ` Greater than or equal to
54+ * ` = ` Equal. If no operator is specified, then equality is assumed,
55+ so this operator is optional, but MAY be included.
56+
57+ For example, the comparator ` >=1.2.7 ` would match the versions
58+ ` 1.2.7 ` , ` 1.2.8 ` , ` 2.5.3 ` , and ` 1.3.9 ` , but not the versions ` 1.2.6 `
59+ or ` 1.1.0 ` .
60+
61+ Comparators can be joined by whitespace to form a ` comparator set ` ,
62+ which is satisfied by the ** intersection** of all of the comparators
63+ it includes.
64+
65+ A range is composed of one or more comparator sets, joined by ` || ` . A
66+ version matches a range if and only if every comparator in at least
67+ one of the ` || ` -separated comparator sets is satisfied by the version.
68+
69+ For example, the range ` >=1.2.7 <1.3.0 ` would match the versions
70+ ` 1.2.7 ` , ` 1.2.8 ` , and ` 1.2.99 ` , but not the versions ` 1.2.6 ` , ` 1.3.0 ` ,
71+ or ` 1.1.0 ` .
72+
73+ The range ` 1.2.7 || >=1.2.9 <2.0.0 ` would match the versions ` 1.2.7 ` ,
74+ ` 1.2.9 ` , and ` 1.4.6 ` , but not the versions ` 1.2.8 ` or ` 2.0.0 ` .
75+
76+ ### Prerelease Tags
77+
78+ If a version has a prerelease tag (for example, ` 1.2.3-alpha.3 ` ) then
79+ it will only be allowed to satisfy comparator sets if at least one
80+ comparator with the same ` [major, minor, patch] ` tuple also has a
81+ prerelease tag.
82+
83+ For example, the range ` >1.2.3-alpha.3 ` would be allowed to match the
84+ version ` 1.2.3-alpha.7 ` , but it would * not* be satisfied by
85+ ` 3.4.5-alpha.9 ` , even though ` 3.4.5-alpha.9 ` is technically "greater
86+ than" ` 1.2.3-alpha.3 ` according to the SemVer sort rules. The version
87+ range only accepts prerelease tags on the ` 1.2.3 ` version. The
88+ version ` 3.4.5 ` * would* satisfy the range, because it does not have a
89+ prerelease flag, and ` 3.4.5 ` is greater than ` 1.2.3-alpha.7 ` .
90+
91+ The purpose for this behavior is twofold. First, prerelease versions
92+ frequently are updated very quickly, and contain many breaking changes
93+ that are (by the author's design) not yet fit for public consumption.
94+ Therefore, by default, they are excluded from range matching
95+ semantics.
96+
97+ Second, a user who has opted into using a prerelease version has
98+ clearly indicated the intent to use * that specific* set of
99+ alpha/beta/rc versions. By including a prerelease tag in the range,
100+ the user is indicating that they are aware of the risk. However, it
101+ is still not appropriate to assume that they have opted into taking a
102+ similar risk on the * next* set of prerelease versions.
103+
104+ ### Advanced Range Syntax
105+
106+ Advanced range syntax desugars to primitive comparators in
107+ deterministic ways.
108+
109+ Advanced ranges may be combined in the same way as primitive
110+ comparators using white space or ` || ` .
111+
112+ #### Hyphen Ranges ` X.Y.Z - A.B.C `
113+
114+ Specifies an inclusive set.
115+
59116* ` 1.2.3 - 2.3.4 ` := ` >=1.2.3 <=2.3.4 `
60- * ` ~1.2.3 ` := ` >=1.2.3-0 <1.3.0-0 ` "Reasonably close to ` 1.2.3 ` ". When
61- using tilde operators, prerelease versions are supported as well,
62- but a prerelease of the next significant digit will NOT be
63- satisfactory, so ` 1.3.0-beta ` will not satisfy ` ~1.2.3 ` .
64- * ` ^1.2.3 ` := ` >=1.2.3-0 <2.0.0-0 ` "Compatible with ` 1.2.3 ` ". When
65- using caret operators, anything from the specified version (including
66- prerelease) will be supported up to, but not including, the next
67- major version (or its prereleases). ` 1.5.1 ` will satisfy ` ^1.2.3 ` ,
68- while ` 1.2.2 ` and ` 2.0.0-beta ` will not.
69- * ` ^0.1.3 ` := ` 0.1.3 ` "Compatible with ` 0.1.3 ` ". ` 0.x.x ` versions are
70- special: since the semver spec specifies that ` 0.x.x ` versions make
71- no stability guarantees, only the version specified is considered
72- valid.
73- * ` ^0.0.2 ` := ` 0.0.2 ` "Only the version ` 0.0.2 ` is considered compatible"
74- * ` ~1.2 ` := ` >=1.2.0-0 <1.3.0-0 ` "Any version starting with ` 1.2 ` "
75- * ` ^1.2 ` := ` >=1.2.0-0 <2.0.0-0 ` "Any version compatible with ` 1.2 ` "
76- * ` 1.2.x ` := ` >=1.2.0-0 <1.3.0-0 ` "Any version starting with ` 1.2 ` "
77- * ` 1.2.* ` Same as ` 1.2.x ` .
78- * ` 1.2 ` Same as ` 1.2.x ` .
79- * ` ~1 ` := ` >=1.0.0-0 <2.0.0-0 ` "Any version starting with ` 1 ` "
80- * ` ^1 ` := ` >=1.0.0-0 <2.0.0-0 ` "Any version compatible with ` 1 ` "
81- * ` 1.x ` := ` >=1.0.0-0 <2.0.0-0 ` "Any version starting with ` 1 ` "
82- * ` 1.* ` Same as ` 1.x ` .
83- * ` 1 ` Same as ` 1.x ` .
84- * ` * ` Any version whatsoever.
85- * ` x ` Same as ` * ` .
86- * ` "" ` (just an empty string) Same as ` * ` .
87-
88-
89- Ranges can be joined with either a space (which implies "and") or a
90- ` || ` (which implies "or").
117+
118+ If a partial version is provided as the first version in the inclusive
119+ range, then the missing pieces are replaced with zeroes.
120+
121+ * ` 1.2 - 2.3.4 ` := ` >=1.2.0 <=2.3.4 `
122+
123+ If a partial version is provided as the second version in the
124+ inclusive range, then all versions that start with the supplied parts
125+ of the tuple are accepted, but nothing that would be greater than the
126+ provided tuple parts.
127+
128+ * ` 1.2.3 - 2.3 ` := ` >=1.2.3 <2.4.0 `
129+ * ` 1.2.3 - 2 ` := ` >=1.2.3 <3.0.0 `
130+
131+ #### X-Ranges ` 1.2.x ` ` 1.X ` ` 1.2.* ` ` * `
132+
133+ Any of ` X ` , ` x ` , or ` * ` may be used to "stand in" for one of the
134+ numeric values in the ` [major, minor, patch] ` tuple.
135+
136+ * ` * ` := ` >=0.0.0 ` (Any version satisfies)
137+ * ` 1.x ` := ` >=1.0.0 <2.0.0 ` (Matching major version)
138+ * ` 1.2.x ` := ` >=1.2.0 <1.3.0 ` (Matching major and minor versions)
139+
140+ A partial version range is treated as an X-Range, so the special
141+ character is in fact optional.
142+
143+ * `` (empty string) := ` * ` := ` >=0.0.0 `
144+ * ` 1 ` := ` 1.x.x ` := ` >=1.0.0 <2.0.0 `
145+ * ` 1.2 ` := ` 1.2.x ` := ` >=1.2.0 <1.3.0 `
146+
147+ #### Tilde Ranges ` ~1.2.3 ` ` ~1.2 ` ` ~1 `
148+
149+ Allows patch-level changes if a minor version is specified on the
150+ comparator. Allows minor-level changes if not.
151+
152+ * ` ~1.2.3 ` := ` >=1.2.3 <1.(2+1).0 ` := ` >=1.2.3 <1.3.0 `
153+ * ` ~1.2 ` := ` >=1.2.0 <1.(2+1).0 ` := ` >=1.2.0 <1.3.0 ` (Same as ` 1.2.x ` )
154+ * ` ~1 ` := ` >=1.0.0 <(1+1).0.0 ` := ` >=1.0.0 <2.0.0 ` (Same as ` 1.x ` )
155+ * ` ~0.2.3 ` := ` >=0.2.3 <0.(2+1).0 ` := ` >=0.2.3 <0.3.0 `
156+ * ` ~0.2 ` := ` >=0.2.0 <0.(2+1).0 ` := ` >=0.2.0 <0.3.0 ` (Same as ` 0.2.x ` )
157+ * ` ~0 ` := ` >=0.0.0 <(0+1).0.0 ` := ` >=0.0.0 <1.0.0 ` (Same as ` 0.x ` )
158+ * ` ~1.2.3-beta.2 ` := ` >=1.2.3-beta.2 <1.3.0 ` Note that prereleases in
159+ the ` 1.2.3 ` version will be allowed, if they are greater than or
160+ equal to ` beta.2 ` . So, ` 1.2.3-beta.4 ` would be allowed, but
161+ ` 1.2.4-beta.2 ` would not, because it is a prerelease of a
162+ different ` [major, minor, patch] ` tuple.
163+
164+ Note: this is the same as the ` ~> ` operator in rubygems.
165+
166+ #### Caret Ranges ` ^1.2.3 ` ` ^0.2.5 ` ` ^0.0.4 `
167+
168+ Allows changes that do not modify the left-most non-zero digit in the
169+ ` [major, minor, patch] ` tuple. In other words, this allows patch and
170+ minor updates for versions ` 1.0.0 ` and above, patch updates for
171+ versions ` 0.X >=0.1.0 ` , and * no* updates for versions ` 0.0.X ` .
172+
173+ Many authors treat a ` 0.x ` version as if the ` x ` were the major
174+ "breaking-change" indicator.
175+
176+ Caret ranges are ideal when an author may make breaking changes
177+ between ` 0.2.4 ` and ` 0.3.0 ` releases, which is a common practice.
178+ However, it presumes that there will * not* be breaking changes between
179+ ` 0.2.4 ` and ` 0.2.5 ` . It allows for changes that are presumed to be
180+ additive (but non-breaking), according to commonly observed practices.
181+
182+ * ` ^1.2.3 ` := ` >=1.2.3 <2.0.0 `
183+ * ` ^0.2.3 ` := ` >=0.2.3 <0.3.0 `
184+ * ` ^0.0.3 ` := ` >=0.0.3 <0.0.4 `
185+ * ` ^1.2.3-beta.2 ` := ` >=1.2.3-beta.2 <2.0.0 ` Note that prereleases in
186+ the ` 1.2.3 ` version will be allowed, if they are greater than or
187+ equal to ` beta.2 ` . So, ` 1.2.3-beta.4 ` would be allowed, but
188+ ` 1.2.4-beta.2 ` would not, because it is a prerelease of a
189+ different ` [major, minor, patch] ` tuple.
190+ * ` ^0.0.3-beta ` := ` >=0.0.3-beta <0.0.4 ` Note that prereleases in the
191+ ` 0.0.3 ` version * only* will be allowed, if they are greater than or
192+ equal to ` beta ` . So, ` 0.0.3-pr.2 ` would be allowed.
193+
194+ When parsing caret ranges, a missing ` patch ` value desugars to the
195+ number ` 0 ` , but will allow flexibility within that value, even if the
196+ major and minor versions are both ` 0 ` .
197+
198+ * ` ^1.2.x ` := ` >=1.2.0 <2.0.0 `
199+ * ` ^0.0.x ` := ` >=0.0.0 <0.1.0 `
200+ * ` ^0.0 ` := ` >=0.0.0 <0.1.0 `
201+
202+ A missing ` minor ` and ` patch ` values will desugar to zero, but also
203+ allow flexibility within those values, even if the major version is
204+ zero.
205+
206+ * ` ^1.x ` := ` >=1.0.0 <2.0.0 `
207+ * ` ^0.x ` := ` >=0.0.0 <1.0.0 `
91208
92209## Functions
93210
0 commit comments