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