Commit | Line | Data |
---|---|---|
cb5772bb RGS |
1 | =head1 NAME |
2 | ||
3 | version - Perl extension for Version Objects | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | use version; | |
8 | $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1 | |
43eaf59d | 9 | print $version; # v12.2.1 |
cb5772bb | 10 | print $version->numify; # 12.002001 |
43eaf59d | 11 | if ( $version gt "12.2" ) # true |
cb5772bb RGS |
12 | |
13 | $alphaver = version->new("1.02_03"); # must be quoted! | |
43eaf59d | 14 | print $alphaver; # 1.02_0300 |
cb5772bb RGS |
15 | print $alphaver->is_alpha(); # true |
16 | ||
43eaf59d | 17 | $ver = qv("1.2.0"); # v1.2.0 |
cb5772bb RGS |
18 | |
19 | $perlver = version->new(5.005_03); # must not be quoted! | |
20 | print $perlver; # 5.005030 | |
21 | ||
22 | =head1 DESCRIPTION | |
23 | ||
317f7c8a | 24 | Overloaded version objects for all modern versions of Perl. This module |
219bf418 RGS |
25 | implements all of the features of version objects which are part |
26 | of Perl 5.10.0. All previous releases (i.e. before 0.74) are deprecated | |
27 | and should not be used due to incompatible API changes. If you 'use | |
28 | version' in your code, you are strongly urged to set a minimum, e.g. | |
29 | ||
30 | use version 0.74; # to remain compatible with Perl v5.10.0 | |
43eaf59d SP |
31 | |
32 | =head2 BEST PRACTICES | |
33 | ||
34 | If you intend for your module to be used by different releases of Perl, | |
35 | and/or for your $VERSION scalar to mean what you think it means, there | |
36 | are a few simple rules to follow: | |
37 | ||
38 | =over 4 | |
39 | ||
40 | =item * Be consistent | |
41 | ||
42 | Whichever of the two types of version objects that you choose to employ, | |
43 | you should stick to either L<Numeric Versions> or L<Extended Versions> | |
44 | and not mix them together. While this is I<possible>, it is very | |
45 | confusing to the average user. | |
46 | ||
47 | If you intend to use L<Extended Versions>, you are strongly encouraged | |
48 | to use the L<qv()> operator with a quoted term, e.g.: | |
49 | ||
50 | use version; our $VERSION = qv("1.2.3"); | |
51 | ||
52 | on a single line as above. | |
53 | ||
54 | At the very least, decide on which of the several ways to initialize | |
55 | your version objects you prefer and stick with it. It is also best to | |
56 | be explicit about what value you intend to assign your version object | |
57 | and to not rely on hidden behavior of the parser. | |
58 | ||
59 | =item * Be careful | |
60 | ||
61 | If you are using Module::Build or ExtUtils::MakeMaker, so that you can | |
34ba6322 SP |
62 | release your module to CPAN, you have to recognize that neither of those |
63 | programs completely handles version objects natively (yet). If you use | |
64 | version objects with Module::Build, you should add an explicit dependency | |
65 | to the release of version.pm in your Build.PL: | |
66 | ||
67 | my $builder = Module::Build->new( | |
68 | ... | |
69 | requires => { | |
70 | ... , | |
71 | 'version' => 0.50, | |
72 | ..., | |
73 | }, | |
74 | ... | |
75 | ); | |
76 | ||
77 | and it should Just Work(TM). Module::Build will [hopefully soon] | |
78 | include full support for version objects; there are no current plans | |
79 | to patch ExtUtils::MakeMaker to support version objects. | |
cb5772bb | 80 | |
317f7c8a RGS |
81 | =back |
82 | ||
83 | =head2 Using modules that use version.pm | |
84 | ||
85 | As much as possible, the version.pm module remains compatible with all | |
86 | current code. However, if your module is using a module that has defined | |
87 | C<$VERSION> using the version class, there are a couple of things to be | |
88 | aware of. For purposes of discussion, we will assume that we have the | |
89 | following module installed: | |
90 | ||
91 | package Example; | |
92 | use version; $VERSION = qv('1.2.2'); | |
93 | ...module code here... | |
94 | 1; | |
95 | ||
96 | =over 4 | |
97 | ||
98 | =item Numeric versions always work | |
99 | ||
100 | Code of the form: | |
101 | ||
102 | use Example 1.002003; | |
103 | ||
104 | will always work correctly. The C<use> will perform an automatic | |
105 | C<$VERSION> comparison using the floating point number given as the first | |
106 | term after the module name (e.g. above 1.002.003). In this case, the | |
107 | installed module is too old for the requested line, so you would see an | |
108 | error like: | |
109 | ||
110 | Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)... | |
111 | ||
112 | =item Extended version work sometimes | |
113 | ||
114 | With Perl >= 5.6.2, you can also use a line like this: | |
115 | ||
116 | use Example 1.2.3; | |
117 | ||
118 | and it will again work (i.e. give the error message as above), even with | |
119 | releases of Perl which do not normally support v-strings (see L<What about | |
120 | v-strings> below). This has to do with that fact that C<use> only checks | |
121 | to see if the second term I<looks like a number> and passes that to the | |
122 | replacement L<UNIVERSAL::VERSION>. This is not true in Perl 5.005_04, | |
123 | however, so you are B<strongly encouraged> to always use a numeric version | |
124 | in your code, even for those versions of Perl which support the extended | |
125 | version. | |
126 | ||
127 | =back | |
128 | ||
cb5772bb RGS |
129 | =head2 What IS a version |
130 | ||
131 | For the purposes of this module, a version "number" is a sequence of | |
43eaf59d SP |
132 | positive integer values separated by one or more decimal points and |
133 | optionally a single underscore. This corresponds to what Perl itself | |
134 | uses for a version, as well as extending the "version as number" that | |
135 | is discussed in the various editions of the Camel book. | |
cb5772bb | 136 | |
43eaf59d | 137 | There are actually two distinct kinds of version objects: |
cb5772bb RGS |
138 | |
139 | =over 4 | |
140 | ||
141 | =item * Numeric Versions | |
142 | ||
143 | Any initial parameter which "looks like a number", see L<Numeric | |
43eaf59d | 144 | Versions>. This also covers versions with a single decimal point and |
cb5772bb RGS |
145 | a single embedded underscore, see L<Numeric Alpha Versions>, even though |
146 | these must be quoted to preserve the underscore formatting. | |
147 | ||
7de739db | 148 | =item * Extended Versions |
cb5772bb RGS |
149 | |
150 | Any initial parameter which contains more than one decimal point | |
43eaf59d SP |
151 | and an optional embedded underscore, see L<Extended Versions>. This |
152 | is what is commonly used in most open source software as the "external" | |
153 | version (the one used as part of the tag or tarfile name). The use | |
154 | of the exported L<qv()> function also produces this kind of version | |
155 | object. | |
cb5772bb RGS |
156 | |
157 | =back | |
158 | ||
159 | Both of these methods will produce similar version objects, in that | |
160 | the default stringification will yield the version L<Normal Form> only | |
161 | if required: | |
162 | ||
163 | $v = version->new(1.002); # 1.002, but compares like 1.2.0 | |
164 | $v = version->new(1.002003); # 1.002003 | |
f34c6aaf | 165 | $v2 = version->new("1.2.3"); # v1.2.3 |
cb5772bb RGS |
166 | |
167 | In specific, version numbers initialized as L<Numeric Versions> will | |
8cb289bd RGS |
168 | stringify as they were originally created (i.e. the same string that was |
169 | passed to C<new()>. Version numbers initialized as L<Extended Versions> | |
cb5772bb RGS |
170 | will be stringified as L<Normal Form>. |
171 | ||
cb5772bb RGS |
172 | =head2 Numeric Versions |
173 | ||
174 | These correspond to historical versions of Perl itself prior to 5.6.0, | |
175 | as well as all other modules which follow the Camel rules for the | |
176 | $VERSION scalar. A numeric version is initialized with what looks like | |
177 | a floating point number. Leading zeros B<are> significant and trailing | |
178 | zeros are implied so that a minimum of three places is maintained | |
179 | between subversions. What this means is that any subversion (digits | |
180 | to the right of the decimal place) that contains less than three digits | |
181 | will have trailing zeros added to make up the difference, but only for | |
182 | purposes of comparison with other version objects. For example: | |
183 | ||
43eaf59d | 184 | # Prints Equivalent to |
8cb289bd RGS |
185 | $v = version->new( 1.2); # 1.2 v1.200.0 |
186 | $v = version->new( 1.02); # 1.02 v1.20.0 | |
43eaf59d | 187 | $v = version->new( 1.002); # 1.002 v1.2.0 |
8cb289bd RGS |
188 | $v = version->new( 1.0023); # 1.0023 v1.2.300 |
189 | $v = version->new( 1.00203); # 1.00203 v1.2.30 | |
43eaf59d | 190 | $v = version->new( 1.002003); # 1.002003 v1.2.3 |
cb5772bb | 191 | |
43eaf59d SP |
192 | All of the preceding examples are true whether or not the input value is |
193 | quoted. The important feature is that the input value contains only a | |
194 | single decimal. See also L<Alpha Versions> for how to handle | |
cb5772bb | 195 | |
43eaf59d SP |
196 | IMPORTANT NOTE: As shown above, if your numeric version contains more |
197 | than 3 significant digits after the decimal place, it will be split on | |
198 | each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need | |
199 | to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation. | |
200 | Any trailing zeros are ignored for mathematical comparison purposes. | |
cb5772bb | 201 | |
7de739db | 202 | =head2 Extended Versions |
cb5772bb RGS |
203 | |
204 | These are the newest form of versions, and correspond to Perl's own | |
205 | version style beginning with 5.6.0. Starting with Perl 5.10.0, | |
206 | and most likely Perl 6, this is likely to be the preferred form. This | |
43eaf59d SP |
207 | method normally requires that the input parameter be quoted, although |
208 | Perl's after 5.8.1 can use v-strings as a special form of quoting, but | |
209 | this is highly discouraged. | |
cb5772bb | 210 | |
43eaf59d SP |
211 | Unlike L<Numeric Versions>, Extended Versions have more than |
212 | a single decimal point, e.g.: | |
cb5772bb | 213 | |
43eaf59d SP |
214 | # Prints |
215 | $v = version->new( "v1.200"); # v1.200.0 | |
216 | $v = version->new("v1.20.0"); # v1.20.0 | |
f34c6aaf | 217 | $v = qv("v1.2.3"); # v1.2.3 |
43eaf59d SP |
218 | $v = qv("1.2.3"); # v1.2.3 |
219 | $v = qv("1.20"); # v1.20.0 | |
cb5772bb | 220 | |
7de739db | 221 | In general, Extended Versions permit the greatest amount of freedom |
cb5772bb RGS |
222 | to specify a version, whereas Numeric Versions enforce a certain |
223 | uniformity. See also L<New Operator> for an additional method of | |
224 | initializing version objects. | |
225 | ||
43eaf59d SP |
226 | Just like L<Numeric Versions>, Extended Versions can be used as |
227 | L<Alpha Versions>. | |
228 | ||
cb5772bb RGS |
229 | =head2 Numeric Alpha Versions |
230 | ||
231 | The one time that a numeric version must be quoted is when a alpha form is | |
43eaf59d | 232 | used with an otherwise numeric version (i.e. a single decimal point). This |
cb5772bb RGS |
233 | is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha |
234 | versions for automatic updating purposes. Since some developers have used | |
235 | only two significant decimal places for their non-alpha releases, the | |
236 | version object will automatically take that into account if the initializer | |
237 | is quoted. For example Module::Example was released to CPAN with the | |
238 | following sequence of $VERSION's: | |
239 | ||
240 | # $VERSION Stringified | |
8cb289bd RGS |
241 | 0.01 0.01 |
242 | 0.02 0.02 | |
243 | 0.02_01 0.02_01 | |
244 | 0.02_02 0.02_02 | |
245 | 0.03 0.03 | |
cb5772bb RGS |
246 | etc. |
247 | ||
8cb289bd RGS |
248 | The stringified form of numeric versions will always be the same string |
249 | that was used to initialize the version object. | |
cb5772bb RGS |
250 | |
251 | =head2 Object Methods | |
252 | ||
253 | Overloading has been used with version objects to provide a natural | |
254 | interface for their use. All mathematical operations are forbidden, | |
f34c6aaf JP |
255 | since they don't make any sense for base version objects. Consequently, |
256 | there is no overloaded numification available. If you want to use a | |
257 | version object in a numeric context for some reason, see the L<numify> | |
258 | object method. | |
cb5772bb RGS |
259 | |
260 | =over 4 | |
261 | ||
262 | =item * New Operator | |
263 | ||
264 | Like all OO interfaces, the new() operator is used to initialize | |
265 | version objects. One way to increment versions when programming is to | |
266 | use the CVS variable $Revision, which is automatically incremented by | |
267 | CVS every time the file is committed to the repository. | |
268 | ||
269 | In order to facilitate this feature, the following | |
270 | code can be employed: | |
271 | ||
272 | $VERSION = version->new(qw$Revision: 2.7 $); | |
273 | ||
274 | and the version object will be created as if the following code | |
275 | were used: | |
276 | ||
277 | $VERSION = version->new("v2.7"); | |
278 | ||
279 | In other words, the version will be automatically parsed out of the | |
280 | string, and it will be quoted to preserve the meaning CVS normally | |
281 | carries for versions. The CVS $Revision$ increments differently from | |
282 | numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if | |
7de739db | 283 | it were a L<Extended Version>. |
cb5772bb RGS |
284 | |
285 | A new version object can be created as a copy of an existing version | |
286 | object, either as a class method: | |
287 | ||
288 | $v1 = version->new(12.3); | |
289 | $v2 = version->new($v1); | |
290 | ||
291 | or as an object method: | |
292 | ||
293 | $v1 = version->new(12.3); | |
f34c6aaf JP |
294 | $v2 = $v1->new(12.3); |
295 | ||
296 | and in each case, $v1 and $v2 will be identical. NOTE: if you create | |
297 | a new object using an existing object like this: | |
298 | ||
cb5772bb RGS |
299 | $v2 = $v1->new(); |
300 | ||
f34c6aaf JP |
301 | the new object B<will not> be a clone of the existing object. In the |
302 | example case, $v2 will be an empty object of the same type as $v1. | |
cb5772bb RGS |
303 | |
304 | =back | |
305 | ||
306 | =over 4 | |
307 | ||
308 | =item * qv() | |
309 | ||
310 | An alternate way to create a new version object is through the exported | |
311 | qv() sub. This is not strictly like other q? operators (like qq, qw), | |
312 | in that the only delimiters supported are parentheses (or spaces). It is | |
313 | the best way to initialize a short version without triggering the floating | |
314 | point interpretation. For example: | |
315 | ||
316 | $v1 = qv(1.2); # 1.2.0 | |
317 | $v2 = qv("1.2"); # also 1.2.0 | |
318 | ||
43eaf59d SP |
319 | As you can see, either a bare number or a quoted string can usually |
320 | be used interchangably, except in the case of a trailing zero, which | |
321 | must be quoted to be converted properly. For this reason, it is strongly | |
322 | recommended that all initializers to qv() be quoted strings instead of | |
323 | bare numbers. | |
cb5772bb | 324 | |
92dcf8ce JP |
325 | To prevent the C<qv()> function from being exported to the caller's namespace, |
326 | either use version with a null parameter: | |
327 | ||
328 | use version (); | |
329 | ||
330 | or just require version, like this: | |
331 | ||
332 | require version; | |
333 | ||
334 | Both methods will prevent the import() method from firing and exporting the | |
335 | C<qv()> sub. This is true of subclasses of version as well, see | |
336 | L<SUBCLASSING> for details. | |
337 | ||
cb5772bb RGS |
338 | =back |
339 | ||
340 | For the subsequent examples, the following three objects will be used: | |
341 | ||
342 | $ver = version->new("1.2.3.4"); # see "Quoting" below | |
343 | $alpha = version->new("1.2.3_4"); # see "Alpha versions" below | |
43eaf59d | 344 | $nver = version->new(1.002); # see "Numeric Versions" above |
cb5772bb RGS |
345 | |
346 | =over 4 | |
347 | ||
348 | =item * Normal Form | |
349 | ||
350 | For any version object which is initialized with multiple decimal | |
351 | places (either quoted or if possible v-string), or initialized using | |
352 | the L<qv()> operator, the stringified representation is returned in | |
353 | a normalized or reduced form (no extraneous zeros), and with a leading 'v': | |
354 | ||
43eaf59d | 355 | print $ver->normal; # prints as v1.2.3.4 |
cb5772bb RGS |
356 | print $ver->stringify; # ditto |
357 | print $ver; # ditto | |
358 | print $nver->normal; # prints as v1.2.0 | |
359 | print $nver->stringify; # prints as 1.002, see "Stringification" | |
360 | ||
361 | In order to preserve the meaning of the processed version, the | |
362 | normalized representation will always contain at least three sub terms. | |
363 | In other words, the following is guaranteed to always be true: | |
364 | ||
365 | my $newver = version->new($ver->stringify); | |
366 | if ($newver eq $ver ) # always true | |
367 | {...} | |
368 | ||
369 | =back | |
370 | ||
371 | =over 4 | |
372 | ||
373 | =item * Numification | |
374 | ||
375 | Although all mathematical operations on version objects are forbidden | |
43eaf59d SP |
376 | by default, it is possible to retrieve a number which corresponds |
377 | to the version object through the use of the $obj->numify | |
cb5772bb RGS |
378 | method. For formatting purposes, when displaying a number which |
379 | corresponds a version object, all sub versions are assumed to have | |
380 | three decimal places. So for example: | |
381 | ||
43eaf59d | 382 | print $ver->numify; # prints 1.002003004 |
cb5772bb RGS |
383 | print $nver->numify; # prints 1.002 |
384 | ||
385 | Unlike the stringification operator, there is never any need to append | |
386 | trailing zeros to preserve the correct version value. | |
387 | ||
388 | =back | |
389 | ||
390 | =over 4 | |
391 | ||
392 | =item * Stringification | |
393 | ||
8cb289bd RGS |
394 | The default stringification for version objects returns exactly the same |
395 | string as was used to create it, whether you used C<new()> or C<qv()>, | |
396 | with one exception. The sole exception is if the object was created using | |
397 | C<qv()> and the initializer did not have two decimal places or a leading | |
398 | 'v' (both optional), then the stringified form will have a leading 'v' | |
399 | prepended, in order to support round-trip processing. | |
cb5772bb | 400 | |
8cb289bd | 401 | For example: |
cb5772bb | 402 | |
8cb289bd RGS |
403 | Initialized as Stringifies to |
404 | ============== ============== | |
405 | version->new("1.2") 1.2 | |
406 | version->new("v1.2") v1.2 | |
407 | qv("1.2.3") 1.2.3 | |
408 | qv("v1.3.5") v1.3.5 | |
409 | qv("1.2") v1.2 ### exceptional case | |
cb5772bb | 410 | |
8cb289bd RGS |
411 | See also L<UNIVERSAL::VERSION>, as this also returns the stringified form |
412 | when used as a class method. | |
cb5772bb | 413 | |
219bf418 RGS |
414 | IMPORTANT NOTE: There is one exceptional cases shown in the above table |
415 | where the "initializer" is not stringwise equivalent to the stringified | |
416 | representation. If you use the C<qv()> operator on a version without a | |
417 | leading 'v' B<and> with only a single decimal place, the stringified output | |
418 | will have a leading 'v', to preserve the sense. See the L<qv()> operator | |
419 | for more details. | |
420 | ||
421 | IMPORTANT NOTE 2: Attempting to bypass the normal stringification rules by | |
422 | manually applying L<numify()> and L<normal()> will sometimes yield | |
423 | surprising results: | |
424 | ||
425 | print version->new(version->new("v1.0")->numify)->normal; # v1.0.0 | |
426 | ||
427 | The reason for this is that the L<numify()> operator will turn "v1.0" | |
428 | into the equivalent string "1.000000". Forcing the outer version object | |
429 | to L<normal()> form will display the mathematically equivalent "v1.0.0". | |
430 | ||
431 | As the example in L<new()> shows, you can always create a copy of an | |
432 | existing version object with the same value by the very compact: | |
433 | ||
434 | $v2 = $v1->new($v1); | |
435 | ||
436 | and be assured that both C<$v1> and C<$v2> will be completely equivalent, | |
437 | down to the same internal representation as well as stringification. | |
438 | ||
cb5772bb RGS |
439 | =back |
440 | ||
441 | =over 4 | |
442 | ||
443 | =item * Comparison operators | |
444 | ||
43eaf59d SP |
445 | Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between |
446 | terms (upgrading to a version object automatically). Perl automatically | |
cb5772bb RGS |
447 | generates all of the other comparison operators based on those two. |
448 | In addition to the obvious equalities listed below, appending a single | |
449 | trailing 0 term does not change the value of a version for comparison | |
450 | purposes. In other words "v1.2" and "1.2.0" will compare as identical. | |
451 | ||
452 | For example, the following relations hold: | |
453 | ||
43eaf59d SP |
454 | As Number As String Truth Value |
455 | ------------- ---------------- ----------- | |
456 | $ver > 1.0 $ver gt "1.0" true | |
457 | $ver < 2.5 $ver lt true | |
458 | $ver != 1.3 $ver ne "1.3" true | |
459 | $ver == 1.2 $ver eq "1.2" false | |
460 | $ver == 1.2.3.4 $ver eq "1.2.3.4" see discussion below | |
cb5772bb RGS |
461 | |
462 | It is probably best to chose either the numeric notation or the string | |
463 | notation and stick with it, to reduce confusion. Perl6 version objects | |
43eaf59d | 464 | B<may> only support numeric comparisons. See also L<Quoting>. |
cb5772bb | 465 | |
43eaf59d | 466 | WARNING: Comparing version with unequal numbers of decimal points (whether |
cb5772bb RGS |
467 | explicitly or implicitly initialized), may yield unexpected results at |
468 | first glance. For example, the following inequalities hold: | |
469 | ||
470 | version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0 | |
471 | version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0 | |
472 | ||
473 | For this reason, it is best to use either exclusively L<Numeric Versions> or | |
43eaf59d | 474 | L<Extended Versions> with multiple decimal points. |
cb5772bb RGS |
475 | |
476 | =back | |
477 | ||
478 | =over 4 | |
479 | ||
480 | =item * Logical Operators | |
481 | ||
482 | If you need to test whether a version object | |
483 | has been initialized, you can simply test it directly: | |
484 | ||
485 | $vobj = version->new($something); | |
486 | if ( $vobj ) # true only if $something was non-blank | |
487 | ||
488 | You can also test whether a version object is an L<Alpha version>, for | |
489 | example to prevent the use of some feature not present in the main | |
490 | release: | |
491 | ||
492 | $vobj = version->new("1.2_3"); # MUST QUOTE | |
493 | ...later... | |
494 | if ( $vobj->is_alpha ) # True | |
495 | ||
496 | =back | |
497 | ||
498 | =head2 Quoting | |
499 | ||
500 | Because of the nature of the Perl parsing and tokenizing routines, | |
501 | certain initialization values B<must> be quoted in order to correctly | |
43eaf59d SP |
502 | parse as the intended version, especially when using the L<qv()> operator. |
503 | In all cases, a floating point number passed to version->new() will be | |
504 | identically converted whether or not the value itself is quoted. This is | |
505 | not true for L<qv()>, however, when trailing zeros would be stripped on | |
506 | an unquoted input, which would result in a very different version object. | |
507 | ||
508 | In addition, in order to be compatible with earlier Perl version styles, | |
509 | any use of versions of the form 5.006001 will be translated as v5.6.1. | |
510 | In other words, a version with a single decimal point will be parsed as | |
511 | implicitly having three digits between subversions, but only for internal | |
512 | comparison purposes. | |
cb5772bb RGS |
513 | |
514 | The complicating factor is that in bare numbers (i.e. unquoted), the | |
515 | underscore is a legal numeric character and is automatically stripped | |
516 | by the Perl tokenizer before the version code is called. However, if | |
517 | a number containing one or more decimals and an underscore is quoted, i.e. | |
518 | not bare, that is considered a L<Alpha Version> and the underscore is | |
519 | significant. | |
520 | ||
521 | If you use a mathematic formula that resolves to a floating point number, | |
522 | you are dependent on Perl's conversion routines to yield the version you | |
523 | expect. You are pretty safe by dividing by a power of 10, for example, | |
524 | but other operations are not likely to be what you intend. For example: | |
525 | ||
526 | $VERSION = version->new((qw$Revision: 1.4)[1]/10); | |
527 | print $VERSION; # yields 0.14 | |
528 | $V2 = version->new(100/9); # Integer overflow in decimal number | |
529 | print $V2; # yields something like 11.111.111.100 | |
530 | ||
531 | Perl 5.8.1 and beyond will be able to automatically quote v-strings but | |
532 | that is not possible in earlier versions of Perl. In other words: | |
533 | ||
534 | $version = version->new("v2.5.4"); # legal in all versions of Perl | |
535 | $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1 | |
536 | ||
43eaf59d SP |
537 | =head2 What about v-strings? |
538 | ||
539 | Beginning with Perl 5.6.0, an alternate method to code arbitrary strings | |
540 | of bytes was introduced, called v-strings. They were intended to be an | |
541 | easy way to enter, for example, Unicode strings (which contain two bytes | |
542 | per character). Some programs have used them to encode printer control | |
543 | characters (e.g. CRLF). They were also intended to be used for $VERSION, | |
544 | but their use as such has been problematic from the start. | |
545 | ||
546 | There are two ways to enter v-strings: a bare number with two or more | |
547 | decimal points, or a bare number with one or more decimal points and a | |
548 | leading 'v' character (also bare). For example: | |
549 | ||
550 | $vs1 = 1.2.3; # encoded as \1\2\3 | |
551 | $vs2 = v1.2; # encoded as \1\2 | |
552 | ||
f34c6aaf JP |
553 | However, the use of bare v-strings to initialize version objects is |
554 | B<strongly> discouraged in all circumstances (especially the leading | |
555 | 'v' style), since the meaning will change depending on which Perl you | |
556 | are running. It is better to directly use L<"Extended Versions"> to | |
557 | ensure the proper interpretation. | |
558 | ||
559 | If you insist on using bare v-strings with Perl > 5.6.0, be aware of the | |
560 | following limitations: | |
43eaf59d | 561 | |
f34c6aaf JP |
562 | 1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses, |
563 | based on some characteristics of v-strings. You B<must> use a three part | |
564 | version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful. | |
565 | ||
566 | 2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl | |
567 | core to be magical, which means that the version.pm code can automatically | |
568 | determine whether the v-string encoding was used. | |
cb5772bb | 569 | |
8cb289bd RGS |
570 | 3) In all cases, a version created using v-strings will have a stringified |
571 | form that has a leading 'v' character, for the simple reason that sometimes | |
572 | it is impossible to tell whether one was present initially. | |
573 | ||
cb5772bb RGS |
574 | =head2 Types of Versions Objects |
575 | ||
576 | There are two types of Version Objects: | |
577 | ||
578 | =over 4 | |
579 | ||
580 | =item * Ordinary versions | |
581 | ||
582 | These are the versions that normal modules will use. Can contain as | |
583 | many subversions as required. In particular, those using RCS/CVS can | |
584 | use the following: | |
585 | ||
586 | $VERSION = version->new(qw$Revision: 2.7 $); | |
587 | ||
588 | and the current RCS Revision for that file will be inserted | |
589 | automatically. If the file has been moved to a branch, the Revision | |
590 | will have three or more elements; otherwise, it will have only two. | |
591 | This allows you to automatically increment your module version by | |
592 | using the Revision number from the primary file in a distribution, see | |
593 | L<ExtUtils::MakeMaker/"VERSION_FROM">. | |
594 | ||
595 | =item * Alpha Versions | |
596 | ||
597 | For module authors using CPAN, the convention has been to note | |
598 | unstable releases with an underscore in the version string, see | |
599 | L<CPAN>. Alpha releases will test as being newer than the more recent | |
600 | stable release, and less than the next stable release. For example: | |
601 | ||
602 | $alphaver = version->new("12.03_01"); # must be quoted | |
603 | ||
604 | obeys the relationship | |
605 | ||
606 | 12.03 < $alphaver < 12.04 | |
607 | ||
43eaf59d | 608 | Alpha versions with a single decimal point will be treated exactly as if |
8cb289bd RGS |
609 | they were L<Numeric Versions>, for parsing and output purposes. The |
610 | underscore will be output when an alpha version is stringified, in the same | |
611 | place as it was when input. | |
cb5772bb | 612 | |
43eaf59d | 613 | Alpha versions with more than a single decimal point will be treated |
7de739db | 614 | exactly as if they were L<Extended Versions>, and will display without any |
cb5772bb RGS |
615 | trailing (or leading) zeros, in the L<Version Normal> form. For example, |
616 | ||
617 | $newver = version->new("12.3.1_1"); | |
618 | print $newver; # v12.3.1_1 | |
619 | ||
f34c6aaf JP |
620 | =back |
621 | ||
cb5772bb RGS |
622 | =head2 Replacement UNIVERSAL::VERSION |
623 | ||
624 | In addition to the version objects, this modules also replaces the core | |
625 | UNIVERSAL::VERSION function with one that uses version objects for its | |
8cb289bd RGS |
626 | comparisons. The return from this operator is always the stringified form, |
627 | but the warning message generated includes either the stringified form or | |
628 | the normal form, depending on how it was called. | |
cb5772bb RGS |
629 | |
630 | For example: | |
631 | ||
632 | package Foo; | |
633 | $VERSION = 1.2; | |
634 | ||
635 | package Bar; | |
636 | $VERSION = "1.3.5"; # works with all Perl's (since it is quoted) | |
637 | ||
638 | package main; | |
639 | use version; | |
640 | ||
641 | print $Foo::VERSION; # prints 1.2 | |
642 | ||
643 | print $Bar::VERSION; # prints 1.003005 | |
644 | ||
8cb289bd RGS |
645 | eval "use foo 10"; |
646 | print $@; # prints "foo version 10 required..." | |
647 | eval "use foo 1.3.5; # work in Perl 5.6.1 or better | |
648 | print $@; # prints "foo version 1.3.5 required..." | |
649 | ||
650 | eval "use bar 1.3.6"; | |
651 | print $@; # prints "bar version 1.3.6 required..." | |
652 | eval "use bar 1.004"; # note numeric version | |
653 | print $@; # prints "bar version 1.004 required..." | |
654 | ||
cb5772bb RGS |
655 | |
656 | IMPORTANT NOTE: This may mean that code which searches for a specific | |
657 | string (to determine whether a given module is available) may need to be | |
8cb289bd RGS |
658 | changed. It is always better to use the built-in comparison implicit in |
659 | C<use> or C<require>, rather than manually poking at C<class->VERSION> | |
660 | and then doing a comparison yourself. | |
cb5772bb RGS |
661 | |
662 | The replacement UNIVERSAL::VERSION, when used as a function, like this: | |
663 | ||
664 | print $module->VERSION; | |
665 | ||
8cb289bd RGS |
666 | will also exclusively return the stringified form. See L<Stringification> |
667 | for more details. | |
cb5772bb RGS |
668 | |
669 | =head1 SUBCLASSING | |
670 | ||
671 | This module is specifically designed and tested to be easily subclassed. | |
672 | In practice, you only need to override the methods you want to change, but | |
673 | you have to take some care when overriding new() (since that is where all | |
674 | of the parsing takes place). For example, this is a perfect acceptable | |
675 | derived class: | |
676 | ||
677 | package myversion; | |
678 | use base version; | |
679 | sub new { | |
680 | my($self,$n)=@_; | |
681 | my $obj; | |
682 | # perform any special input handling here | |
683 | $obj = $self->SUPER::new($n); | |
684 | # and/or add additional hash elements here | |
685 | return $obj; | |
686 | } | |
687 | ||
688 | See also L<version::AlphaBeta> on CPAN for an alternate representation of | |
689 | version strings. | |
690 | ||
92dcf8ce JP |
691 | B<NOTE:> Although the L<qv> operator is not a true class method, but rather a |
692 | function exported into the caller's namespace, a subclass of version will | |
693 | inherit an import() function which will perform the correct magic on behalf | |
694 | of the subclass. | |
cb5772bb RGS |
695 | |
696 | =head1 EXPORT | |
697 | ||
7de739db | 698 | qv - Extended Version initialization operator |
cb5772bb RGS |
699 | |
700 | =head1 AUTHOR | |
701 | ||
702 | John Peacock E<lt>jpeacock@cpan.orgE<gt> | |
703 | ||
704 | =head1 SEE ALSO | |
705 | ||
706 | L<perl>. | |
707 | ||
708 | =cut |