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 |
9 | print $version; # 12.2.1 |
10 | print $version->numify; # 12.002001 |
11 | if ( $version gt "12.2" ) # true |
12 | |
13 | $alphaver = version->new("1.02_03"); # must be quoted! |
14 | print $alphaver; # 1.02_030 |
15 | print $alphaver->is_alpha(); # true |
16 | |
17 | $ver = qv(1.2); # 1.2.0 |
18 | $ver = qv("1.2"); # 1.2.0 |
19 | |
20 | $perlver = version->new(5.005_03); # must not be quoted! |
21 | print $perlver; # 5.005030 |
22 | |
23 | =head1 DESCRIPTION |
24 | |
25 | Overloaded version objects for all versions of Perl. This module |
26 | implements all of the features of version objects which will be part |
27 | of Perl 5.10.0 except automatic version object creation. |
28 | |
29 | =head2 What IS a version |
30 | |
31 | For the purposes of this module, a version "number" is a sequence of |
32 | positive integral values separated by decimal points and optionally a |
33 | single underscore. This corresponds to what Perl itself uses for a |
34 | version, as well as extending the "version as number" that is discussed |
35 | in the various editions of the Camel book. |
36 | |
37 | There are actually two distinct ways to initialize versions: |
38 | |
39 | =over 4 |
40 | |
41 | =item * Numeric Versions |
42 | |
43 | Any initial parameter which "looks like a number", see L<Numeric |
44 | Versions>. This also covers versions with a single decimal place and |
45 | a single embedded underscore, see L<Numeric Alpha Versions>, even though |
46 | these must be quoted to preserve the underscore formatting. |
47 | |
48 | =item * Quoted Versions |
49 | |
50 | Any initial parameter which contains more than one decimal point |
51 | and an optional embedded underscore, see L<Quoted Versions>. |
52 | |
53 | =back |
54 | |
55 | Both of these methods will produce similar version objects, in that |
56 | the default stringification will yield the version L<Normal Form> only |
57 | if required: |
58 | |
59 | $v = version->new(1.002); # 1.002, but compares like 1.2.0 |
60 | $v = version->new(1.002003); # 1.002003 |
61 | $v2 = version->new( "1.2.3"); # v1.2.3 |
62 | $v3 = version->new( 1.2.3); # v1.2.3 for Perl >= 5.8.1 |
63 | |
64 | In specific, version numbers initialized as L<Numeric Versions> will |
65 | stringify in Numeric form. Version numbers initialized as L<Quoted Versions> |
66 | will be stringified as L<Normal Form>. |
67 | |
68 | Please see L<Quoting> for more details on how Perl will parse various |
69 | input values. |
70 | |
71 | Any value passed to the new() operator will be parsed only so far as it |
72 | contains a numeric, decimal, or underscore character. So, for example: |
73 | |
74 | $v1 = version->new("99 and 94/100 percent pure"); # $v1 == 99.0 |
75 | $v2 = version->new("something"); # $v2 == "" and $v2->numify == 0 |
76 | |
77 | However, see L<New Operator> for one case where non-numeric text is |
78 | acceptable when initializing version objects. |
79 | |
80 | =head2 What about v-strings? |
81 | |
82 | Beginning with Perl 5.6.0, an alternate method to code arbitrary strings |
83 | of bytes was introduced, called v-strings. They were intended to be an |
84 | easy way to enter, for example, Unicode strings (which contain two bytes |
85 | per character). Some programs have used them to encode printer control |
86 | characters (e.g. CRLF). They were also intended to be used for $VERSION. |
87 | Their use has been problematic from the start and they will be phased out |
88 | beginning in Perl 5.10.0. |
89 | |
90 | There are two ways to enter v-strings: a bare number with two or more |
91 | decimal places, or a bare number with one or more decimal places and a |
92 | leading 'v' character (also bare). For example: |
93 | |
94 | $vs1 = 1.2.3; # encoded as \1\2\3 |
95 | $vs2 = v1.2; # encoded as \1\2 |
96 | |
97 | The first of those two syntaxes is destined to be the default way to create |
98 | a version object in 5.10.0, whereas the second will issue a mandatory |
99 | deprecation warning beginning at the same time. In both cases, a v-string |
100 | encoded version will always be stringified in the version L<Normal Form>. |
101 | |
102 | Consequently, the use of v-strings to initialize version objects with |
103 | this module is only possible with Perl 5.8.1 or better (which contain special |
104 | code to enable it). Their use is B<strongly> discouraged in all |
105 | circumstances (especially the leading 'v' style), since the meaning will |
106 | change depending on which Perl you are running. It is better to use |
107 | L<"Quoted Versions"> to ensure the proper interpretation. |
108 | |
109 | =head2 Numeric Versions |
110 | |
111 | These correspond to historical versions of Perl itself prior to 5.6.0, |
112 | as well as all other modules which follow the Camel rules for the |
113 | $VERSION scalar. A numeric version is initialized with what looks like |
114 | a floating point number. Leading zeros B<are> significant and trailing |
115 | zeros are implied so that a minimum of three places is maintained |
116 | between subversions. What this means is that any subversion (digits |
117 | to the right of the decimal place) that contains less than three digits |
118 | will have trailing zeros added to make up the difference, but only for |
119 | purposes of comparison with other version objects. For example: |
120 | |
121 | $v = version->new( 1.2); # prints 1.2, compares as 1.200.0 |
122 | $v = version->new( 1.02); # prints 1.02, compares as 1.20.0 |
123 | $v = version->new( 1.002); # prints 1.002, compares as 1.2.0 |
124 | $v = version->new( 1.0023); # 1.2.300 |
125 | $v = version->new( 1.00203); # 1.2.30 |
126 | $v = version->new( 1.002_03); # 1.2.30 See "Quoting" |
127 | $v = version->new( 1.002003); # 1.2.3 |
128 | |
129 | All of the preceding examples except the second to last are true |
130 | whether or not the input value is quoted. The important feature is that |
131 | the input value contains only a single decimal. |
132 | |
133 | IMPORTANT NOTE: If your numeric version contains more than 3 significant |
134 | digits after the decimal place, it will be split on each multiple of 3, so |
135 | 1.0003 becomes 1.0.300, due to the need to remain compatible with Perl's |
136 | own 5.005_03 == 5.5.30 interpretation. |
137 | |
138 | =head2 Quoted Versions |
139 | |
140 | These are the newest form of versions, and correspond to Perl's own |
141 | version style beginning with 5.6.0. Starting with Perl 5.10.0, |
142 | and most likely Perl 6, this is likely to be the preferred form. This |
143 | method requires that the input parameter be quoted, although Perl's after |
144 | 5.9.0 can use bare numbers with multiple decimal places as a special form |
145 | of quoting. |
146 | |
147 | Unlike L<Numeric Versions>, Quoted Versions may have more than |
148 | a single decimal point, e.g. "5.6.1" (for all versions of Perl). If a |
149 | Quoted Version has only one decimal place (and no embedded underscore), |
150 | it is interpreted exactly like a L<Numeric Version>. |
151 | |
152 | So, for example: |
153 | |
154 | $v = version->new( "1.002"); # 1.2 |
155 | $v = version->new( "1.2.3"); # 1.2.3 |
156 | $v = version->new("1.0003"); # 1.0.300 |
157 | |
158 | In addition to conventional versions, Quoted Versions can be |
159 | used to create L<Alpha Versions>. |
160 | |
161 | In general, Quoted Versions permit the greatest amount of freedom |
162 | to specify a version, whereas Numeric Versions enforce a certain |
163 | uniformity. See also L<New Operator> for an additional method of |
164 | initializing version objects. |
165 | |
166 | =head2 Numeric Alpha Versions |
167 | |
168 | The one time that a numeric version must be quoted is when a alpha form is |
169 | used with an otherwise numeric version (i.e. a single decimal place). This |
170 | is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha |
171 | versions for automatic updating purposes. Since some developers have used |
172 | only two significant decimal places for their non-alpha releases, the |
173 | version object will automatically take that into account if the initializer |
174 | is quoted. For example Module::Example was released to CPAN with the |
175 | following sequence of $VERSION's: |
176 | |
177 | # $VERSION Stringified |
178 | 0.01 0.010 |
179 | 0.02 0.020 |
180 | 0.02_01 0.02_0100 |
181 | 0.02_02 0.02_0200 |
182 | 0.03 0.030 |
183 | etc. |
184 | |
185 | As you can see, the version object created from the values in the first |
186 | column may contain a trailing 0, but will otherwise be both mathematically |
187 | equivalent and sorts alpha-numerically as would be expected. |
188 | |
189 | =head2 Object Methods |
190 | |
191 | Overloading has been used with version objects to provide a natural |
192 | interface for their use. All mathematical operations are forbidden, |
193 | since they don't make any sense for base version objects. |
194 | |
195 | =over 4 |
196 | |
197 | =item * New Operator |
198 | |
199 | Like all OO interfaces, the new() operator is used to initialize |
200 | version objects. One way to increment versions when programming is to |
201 | use the CVS variable $Revision, which is automatically incremented by |
202 | CVS every time the file is committed to the repository. |
203 | |
204 | In order to facilitate this feature, the following |
205 | code can be employed: |
206 | |
207 | $VERSION = version->new(qw$Revision: 2.7 $); |
208 | |
209 | and the version object will be created as if the following code |
210 | were used: |
211 | |
212 | $VERSION = version->new("v2.7"); |
213 | |
214 | In other words, the version will be automatically parsed out of the |
215 | string, and it will be quoted to preserve the meaning CVS normally |
216 | carries for versions. The CVS $Revision$ increments differently from |
217 | numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if |
218 | it were a L<Quoted Version>. |
219 | |
220 | A new version object can be created as a copy of an existing version |
221 | object, either as a class method: |
222 | |
223 | $v1 = version->new(12.3); |
224 | $v2 = version->new($v1); |
225 | |
226 | or as an object method: |
227 | |
228 | $v1 = version->new(12.3); |
229 | $v2 = $v1->new(); |
230 | |
231 | and in each case, $v1 and $v2 will be identical. |
232 | |
233 | =back |
234 | |
235 | =over 4 |
236 | |
237 | =item * qv() |
238 | |
239 | An alternate way to create a new version object is through the exported |
240 | qv() sub. This is not strictly like other q? operators (like qq, qw), |
241 | in that the only delimiters supported are parentheses (or spaces). It is |
242 | the best way to initialize a short version without triggering the floating |
243 | point interpretation. For example: |
244 | |
245 | $v1 = qv(1.2); # 1.2.0 |
246 | $v2 = qv("1.2"); # also 1.2.0 |
247 | |
248 | As you can see, either a bare number or a quoted string can be used, and |
249 | either will yield the same version number. |
250 | |
251 | =back |
252 | |
253 | For the subsequent examples, the following three objects will be used: |
254 | |
255 | $ver = version->new("1.2.3.4"); # see "Quoting" below |
256 | $alpha = version->new("1.2.3_4"); # see "Alpha versions" below |
257 | $nver = version->new(1.002); # see "Numeric Versions" above |
258 | |
259 | =over 4 |
260 | |
261 | =item * Normal Form |
262 | |
263 | For any version object which is initialized with multiple decimal |
264 | places (either quoted or if possible v-string), or initialized using |
265 | the L<qv()> operator, the stringified representation is returned in |
266 | a normalized or reduced form (no extraneous zeros), and with a leading 'v': |
267 | |
268 | print $ver->normal; # prints as v1.2.3 |
269 | print $ver->stringify; # ditto |
270 | print $ver; # ditto |
271 | print $nver->normal; # prints as v1.2.0 |
272 | print $nver->stringify; # prints as 1.002, see "Stringification" |
273 | |
274 | In order to preserve the meaning of the processed version, the |
275 | normalized representation will always contain at least three sub terms. |
276 | In other words, the following is guaranteed to always be true: |
277 | |
278 | my $newver = version->new($ver->stringify); |
279 | if ($newver eq $ver ) # always true |
280 | {...} |
281 | |
282 | =back |
283 | |
284 | =over 4 |
285 | |
286 | =item * Numification |
287 | |
288 | Although all mathematical operations on version objects are forbidden |
289 | by default, it is possible to retrieve a number which roughly |
290 | corresponds to the version object through the use of the $obj->numify |
291 | method. For formatting purposes, when displaying a number which |
292 | corresponds a version object, all sub versions are assumed to have |
293 | three decimal places. So for example: |
294 | |
295 | print $ver->numify; # prints 1.002003 |
296 | print $nver->numify; # prints 1.002 |
297 | |
298 | Unlike the stringification operator, there is never any need to append |
299 | trailing zeros to preserve the correct version value. |
300 | |
301 | =back |
302 | |
303 | =over 4 |
304 | |
305 | =item * Stringification |
306 | |
307 | In order to mirror as much as possible the existing behavior of ordinary |
308 | $VERSION scalars, the stringification operation will display differently, |
309 | depending on whether the version was initialized as a L<Numeric Version> |
310 | or L<Quoted Version>. |
311 | |
312 | What this means in practice is that if the normal CPAN and Camel rules are |
313 | followed ($VERSION is a floating point number with no more than 3 decimal |
314 | places), the stringified output will be exactly the same as the numified |
315 | output. There will be no visible difference, although the internal |
316 | representation will be different, and the L<Comparison operators> will |
317 | function using the internal coding. |
318 | |
319 | If a version object is initialized using a L<Quoted Version> form, or if |
320 | the number of significant decimal places exceed three, then the stringified |
321 | form will be the L<Normal Form>. The $obj->normal operation can always be |
322 | used to produce the L<Normal Form>, even if the version was originally a |
323 | L<Numeric Version>. |
324 | |
325 | print $ver->stringify; # prints v1.2.3 |
326 | print $nver->stringify; # prints 1.002 |
327 | |
328 | =back |
329 | |
330 | =over 4 |
331 | |
332 | =item * Comparison operators |
333 | |
334 | Both cmp and <=> operators perform the same comparison between terms |
335 | (upgrading to a version object automatically). Perl automatically |
336 | generates all of the other comparison operators based on those two. |
337 | In addition to the obvious equalities listed below, appending a single |
338 | trailing 0 term does not change the value of a version for comparison |
339 | purposes. In other words "v1.2" and "1.2.0" will compare as identical. |
340 | |
341 | For example, the following relations hold: |
342 | |
343 | As Number As String Truth Value |
344 | --------- ------------ ----------- |
345 | $ver > 1.0 $ver gt "1.0" true |
346 | $ver < 2.5 $ver lt true |
347 | $ver != 1.3 $ver ne "1.3" true |
348 | $ver == 1.2 $ver eq "1.2" false |
349 | $ver == 1.2.3 $ver eq "1.2.3" see discussion below |
350 | |
351 | It is probably best to chose either the numeric notation or the string |
352 | notation and stick with it, to reduce confusion. Perl6 version objects |
353 | B<may> only support numeric comparisons. See also L<"Quoting">. |
354 | |
355 | WARNING: Comparing version with unequal numbers of decimal places (whether |
356 | explicitly or implicitly initialized), may yield unexpected results at |
357 | first glance. For example, the following inequalities hold: |
358 | |
359 | version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0 |
360 | version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0 |
361 | |
362 | For this reason, it is best to use either exclusively L<Numeric Versions> or |
363 | L<Quoted Versions> with multiple decimal places. |
364 | |
365 | =back |
366 | |
367 | =over 4 |
368 | |
369 | =item * Logical Operators |
370 | |
371 | If you need to test whether a version object |
372 | has been initialized, you can simply test it directly: |
373 | |
374 | $vobj = version->new($something); |
375 | if ( $vobj ) # true only if $something was non-blank |
376 | |
377 | You can also test whether a version object is an L<Alpha version>, for |
378 | example to prevent the use of some feature not present in the main |
379 | release: |
380 | |
381 | $vobj = version->new("1.2_3"); # MUST QUOTE |
382 | ...later... |
383 | if ( $vobj->is_alpha ) # True |
384 | |
385 | =back |
386 | |
387 | =head2 Quoting |
388 | |
389 | Because of the nature of the Perl parsing and tokenizing routines, |
390 | certain initialization values B<must> be quoted in order to correctly |
391 | parse as the intended version, and additionally, some initial values |
392 | B<must not> be quoted to obtain the intended version. |
393 | |
394 | Except for L<Alpha versions>, any version initialized with something |
395 | that looks like a number (a single decimal place) will be parsed in |
396 | the same way whether or not the term is quoted. In order to be |
397 | compatible with earlier Perl version styles, any use of versions of |
398 | the form 5.006001 will be translated as 5.6.1. In other words, a |
399 | version with a single decimal place will be parsed as implicitly |
400 | having three places between subversions. |
401 | |
402 | The complicating factor is that in bare numbers (i.e. unquoted), the |
403 | underscore is a legal numeric character and is automatically stripped |
404 | by the Perl tokenizer before the version code is called. However, if |
405 | a number containing one or more decimals and an underscore is quoted, i.e. |
406 | not bare, that is considered a L<Alpha Version> and the underscore is |
407 | significant. |
408 | |
409 | If you use a mathematic formula that resolves to a floating point number, |
410 | you are dependent on Perl's conversion routines to yield the version you |
411 | expect. You are pretty safe by dividing by a power of 10, for example, |
412 | but other operations are not likely to be what you intend. For example: |
413 | |
414 | $VERSION = version->new((qw$Revision: 1.4)[1]/10); |
415 | print $VERSION; # yields 0.14 |
416 | $V2 = version->new(100/9); # Integer overflow in decimal number |
417 | print $V2; # yields something like 11.111.111.100 |
418 | |
419 | Perl 5.8.1 and beyond will be able to automatically quote v-strings but |
420 | that is not possible in earlier versions of Perl. In other words: |
421 | |
422 | $version = version->new("v2.5.4"); # legal in all versions of Perl |
423 | $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1 |
424 | |
425 | |
426 | =head2 Types of Versions Objects |
427 | |
428 | There are two types of Version Objects: |
429 | |
430 | =over 4 |
431 | |
432 | =item * Ordinary versions |
433 | |
434 | These are the versions that normal modules will use. Can contain as |
435 | many subversions as required. In particular, those using RCS/CVS can |
436 | use the following: |
437 | |
438 | $VERSION = version->new(qw$Revision: 2.7 $); |
439 | |
440 | and the current RCS Revision for that file will be inserted |
441 | automatically. If the file has been moved to a branch, the Revision |
442 | will have three or more elements; otherwise, it will have only two. |
443 | This allows you to automatically increment your module version by |
444 | using the Revision number from the primary file in a distribution, see |
445 | L<ExtUtils::MakeMaker/"VERSION_FROM">. |
446 | |
447 | =item * Alpha Versions |
448 | |
449 | For module authors using CPAN, the convention has been to note |
450 | unstable releases with an underscore in the version string, see |
451 | L<CPAN>. Alpha releases will test as being newer than the more recent |
452 | stable release, and less than the next stable release. For example: |
453 | |
454 | $alphaver = version->new("12.03_01"); # must be quoted |
455 | |
456 | obeys the relationship |
457 | |
458 | 12.03 < $alphaver < 12.04 |
459 | |
460 | Alpha versions with a single decimal place will be treated exactly as if |
461 | they were L<Numeric Versions>, for parsing purposes. The stringification for |
462 | alpha versions with a single decimal place may seem surprising, since any |
463 | trailing zeros will visible. For example, the above $alphaver will print as |
464 | |
465 | 12.03_0100 |
466 | |
467 | which is mathematically equivalent and ASCII sorts exactly the same as |
468 | without the trailing zeros. |
469 | |
470 | Alpha versions with more than a single decimal place will be treated |
471 | exactly as if they were L<Quoted Versions>, and will display without any |
472 | trailing (or leading) zeros, in the L<Version Normal> form. For example, |
473 | |
474 | $newver = version->new("12.3.1_1"); |
475 | print $newver; # v12.3.1_1 |
476 | |
477 | =head2 Replacement UNIVERSAL::VERSION |
478 | |
479 | In addition to the version objects, this modules also replaces the core |
480 | UNIVERSAL::VERSION function with one that uses version objects for its |
481 | comparisons. The return from this operator is always the numified form, |
482 | and the warning message generated includes both the numified and normal |
483 | forms (for clarity). |
484 | |
485 | For example: |
486 | |
487 | package Foo; |
488 | $VERSION = 1.2; |
489 | |
490 | package Bar; |
491 | $VERSION = "1.3.5"; # works with all Perl's (since it is quoted) |
492 | |
493 | package main; |
494 | use version; |
495 | |
496 | print $Foo::VERSION; # prints 1.2 |
497 | |
498 | print $Bar::VERSION; # prints 1.003005 |
499 | |
500 | eval "use CGI 10"; # some far future release |
501 | print $@; # prints "CGI version 10 (10.0.0) required..." |
502 | |
503 | IMPORTANT NOTE: This may mean that code which searches for a specific |
504 | string (to determine whether a given module is available) may need to be |
505 | changed. |
506 | |
507 | The replacement UNIVERSAL::VERSION, when used as a function, like this: |
508 | |
509 | print $module->VERSION; |
510 | |
511 | will also exclusively return the numified form. Technically, the |
512 | $module->VERSION function returns a string (PV) that can be converted to a |
513 | number following the normal Perl rules, when used in a numeric context. |
514 | |
515 | =head1 SUBCLASSING |
516 | |
517 | This module is specifically designed and tested to be easily subclassed. |
518 | In practice, you only need to override the methods you want to change, but |
519 | you have to take some care when overriding new() (since that is where all |
520 | of the parsing takes place). For example, this is a perfect acceptable |
521 | derived class: |
522 | |
523 | package myversion; |
524 | use base version; |
525 | sub new { |
526 | my($self,$n)=@_; |
527 | my $obj; |
528 | # perform any special input handling here |
529 | $obj = $self->SUPER::new($n); |
530 | # and/or add additional hash elements here |
531 | return $obj; |
532 | } |
533 | |
534 | See also L<version::AlphaBeta> on CPAN for an alternate representation of |
535 | version strings. |
536 | |
537 | =head1 EXPORT |
538 | |
539 | qv - quoted version initialization operator |
540 | |
541 | =head1 AUTHOR |
542 | |
543 | John Peacock E<lt>jpeacock@cpan.orgE<gt> |
544 | |
545 | =head1 SEE ALSO |
546 | |
547 | L<perl>. |
548 | |
549 | =cut |
550 | =head1 NAME |
551 | |
552 | version - Perl extension for Version Objects |
553 | |
554 | =head1 SYNOPSIS |
555 | |
556 | use version; |
557 | $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1 |
558 | print $version; # 12.2.1 |
559 | print $version->numify; # 12.002001 |
560 | if ( $version gt "12.2" ) # true |
561 | |
562 | $alphaver = version->new("1.02_03"); # must be quoted! |
563 | print $alphaver; # 1.02_030 |
564 | print $alphaver->is_alpha(); # true |
565 | |
566 | $ver = qv(1.2); # 1.2.0 |
567 | $ver = qv("1.2"); # 1.2.0 |
568 | |
569 | $perlver = version->new(5.005_03); # must not be quoted! |
570 | print $perlver; # 5.005030 |
571 | |
572 | =head1 DESCRIPTION |
573 | |
574 | Overloaded version objects for all versions of Perl. This module |
575 | implements all of the features of version objects which will be part |
576 | of Perl 5.10.0 except automatic version object creation. |
577 | |
578 | =head2 What IS a version |
579 | |
580 | For the purposes of this module, a version "number" is a sequence of |
581 | positive integral values separated by decimal points and optionally a |
582 | single underscore. This corresponds to what Perl itself uses for a |
583 | version, as well as extending the "version as number" that is discussed |
584 | in the various editions of the Camel book. |
585 | |
586 | There are actually two distinct ways to initialize versions: |
587 | |
588 | =over 4 |
589 | |
590 | =item * Numeric Versions |
591 | |
592 | Any initial parameter which "looks like a number", see L<Numeric |
593 | Versions>. This also covers versions with a single decimal place and |
594 | a single embedded underscore, see L<Numeric Alpha Versions>, even though |
595 | these must be quoted to preserve the underscore formatting. |
596 | |
597 | =item * Quoted Versions |
598 | |
599 | Any initial parameter which contains more than one decimal point |
600 | and an optional embedded underscore, see L<Quoted Versions>. |
601 | |
602 | =back |
603 | |
604 | Both of these methods will produce similar version objects, in that |
605 | the default stringification will yield the version L<Normal Form> only |
606 | if required: |
607 | |
608 | $v = version->new(1.002); # 1.002, but compares like 1.2.0 |
609 | $v = version->new(1.002003); # 1.002003 |
610 | $v2 = version->new( "1.2.3"); # v1.2.3 |
611 | $v3 = version->new( 1.2.3); # v1.2.3 for Perl >= 5.8.1 |
612 | |
613 | In specific, version numbers initialized as L<Numeric Versions> will |
614 | stringify in Numeric form. Version numbers initialized as L<Quoted Versions> |
615 | will be stringified as L<Normal Form>. |
616 | |
617 | Please see L<Quoting> for more details on how Perl will parse various |
618 | input values. |
619 | |
620 | Any value passed to the new() operator will be parsed only so far as it |
621 | contains a numeric, decimal, or underscore character. So, for example: |
622 | |
623 | $v1 = version->new("99 and 94/100 percent pure"); # $v1 == 99.0 |
624 | $v2 = version->new("something"); # $v2 == "" and $v2->numify == 0 |
625 | |
626 | However, see L<New Operator> for one case where non-numeric text is |
627 | acceptable when initializing version objects. |
628 | |
629 | =head2 What about v-strings? |
630 | |
631 | Beginning with Perl 5.6.0, an alternate method to code arbitrary strings |
632 | of bytes was introduced, called v-strings. They were intended to be an |
633 | easy way to enter, for example, Unicode strings (which contain two bytes |
634 | per character). Some programs have used them to encode printer control |
635 | characters (e.g. CRLF). They were also intended to be used for $VERSION. |
636 | Their use has been problematic from the start and they will be phased out |
637 | beginning in Perl 5.10.0. |
638 | |
639 | There are two ways to enter v-strings: a bare number with two or more |
640 | decimal places, or a bare number with one or more decimal places and a |
641 | leading 'v' character (also bare). For example: |
642 | |
643 | $vs1 = 1.2.3; # encoded as \1\2\3 |
644 | $vs2 = v1.2; # encoded as \1\2 |
645 | |
646 | The first of those two syntaxes is destined to be the default way to create |
647 | a version object in 5.10.0, whereas the second will issue a mandatory |
648 | deprecation warning beginning at the same time. In both cases, a v-string |
649 | encoded version will always be stringified in the version L<Normal Form>. |
650 | |
651 | Consequently, the use of v-strings to initialize version objects with |
652 | this module is only possible with Perl 5.8.1 or better (which contain special |
653 | code to enable it). Their use is B<strongly> discouraged in all |
654 | circumstances (especially the leading 'v' style), since the meaning will |
655 | change depending on which Perl you are running. It is better to use |
656 | L<"Quoted Versions"> to ensure the proper interpretation. |
657 | |
658 | =head2 Numeric Versions |
659 | |
660 | These correspond to historical versions of Perl itself prior to 5.6.0, |
661 | as well as all other modules which follow the Camel rules for the |
662 | $VERSION scalar. A numeric version is initialized with what looks like |
663 | a floating point number. Leading zeros B<are> significant and trailing |
664 | zeros are implied so that a minimum of three places is maintained |
665 | between subversions. What this means is that any subversion (digits |
666 | to the right of the decimal place) that contains less than three digits |
667 | will have trailing zeros added to make up the difference, but only for |
668 | purposes of comparison with other version objects. For example: |
669 | |
670 | $v = version->new( 1.2); # prints 1.2, compares as 1.200.0 |
671 | $v = version->new( 1.02); # prints 1.02, compares as 1.20.0 |
672 | $v = version->new( 1.002); # prints 1.002, compares as 1.2.0 |
673 | $v = version->new( 1.0023); # 1.2.300 |
674 | $v = version->new( 1.00203); # 1.2.30 |
675 | $v = version->new( 1.002_03); # 1.2.30 See "Quoting" |
676 | $v = version->new( 1.002003); # 1.2.3 |
677 | |
678 | All of the preceding examples except the second to last are true |
679 | whether or not the input value is quoted. The important feature is that |
680 | the input value contains only a single decimal. |
681 | |
682 | IMPORTANT NOTE: If your numeric version contains more than 3 significant |
683 | digits after the decimal place, it will be split on each multiple of 3, so |
684 | 1.0003 becomes 1.0.300, due to the need to remain compatible with Perl's |
685 | own 5.005_03 == 5.5.30 interpretation. |
686 | |
687 | =head2 Quoted Versions |
688 | |
689 | These are the newest form of versions, and correspond to Perl's own |
690 | version style beginning with 5.6.0. Starting with Perl 5.10.0, |
691 | and most likely Perl 6, this is likely to be the preferred form. This |
692 | method requires that the input parameter be quoted, although Perl's after |
693 | 5.9.0 can use bare numbers with multiple decimal places as a special form |
694 | of quoting. |
695 | |
696 | Unlike L<Numeric Versions>, Quoted Versions may have more than |
697 | a single decimal point, e.g. "5.6.1" (for all versions of Perl). If a |
698 | Quoted Version has only one decimal place (and no embedded underscore), |
699 | it is interpreted exactly like a L<Numeric Version>. |
700 | |
701 | So, for example: |
702 | |
703 | $v = version->new( "1.002"); # 1.2 |
704 | $v = version->new( "1.2.3"); # 1.2.3 |
705 | $v = version->new("1.0003"); # 1.0.300 |
706 | |
707 | In addition to conventional versions, Quoted Versions can be |
708 | used to create L<Alpha Versions>. |
709 | |
710 | In general, Quoted Versions permit the greatest amount of freedom |
711 | to specify a version, whereas Numeric Versions enforce a certain |
712 | uniformity. See also L<New Operator> for an additional method of |
713 | initializing version objects. |
714 | |
715 | =head2 Numeric Alpha Versions |
716 | |
717 | The one time that a numeric version must be quoted is when a alpha form is |
718 | used with an otherwise numeric version (i.e. a single decimal place). This |
719 | is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha |
720 | versions for automatic updating purposes. Since some developers have used |
721 | only two significant decimal places for their non-alpha releases, the |
722 | version object will automatically take that into account if the initializer |
723 | is quoted. For example Module::Example was released to CPAN with the |
724 | following sequence of $VERSION's: |
725 | |
726 | # $VERSION Stringified |
727 | 0.01 0.010 |
728 | 0.02 0.020 |
729 | 0.02_01 0.02_0100 |
730 | 0.02_02 0.02_0200 |
731 | 0.03 0.030 |
732 | etc. |
733 | |
734 | As you can see, the version object created from the values in the first |
735 | column may contain a trailing 0, but will otherwise be both mathematically |
736 | equivalent and sorts alpha-numerically as would be expected. |
737 | |
738 | =head2 Object Methods |
739 | |
740 | Overloading has been used with version objects to provide a natural |
741 | interface for their use. All mathematical operations are forbidden, |
742 | since they don't make any sense for base version objects. |
743 | |
744 | =over 4 |
745 | |
746 | =item * New Operator |
747 | |
748 | Like all OO interfaces, the new() operator is used to initialize |
749 | version objects. One way to increment versions when programming is to |
750 | use the CVS variable $Revision, which is automatically incremented by |
751 | CVS every time the file is committed to the repository. |
752 | |
753 | In order to facilitate this feature, the following |
754 | code can be employed: |
755 | |
756 | $VERSION = version->new(qw$Revision: 2.7 $); |
757 | |
758 | and the version object will be created as if the following code |
759 | were used: |
760 | |
761 | $VERSION = version->new("v2.7"); |
762 | |
763 | In other words, the version will be automatically parsed out of the |
764 | string, and it will be quoted to preserve the meaning CVS normally |
765 | carries for versions. The CVS $Revision$ increments differently from |
766 | numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if |
767 | it were a L<Quoted Version>. |
768 | |
769 | A new version object can be created as a copy of an existing version |
770 | object, either as a class method: |
771 | |
772 | $v1 = version->new(12.3); |
773 | $v2 = version->new($v1); |
774 | |
775 | or as an object method: |
776 | |
777 | $v1 = version->new(12.3); |
778 | $v2 = $v1->new(); |
779 | |
780 | and in each case, $v1 and $v2 will be identical. |
781 | |
782 | =back |
783 | |
784 | =over 4 |
785 | |
786 | =item * qv() |
787 | |
788 | An alternate way to create a new version object is through the exported |
789 | qv() sub. This is not strictly like other q? operators (like qq, qw), |
790 | in that the only delimiters supported are parentheses (or spaces). It is |
791 | the best way to initialize a short version without triggering the floating |
792 | point interpretation. For example: |
793 | |
794 | $v1 = qv(1.2); # 1.2.0 |
795 | $v2 = qv("1.2"); # also 1.2.0 |
796 | |
797 | As you can see, either a bare number or a quoted string can be used, and |
798 | either will yield the same version number. |
799 | |
800 | =back |
801 | |
802 | For the subsequent examples, the following three objects will be used: |
803 | |
804 | $ver = version->new("1.2.3.4"); # see "Quoting" below |
805 | $alpha = version->new("1.2.3_4"); # see "Alpha versions" below |
806 | $nver = version->new(1.002); # see "Numeric Versions" above |
807 | |
808 | =over 4 |
809 | |
810 | =item * Normal Form |
811 | |
812 | For any version object which is initialized with multiple decimal |
813 | places (either quoted or if possible v-string), or initialized using |
814 | the L<qv()> operator, the stringified representation is returned in |
815 | a normalized or reduced form (no extraneous zeros), and with a leading 'v': |
816 | |
817 | print $ver->normal; # prints as v1.2.3 |
818 | print $ver->stringify; # ditto |
819 | print $ver; # ditto |
820 | print $nver->normal; # prints as v1.2.0 |
821 | print $nver->stringify; # prints as 1.002, see "Stringification" |
822 | |
823 | In order to preserve the meaning of the processed version, the |
824 | normalized representation will always contain at least three sub terms. |
825 | In other words, the following is guaranteed to always be true: |
826 | |
827 | my $newver = version->new($ver->stringify); |
828 | if ($newver eq $ver ) # always true |
829 | {...} |
830 | |
831 | =back |
832 | |
833 | =over 4 |
834 | |
835 | =item * Numification |
836 | |
837 | Although all mathematical operations on version objects are forbidden |
838 | by default, it is possible to retrieve a number which roughly |
839 | corresponds to the version object through the use of the $obj->numify |
840 | method. For formatting purposes, when displaying a number which |
841 | corresponds a version object, all sub versions are assumed to have |
842 | three decimal places. So for example: |
843 | |
844 | print $ver->numify; # prints 1.002003 |
845 | print $nver->numify; # prints 1.002 |
846 | |
847 | Unlike the stringification operator, there is never any need to append |
848 | trailing zeros to preserve the correct version value. |
849 | |
850 | =back |
851 | |
852 | =over 4 |
853 | |
854 | =item * Stringification |
855 | |
856 | In order to mirror as much as possible the existing behavior of ordinary |
857 | $VERSION scalars, the stringification operation will display differently, |
858 | depending on whether the version was initialized as a L<Numeric Version> |
859 | or L<Quoted Version>. |
860 | |
861 | What this means in practice is that if the normal CPAN and Camel rules are |
862 | followed ($VERSION is a floating point number with no more than 3 decimal |
863 | places), the stringified output will be exactly the same as the numified |
864 | output. There will be no visible difference, although the internal |
865 | representation will be different, and the L<Comparison operators> will |
866 | function using the internal coding. |
867 | |
868 | If a version object is initialized using a L<Quoted Version> form, or if |
869 | the number of significant decimal places exceed three, then the stringified |
870 | form will be the L<Normal Form>. The $obj->normal operation can always be |
871 | used to produce the L<Normal Form>, even if the version was originally a |
872 | L<Numeric Version>. |
873 | |
874 | print $ver->stringify; # prints v1.2.3 |
875 | print $nver->stringify; # prints 1.002 |
876 | |
877 | =back |
878 | |
879 | =over 4 |
880 | |
881 | =item * Comparison operators |
882 | |
883 | Both cmp and <=> operators perform the same comparison between terms |
884 | (upgrading to a version object automatically). Perl automatically |
885 | generates all of the other comparison operators based on those two. |
886 | In addition to the obvious equalities listed below, appending a single |
887 | trailing 0 term does not change the value of a version for comparison |
888 | purposes. In other words "v1.2" and "1.2.0" will compare as identical. |
889 | |
890 | For example, the following relations hold: |
891 | |
892 | As Number As String Truth Value |
893 | --------- ------------ ----------- |
894 | $ver > 1.0 $ver gt "1.0" true |
895 | $ver < 2.5 $ver lt true |
896 | $ver != 1.3 $ver ne "1.3" true |
897 | $ver == 1.2 $ver eq "1.2" false |
898 | $ver == 1.2.3 $ver eq "1.2.3" see discussion below |
899 | |
900 | It is probably best to chose either the numeric notation or the string |
901 | notation and stick with it, to reduce confusion. Perl6 version objects |
902 | B<may> only support numeric comparisons. See also L<"Quoting">. |
903 | |
904 | WARNING: Comparing version with unequal numbers of decimal places (whether |
905 | explicitly or implicitly initialized), may yield unexpected results at |
906 | first glance. For example, the following inequalities hold: |
907 | |
908 | version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0 |
909 | version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0 |
910 | |
911 | For this reason, it is best to use either exclusively L<Numeric Versions> or |
912 | L<Quoted Versions> with multiple decimal places. |
913 | |
914 | =back |
915 | |
916 | =over 4 |
917 | |
918 | =item * Logical Operators |
919 | |
920 | If you need to test whether a version object |
921 | has been initialized, you can simply test it directly: |
922 | |
923 | $vobj = version->new($something); |
924 | if ( $vobj ) # true only if $something was non-blank |
925 | |
926 | You can also test whether a version object is an L<Alpha version>, for |
927 | example to prevent the use of some feature not present in the main |
928 | release: |
929 | |
930 | $vobj = version->new("1.2_3"); # MUST QUOTE |
931 | ...later... |
932 | if ( $vobj->is_alpha ) # True |
933 | |
934 | =back |
935 | |
936 | =head2 Quoting |
937 | |
938 | Because of the nature of the Perl parsing and tokenizing routines, |
939 | certain initialization values B<must> be quoted in order to correctly |
940 | parse as the intended version, and additionally, some initial values |
941 | B<must not> be quoted to obtain the intended version. |
942 | |
943 | Except for L<Alpha versions>, any version initialized with something |
944 | that looks like a number (a single decimal place) will be parsed in |
945 | the same way whether or not the term is quoted. In order to be |
946 | compatible with earlier Perl version styles, any use of versions of |
947 | the form 5.006001 will be translated as 5.6.1. In other words, a |
948 | version with a single decimal place will be parsed as implicitly |
949 | having three places between subversions. |
950 | |
951 | The complicating factor is that in bare numbers (i.e. unquoted), the |
952 | underscore is a legal numeric character and is automatically stripped |
953 | by the Perl tokenizer before the version code is called. However, if |
954 | a number containing one or more decimals and an underscore is quoted, i.e. |
955 | not bare, that is considered a L<Alpha Version> and the underscore is |
956 | significant. |
957 | |
958 | If you use a mathematic formula that resolves to a floating point number, |
959 | you are dependent on Perl's conversion routines to yield the version you |
960 | expect. You are pretty safe by dividing by a power of 10, for example, |
961 | but other operations are not likely to be what you intend. For example: |
962 | |
963 | $VERSION = version->new((qw$Revision: 1.4)[1]/10); |
964 | print $VERSION; # yields 0.14 |
965 | $V2 = version->new(100/9); # Integer overflow in decimal number |
966 | print $V2; # yields something like 11.111.111.100 |
967 | |
968 | Perl 5.8.1 and beyond will be able to automatically quote v-strings but |
969 | that is not possible in earlier versions of Perl. In other words: |
970 | |
971 | $version = version->new("v2.5.4"); # legal in all versions of Perl |
972 | $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1 |
973 | |
974 | |
975 | =head2 Types of Versions Objects |
976 | |
977 | There are two types of Version Objects: |
978 | |
979 | =over 4 |
980 | |
981 | =item * Ordinary versions |
982 | |
983 | These are the versions that normal modules will use. Can contain as |
984 | many subversions as required. In particular, those using RCS/CVS can |
985 | use the following: |
986 | |
987 | $VERSION = version->new(qw$Revision: 2.7 $); |
988 | |
989 | and the current RCS Revision for that file will be inserted |
990 | automatically. If the file has been moved to a branch, the Revision |
991 | will have three or more elements; otherwise, it will have only two. |
992 | This allows you to automatically increment your module version by |
993 | using the Revision number from the primary file in a distribution, see |
994 | L<ExtUtils::MakeMaker/"VERSION_FROM">. |
995 | |
996 | =item * Alpha Versions |
997 | |
998 | For module authors using CPAN, the convention has been to note |
999 | unstable releases with an underscore in the version string, see |
1000 | L<CPAN>. Alpha releases will test as being newer than the more recent |
1001 | stable release, and less than the next stable release. For example: |
1002 | |
1003 | $alphaver = version->new("12.03_01"); # must be quoted |
1004 | |
1005 | obeys the relationship |
1006 | |
1007 | 12.03 < $alphaver < 12.04 |
1008 | |
1009 | Alpha versions with a single decimal place will be treated exactly as if |
1010 | they were L<Numeric Versions>, for parsing purposes. The stringification for |
1011 | alpha versions with a single decimal place may seem surprising, since any |
1012 | trailing zeros will visible. For example, the above $alphaver will print as |
1013 | |
1014 | 12.03_0100 |
1015 | |
1016 | which is mathematically equivalent and ASCII sorts exactly the same as |
1017 | without the trailing zeros. |
1018 | |
1019 | Alpha versions with more than a single decimal place will be treated |
1020 | exactly as if they were L<Quoted Versions>, and will display without any |
1021 | trailing (or leading) zeros, in the L<Version Normal> form. For example, |
1022 | |
1023 | $newver = version->new("12.3.1_1"); |
1024 | print $newver; # v12.3.1_1 |
1025 | |
1026 | =head2 Replacement UNIVERSAL::VERSION |
1027 | |
1028 | In addition to the version objects, this modules also replaces the core |
1029 | UNIVERSAL::VERSION function with one that uses version objects for its |
1030 | comparisons. The return from this operator is always the numified form, |
1031 | and the warning message generated includes both the numified and normal |
1032 | forms (for clarity). |
1033 | |
1034 | For example: |
1035 | |
1036 | package Foo; |
1037 | $VERSION = 1.2; |
1038 | |
1039 | package Bar; |
1040 | $VERSION = "1.3.5"; # works with all Perl's (since it is quoted) |
1041 | |
1042 | package main; |
1043 | use version; |
1044 | |
1045 | print $Foo::VERSION; # prints 1.2 |
1046 | |
1047 | print $Bar::VERSION; # prints 1.003005 |
1048 | |
1049 | eval "use CGI 10"; # some far future release |
1050 | print $@; # prints "CGI version 10 (10.0.0) required..." |
1051 | |
1052 | IMPORTANT NOTE: This may mean that code which searches for a specific |
1053 | string (to determine whether a given module is available) may need to be |
1054 | changed. |
1055 | |
1056 | The replacement UNIVERSAL::VERSION, when used as a function, like this: |
1057 | |
1058 | print $module->VERSION; |
1059 | |
1060 | will also exclusively return the numified form. Technically, the |
1061 | $module->VERSION function returns a string (PV) that can be converted to a |
1062 | number following the normal Perl rules, when used in a numeric context. |
1063 | |
1064 | =head1 SUBCLASSING |
1065 | |
1066 | This module is specifically designed and tested to be easily subclassed. |
1067 | In practice, you only need to override the methods you want to change, but |
1068 | you have to take some care when overriding new() (since that is where all |
1069 | of the parsing takes place). For example, this is a perfect acceptable |
1070 | derived class: |
1071 | |
1072 | package myversion; |
1073 | use base version; |
1074 | sub new { |
1075 | my($self,$n)=@_; |
1076 | my $obj; |
1077 | # perform any special input handling here |
1078 | $obj = $self->SUPER::new($n); |
1079 | # and/or add additional hash elements here |
1080 | return $obj; |
1081 | } |
1082 | |
1083 | See also L<version::AlphaBeta> on CPAN for an alternate representation of |
1084 | version strings. |
1085 | |
1086 | =head1 EXPORT |
1087 | |
1088 | qv - quoted version initialization operator |
1089 | |
1090 | =head1 AUTHOR |
1091 | |
1092 | John Peacock E<lt>jpeacock@cpan.orgE<gt> |
1093 | |
1094 | =head1 SEE ALSO |
1095 | |
1096 | L<perl>. |
1097 | |
1098 | =cut |