This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to version.pm 0.48
[perl5.git] / lib / version.pod
CommitLineData
cb5772bb
RGS
1=head1 NAME
2
3version - 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
25Overloaded version objects for all versions of Perl. This module
26implements all of the features of version objects which will be part
27of Perl 5.10.0 except automatic version object creation.
28
29=head2 What IS a version
30
31For the purposes of this module, a version "number" is a sequence of
32positive integral values separated by decimal points and optionally a
33single underscore. This corresponds to what Perl itself uses for a
34version, as well as extending the "version as number" that is discussed
35in the various editions of the Camel book.
36
37There are actually two distinct ways to initialize versions:
38
39=over 4
40
41=item * Numeric Versions
42
43Any initial parameter which "looks like a number", see L<Numeric
44Versions>. This also covers versions with a single decimal place and
45a single embedded underscore, see L<Numeric Alpha Versions>, even though
46these must be quoted to preserve the underscore formatting.
47
48=item * Quoted Versions
49
50Any initial parameter which contains more than one decimal point
51and an optional embedded underscore, see L<Quoted Versions>.
52
53=back
54
55Both of these methods will produce similar version objects, in that
56the default stringification will yield the version L<Normal Form> only
57if 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
64In specific, version numbers initialized as L<Numeric Versions> will
65stringify in Numeric form. Version numbers initialized as L<Quoted Versions>
66will be stringified as L<Normal Form>.
67
68Please see L<Quoting> for more details on how Perl will parse various
69input values.
70
71Any value passed to the new() operator will be parsed only so far as it
72contains 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
77However, see L<New Operator> for one case where non-numeric text is
78acceptable when initializing version objects.
79
80=head2 What about v-strings?
81
82Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
83of bytes was introduced, called v-strings. They were intended to be an
84easy way to enter, for example, Unicode strings (which contain two bytes
85per character). Some programs have used them to encode printer control
86characters (e.g. CRLF). They were also intended to be used for $VERSION.
87Their use has been problematic from the start and they will be phased out
88beginning in Perl 5.10.0.
89
90There are two ways to enter v-strings: a bare number with two or more
91decimal places, or a bare number with one or more decimal places and a
92leading '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
97The first of those two syntaxes is destined to be the default way to create
98a version object in 5.10.0, whereas the second will issue a mandatory
99deprecation warning beginning at the same time. In both cases, a v-string
100encoded version will always be stringified in the version L<Normal Form>.
101
102Consequently, the use of v-strings to initialize version objects with
103this module is only possible with Perl 5.8.1 or better (which contain special
104code to enable it). Their use is B<strongly> discouraged in all
105circumstances (especially the leading 'v' style), since the meaning will
106change depending on which Perl you are running. It is better to use
107L<"Quoted Versions"> to ensure the proper interpretation.
108
109=head2 Numeric Versions
110
111These correspond to historical versions of Perl itself prior to 5.6.0,
112as well as all other modules which follow the Camel rules for the
113$VERSION scalar. A numeric version is initialized with what looks like
114a floating point number. Leading zeros B<are> significant and trailing
115zeros are implied so that a minimum of three places is maintained
116between subversions. What this means is that any subversion (digits
117to the right of the decimal place) that contains less than three digits
118will have trailing zeros added to make up the difference, but only for
119purposes 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
129All of the preceding examples except the second to last are true
130whether or not the input value is quoted. The important feature is that
131the input value contains only a single decimal.
132
133IMPORTANT NOTE: If your numeric version contains more than 3 significant
134digits after the decimal place, it will be split on each multiple of 3, so
1351.0003 becomes 1.0.300, due to the need to remain compatible with Perl's
136own 5.005_03 == 5.5.30 interpretation.
137
138=head2 Quoted Versions
139
140These are the newest form of versions, and correspond to Perl's own
141version style beginning with 5.6.0. Starting with Perl 5.10.0,
142and most likely Perl 6, this is likely to be the preferred form. This
143method requires that the input parameter be quoted, although Perl's after
1445.9.0 can use bare numbers with multiple decimal places as a special form
145of quoting.
146
147Unlike L<Numeric Versions>, Quoted Versions may have more than
148a single decimal point, e.g. "5.6.1" (for all versions of Perl). If a
149Quoted Version has only one decimal place (and no embedded underscore),
150it is interpreted exactly like a L<Numeric Version>.
151
152So, 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
158In addition to conventional versions, Quoted Versions can be
159used to create L<Alpha Versions>.
160
161In general, Quoted Versions permit the greatest amount of freedom
162to specify a version, whereas Numeric Versions enforce a certain
163uniformity. See also L<New Operator> for an additional method of
164initializing version objects.
165
166=head2 Numeric Alpha Versions
167
168The one time that a numeric version must be quoted is when a alpha form is
169used with an otherwise numeric version (i.e. a single decimal place). This
170is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
171versions for automatic updating purposes. Since some developers have used
172only two significant decimal places for their non-alpha releases, the
173version object will automatically take that into account if the initializer
174is quoted. For example Module::Example was released to CPAN with the
175following 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
185As you can see, the version object created from the values in the first
186column may contain a trailing 0, but will otherwise be both mathematically
187equivalent and sorts alpha-numerically as would be expected.
188
189=head2 Object Methods
190
191Overloading has been used with version objects to provide a natural
192interface for their use. All mathematical operations are forbidden,
193since they don't make any sense for base version objects.
194
195=over 4
196
197=item * New Operator
198
199Like all OO interfaces, the new() operator is used to initialize
200version objects. One way to increment versions when programming is to
201use the CVS variable $Revision, which is automatically incremented by
202CVS every time the file is committed to the repository.
203
204In order to facilitate this feature, the following
205code can be employed:
206
207 $VERSION = version->new(qw$Revision: 2.7 $);
208
209and the version object will be created as if the following code
210were used:
211
212 $VERSION = version->new("v2.7");
213
214In other words, the version will be automatically parsed out of the
215string, and it will be quoted to preserve the meaning CVS normally
216carries for versions. The CVS $Revision$ increments differently from
217numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
218it were a L<Quoted Version>.
219
220A new version object can be created as a copy of an existing version
221object, either as a class method:
222
223 $v1 = version->new(12.3);
224 $v2 = version->new($v1);
225
226or as an object method:
227
228 $v1 = version->new(12.3);
229 $v2 = $v1->new();
230
231and in each case, $v1 and $v2 will be identical.
232
233=back
234
235=over 4
236
237=item * qv()
238
239An alternate way to create a new version object is through the exported
240qv() sub. This is not strictly like other q? operators (like qq, qw),
241in that the only delimiters supported are parentheses (or spaces). It is
242the best way to initialize a short version without triggering the floating
243point interpretation. For example:
244
245 $v1 = qv(1.2); # 1.2.0
246 $v2 = qv("1.2"); # also 1.2.0
247
248As you can see, either a bare number or a quoted string can be used, and
249either will yield the same version number.
250
251=back
252
253For 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
263For any version object which is initialized with multiple decimal
264places (either quoted or if possible v-string), or initialized using
265the L<qv()> operator, the stringified representation is returned in
266a 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
274In order to preserve the meaning of the processed version, the
275normalized representation will always contain at least three sub terms.
276In 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
288Although all mathematical operations on version objects are forbidden
289by default, it is possible to retrieve a number which roughly
290corresponds to the version object through the use of the $obj->numify
291method. For formatting purposes, when displaying a number which
292corresponds a version object, all sub versions are assumed to have
293three decimal places. So for example:
294
295 print $ver->numify; # prints 1.002003
296 print $nver->numify; # prints 1.002
297
298Unlike the stringification operator, there is never any need to append
299trailing zeros to preserve the correct version value.
300
301=back
302
303=over 4
304
305=item * Stringification
306
307In order to mirror as much as possible the existing behavior of ordinary
308$VERSION scalars, the stringification operation will display differently,
309depending on whether the version was initialized as a L<Numeric Version>
310or L<Quoted Version>.
311
312What this means in practice is that if the normal CPAN and Camel rules are
313followed ($VERSION is a floating point number with no more than 3 decimal
314places), the stringified output will be exactly the same as the numified
315output. There will be no visible difference, although the internal
316representation will be different, and the L<Comparison operators> will
317function using the internal coding.
318
319If a version object is initialized using a L<Quoted Version> form, or if
320the number of significant decimal places exceed three, then the stringified
321form will be the L<Normal Form>. The $obj->normal operation can always be
322used to produce the L<Normal Form>, even if the version was originally a
323L<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
334Both cmp and <=> operators perform the same comparison between terms
335(upgrading to a version object automatically). Perl automatically
336generates all of the other comparison operators based on those two.
337In addition to the obvious equalities listed below, appending a single
338trailing 0 term does not change the value of a version for comparison
339purposes. In other words "v1.2" and "1.2.0" will compare as identical.
340
341For 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
351It is probably best to chose either the numeric notation or the string
352notation and stick with it, to reduce confusion. Perl6 version objects
353B<may> only support numeric comparisons. See also L<"Quoting">.
354
355WARNING: Comparing version with unequal numbers of decimal places (whether
356explicitly or implicitly initialized), may yield unexpected results at
357first 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
362For this reason, it is best to use either exclusively L<Numeric Versions> or
363L<Quoted Versions> with multiple decimal places.
364
365=back
366
367=over 4
368
369=item * Logical Operators
370
371If you need to test whether a version object
372has 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
377You can also test whether a version object is an L<Alpha version>, for
378example to prevent the use of some feature not present in the main
379release:
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
389Because of the nature of the Perl parsing and tokenizing routines,
390certain initialization values B<must> be quoted in order to correctly
391parse as the intended version, and additionally, some initial values
392B<must not> be quoted to obtain the intended version.
393
394Except for L<Alpha versions>, any version initialized with something
395that looks like a number (a single decimal place) will be parsed in
396the same way whether or not the term is quoted. In order to be
397compatible with earlier Perl version styles, any use of versions of
398the form 5.006001 will be translated as 5.6.1. In other words, a
399version with a single decimal place will be parsed as implicitly
400having three places between subversions.
401
402The complicating factor is that in bare numbers (i.e. unquoted), the
403underscore is a legal numeric character and is automatically stripped
404by the Perl tokenizer before the version code is called. However, if
405a number containing one or more decimals and an underscore is quoted, i.e.
406not bare, that is considered a L<Alpha Version> and the underscore is
407significant.
408
409If you use a mathematic formula that resolves to a floating point number,
410you are dependent on Perl's conversion routines to yield the version you
411expect. You are pretty safe by dividing by a power of 10, for example,
412but 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
419Perl 5.8.1 and beyond will be able to automatically quote v-strings but
420that 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
428There are two types of Version Objects:
429
430=over 4
431
432=item * Ordinary versions
433
434These are the versions that normal modules will use. Can contain as
435many subversions as required. In particular, those using RCS/CVS can
436use the following:
437
438 $VERSION = version->new(qw$Revision: 2.7 $);
439
440and the current RCS Revision for that file will be inserted
441automatically. If the file has been moved to a branch, the Revision
442will have three or more elements; otherwise, it will have only two.
443This allows you to automatically increment your module version by
444using the Revision number from the primary file in a distribution, see
445L<ExtUtils::MakeMaker/"VERSION_FROM">.
446
447=item * Alpha Versions
448
449For module authors using CPAN, the convention has been to note
450unstable releases with an underscore in the version string, see
451L<CPAN>. Alpha releases will test as being newer than the more recent
452stable release, and less than the next stable release. For example:
453
454 $alphaver = version->new("12.03_01"); # must be quoted
455
456obeys the relationship
457
458 12.03 < $alphaver < 12.04
459
460Alpha versions with a single decimal place will be treated exactly as if
461they were L<Numeric Versions>, for parsing purposes. The stringification for
462alpha versions with a single decimal place may seem surprising, since any
463trailing zeros will visible. For example, the above $alphaver will print as
464
465 12.03_0100
466
467which is mathematically equivalent and ASCII sorts exactly the same as
468without the trailing zeros.
469
470Alpha versions with more than a single decimal place will be treated
471exactly as if they were L<Quoted Versions>, and will display without any
472trailing (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
479In addition to the version objects, this modules also replaces the core
480UNIVERSAL::VERSION function with one that uses version objects for its
481comparisons. The return from this operator is always the numified form,
482and the warning message generated includes both the numified and normal
483forms (for clarity).
484
485For 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
503IMPORTANT NOTE: This may mean that code which searches for a specific
504string (to determine whether a given module is available) may need to be
505changed.
506
507The replacement UNIVERSAL::VERSION, when used as a function, like this:
508
509 print $module->VERSION;
510
511will also exclusively return the numified form. Technically, the
512$module->VERSION function returns a string (PV) that can be converted to a
513number following the normal Perl rules, when used in a numeric context.
514
515=head1 SUBCLASSING
516
517This module is specifically designed and tested to be easily subclassed.
518In practice, you only need to override the methods you want to change, but
519you have to take some care when overriding new() (since that is where all
520of the parsing takes place). For example, this is a perfect acceptable
521derived 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
534See also L<version::AlphaBeta> on CPAN for an alternate representation of
535version strings.
536
537=head1 EXPORT
538
539qv - quoted version initialization operator
540
541=head1 AUTHOR
542
543John Peacock E<lt>jpeacock@cpan.orgE<gt>
544
545=head1 SEE ALSO
546
547L<perl>.
548
549=cut
550=head1 NAME
551
552version - 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
574Overloaded version objects for all versions of Perl. This module
575implements all of the features of version objects which will be part
576of Perl 5.10.0 except automatic version object creation.
577
578=head2 What IS a version
579
580For the purposes of this module, a version "number" is a sequence of
581positive integral values separated by decimal points and optionally a
582single underscore. This corresponds to what Perl itself uses for a
583version, as well as extending the "version as number" that is discussed
584in the various editions of the Camel book.
585
586There are actually two distinct ways to initialize versions:
587
588=over 4
589
590=item * Numeric Versions
591
592Any initial parameter which "looks like a number", see L<Numeric
593Versions>. This also covers versions with a single decimal place and
594a single embedded underscore, see L<Numeric Alpha Versions>, even though
595these must be quoted to preserve the underscore formatting.
596
597=item * Quoted Versions
598
599Any initial parameter which contains more than one decimal point
600and an optional embedded underscore, see L<Quoted Versions>.
601
602=back
603
604Both of these methods will produce similar version objects, in that
605the default stringification will yield the version L<Normal Form> only
606if 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
613In specific, version numbers initialized as L<Numeric Versions> will
614stringify in Numeric form. Version numbers initialized as L<Quoted Versions>
615will be stringified as L<Normal Form>.
616
617Please see L<Quoting> for more details on how Perl will parse various
618input values.
619
620Any value passed to the new() operator will be parsed only so far as it
621contains 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
626However, see L<New Operator> for one case where non-numeric text is
627acceptable when initializing version objects.
628
629=head2 What about v-strings?
630
631Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
632of bytes was introduced, called v-strings. They were intended to be an
633easy way to enter, for example, Unicode strings (which contain two bytes
634per character). Some programs have used them to encode printer control
635characters (e.g. CRLF). They were also intended to be used for $VERSION.
636Their use has been problematic from the start and they will be phased out
637beginning in Perl 5.10.0.
638
639There are two ways to enter v-strings: a bare number with two or more
640decimal places, or a bare number with one or more decimal places and a
641leading '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
646The first of those two syntaxes is destined to be the default way to create
647a version object in 5.10.0, whereas the second will issue a mandatory
648deprecation warning beginning at the same time. In both cases, a v-string
649encoded version will always be stringified in the version L<Normal Form>.
650
651Consequently, the use of v-strings to initialize version objects with
652this module is only possible with Perl 5.8.1 or better (which contain special
653code to enable it). Their use is B<strongly> discouraged in all
654circumstances (especially the leading 'v' style), since the meaning will
655change depending on which Perl you are running. It is better to use
656L<"Quoted Versions"> to ensure the proper interpretation.
657
658=head2 Numeric Versions
659
660These correspond to historical versions of Perl itself prior to 5.6.0,
661as well as all other modules which follow the Camel rules for the
662$VERSION scalar. A numeric version is initialized with what looks like
663a floating point number. Leading zeros B<are> significant and trailing
664zeros are implied so that a minimum of three places is maintained
665between subversions. What this means is that any subversion (digits
666to the right of the decimal place) that contains less than three digits
667will have trailing zeros added to make up the difference, but only for
668purposes 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
678All of the preceding examples except the second to last are true
679whether or not the input value is quoted. The important feature is that
680the input value contains only a single decimal.
681
682IMPORTANT NOTE: If your numeric version contains more than 3 significant
683digits after the decimal place, it will be split on each multiple of 3, so
6841.0003 becomes 1.0.300, due to the need to remain compatible with Perl's
685own 5.005_03 == 5.5.30 interpretation.
686
687=head2 Quoted Versions
688
689These are the newest form of versions, and correspond to Perl's own
690version style beginning with 5.6.0. Starting with Perl 5.10.0,
691and most likely Perl 6, this is likely to be the preferred form. This
692method requires that the input parameter be quoted, although Perl's after
6935.9.0 can use bare numbers with multiple decimal places as a special form
694of quoting.
695
696Unlike L<Numeric Versions>, Quoted Versions may have more than
697a single decimal point, e.g. "5.6.1" (for all versions of Perl). If a
698Quoted Version has only one decimal place (and no embedded underscore),
699it is interpreted exactly like a L<Numeric Version>.
700
701So, 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
707In addition to conventional versions, Quoted Versions can be
708used to create L<Alpha Versions>.
709
710In general, Quoted Versions permit the greatest amount of freedom
711to specify a version, whereas Numeric Versions enforce a certain
712uniformity. See also L<New Operator> for an additional method of
713initializing version objects.
714
715=head2 Numeric Alpha Versions
716
717The one time that a numeric version must be quoted is when a alpha form is
718used with an otherwise numeric version (i.e. a single decimal place). This
719is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
720versions for automatic updating purposes. Since some developers have used
721only two significant decimal places for their non-alpha releases, the
722version object will automatically take that into account if the initializer
723is quoted. For example Module::Example was released to CPAN with the
724following 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
734As you can see, the version object created from the values in the first
735column may contain a trailing 0, but will otherwise be both mathematically
736equivalent and sorts alpha-numerically as would be expected.
737
738=head2 Object Methods
739
740Overloading has been used with version objects to provide a natural
741interface for their use. All mathematical operations are forbidden,
742since they don't make any sense for base version objects.
743
744=over 4
745
746=item * New Operator
747
748Like all OO interfaces, the new() operator is used to initialize
749version objects. One way to increment versions when programming is to
750use the CVS variable $Revision, which is automatically incremented by
751CVS every time the file is committed to the repository.
752
753In order to facilitate this feature, the following
754code can be employed:
755
756 $VERSION = version->new(qw$Revision: 2.7 $);
757
758and the version object will be created as if the following code
759were used:
760
761 $VERSION = version->new("v2.7");
762
763In other words, the version will be automatically parsed out of the
764string, and it will be quoted to preserve the meaning CVS normally
765carries for versions. The CVS $Revision$ increments differently from
766numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
767it were a L<Quoted Version>.
768
769A new version object can be created as a copy of an existing version
770object, either as a class method:
771
772 $v1 = version->new(12.3);
773 $v2 = version->new($v1);
774
775or as an object method:
776
777 $v1 = version->new(12.3);
778 $v2 = $v1->new();
779
780and in each case, $v1 and $v2 will be identical.
781
782=back
783
784=over 4
785
786=item * qv()
787
788An alternate way to create a new version object is through the exported
789qv() sub. This is not strictly like other q? operators (like qq, qw),
790in that the only delimiters supported are parentheses (or spaces). It is
791the best way to initialize a short version without triggering the floating
792point interpretation. For example:
793
794 $v1 = qv(1.2); # 1.2.0
795 $v2 = qv("1.2"); # also 1.2.0
796
797As you can see, either a bare number or a quoted string can be used, and
798either will yield the same version number.
799
800=back
801
802For 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
812For any version object which is initialized with multiple decimal
813places (either quoted or if possible v-string), or initialized using
814the L<qv()> operator, the stringified representation is returned in
815a 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
823In order to preserve the meaning of the processed version, the
824normalized representation will always contain at least three sub terms.
825In 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
837Although all mathematical operations on version objects are forbidden
838by default, it is possible to retrieve a number which roughly
839corresponds to the version object through the use of the $obj->numify
840method. For formatting purposes, when displaying a number which
841corresponds a version object, all sub versions are assumed to have
842three decimal places. So for example:
843
844 print $ver->numify; # prints 1.002003
845 print $nver->numify; # prints 1.002
846
847Unlike the stringification operator, there is never any need to append
848trailing zeros to preserve the correct version value.
849
850=back
851
852=over 4
853
854=item * Stringification
855
856In order to mirror as much as possible the existing behavior of ordinary
857$VERSION scalars, the stringification operation will display differently,
858depending on whether the version was initialized as a L<Numeric Version>
859or L<Quoted Version>.
860
861What this means in practice is that if the normal CPAN and Camel rules are
862followed ($VERSION is a floating point number with no more than 3 decimal
863places), the stringified output will be exactly the same as the numified
864output. There will be no visible difference, although the internal
865representation will be different, and the L<Comparison operators> will
866function using the internal coding.
867
868If a version object is initialized using a L<Quoted Version> form, or if
869the number of significant decimal places exceed three, then the stringified
870form will be the L<Normal Form>. The $obj->normal operation can always be
871used to produce the L<Normal Form>, even if the version was originally a
872L<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
883Both cmp and <=> operators perform the same comparison between terms
884(upgrading to a version object automatically). Perl automatically
885generates all of the other comparison operators based on those two.
886In addition to the obvious equalities listed below, appending a single
887trailing 0 term does not change the value of a version for comparison
888purposes. In other words "v1.2" and "1.2.0" will compare as identical.
889
890For 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
900It is probably best to chose either the numeric notation or the string
901notation and stick with it, to reduce confusion. Perl6 version objects
902B<may> only support numeric comparisons. See also L<"Quoting">.
903
904WARNING: Comparing version with unequal numbers of decimal places (whether
905explicitly or implicitly initialized), may yield unexpected results at
906first 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
911For this reason, it is best to use either exclusively L<Numeric Versions> or
912L<Quoted Versions> with multiple decimal places.
913
914=back
915
916=over 4
917
918=item * Logical Operators
919
920If you need to test whether a version object
921has 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
926You can also test whether a version object is an L<Alpha version>, for
927example to prevent the use of some feature not present in the main
928release:
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
938Because of the nature of the Perl parsing and tokenizing routines,
939certain initialization values B<must> be quoted in order to correctly
940parse as the intended version, and additionally, some initial values
941B<must not> be quoted to obtain the intended version.
942
943Except for L<Alpha versions>, any version initialized with something
944that looks like a number (a single decimal place) will be parsed in
945the same way whether or not the term is quoted. In order to be
946compatible with earlier Perl version styles, any use of versions of
947the form 5.006001 will be translated as 5.6.1. In other words, a
948version with a single decimal place will be parsed as implicitly
949having three places between subversions.
950
951The complicating factor is that in bare numbers (i.e. unquoted), the
952underscore is a legal numeric character and is automatically stripped
953by the Perl tokenizer before the version code is called. However, if
954a number containing one or more decimals and an underscore is quoted, i.e.
955not bare, that is considered a L<Alpha Version> and the underscore is
956significant.
957
958If you use a mathematic formula that resolves to a floating point number,
959you are dependent on Perl's conversion routines to yield the version you
960expect. You are pretty safe by dividing by a power of 10, for example,
961but 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
968Perl 5.8.1 and beyond will be able to automatically quote v-strings but
969that 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
977There are two types of Version Objects:
978
979=over 4
980
981=item * Ordinary versions
982
983These are the versions that normal modules will use. Can contain as
984many subversions as required. In particular, those using RCS/CVS can
985use the following:
986
987 $VERSION = version->new(qw$Revision: 2.7 $);
988
989and the current RCS Revision for that file will be inserted
990automatically. If the file has been moved to a branch, the Revision
991will have three or more elements; otherwise, it will have only two.
992This allows you to automatically increment your module version by
993using the Revision number from the primary file in a distribution, see
994L<ExtUtils::MakeMaker/"VERSION_FROM">.
995
996=item * Alpha Versions
997
998For module authors using CPAN, the convention has been to note
999unstable releases with an underscore in the version string, see
1000L<CPAN>. Alpha releases will test as being newer than the more recent
1001stable release, and less than the next stable release. For example:
1002
1003 $alphaver = version->new("12.03_01"); # must be quoted
1004
1005obeys the relationship
1006
1007 12.03 < $alphaver < 12.04
1008
1009Alpha versions with a single decimal place will be treated exactly as if
1010they were L<Numeric Versions>, for parsing purposes. The stringification for
1011alpha versions with a single decimal place may seem surprising, since any
1012trailing zeros will visible. For example, the above $alphaver will print as
1013
1014 12.03_0100
1015
1016which is mathematically equivalent and ASCII sorts exactly the same as
1017without the trailing zeros.
1018
1019Alpha versions with more than a single decimal place will be treated
1020exactly as if they were L<Quoted Versions>, and will display without any
1021trailing (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
1028In addition to the version objects, this modules also replaces the core
1029UNIVERSAL::VERSION function with one that uses version objects for its
1030comparisons. The return from this operator is always the numified form,
1031and the warning message generated includes both the numified and normal
1032forms (for clarity).
1033
1034For 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
1052IMPORTANT NOTE: This may mean that code which searches for a specific
1053string (to determine whether a given module is available) may need to be
1054changed.
1055
1056The replacement UNIVERSAL::VERSION, when used as a function, like this:
1057
1058 print $module->VERSION;
1059
1060will also exclusively return the numified form. Technically, the
1061$module->VERSION function returns a string (PV) that can be converted to a
1062number following the normal Perl rules, when used in a numeric context.
1063
1064=head1 SUBCLASSING
1065
1066This module is specifically designed and tested to be easily subclassed.
1067In practice, you only need to override the methods you want to change, but
1068you have to take some care when overriding new() (since that is where all
1069of the parsing takes place). For example, this is a perfect acceptable
1070derived 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
1083See also L<version::AlphaBeta> on CPAN for an alternate representation of
1084version strings.
1085
1086=head1 EXPORT
1087
1088qv - quoted version initialization operator
1089
1090=head1 AUTHOR
1091
1092John Peacock E<lt>jpeacock@cpan.orgE<gt>
1093
1094=head1 SEE ALSO
1095
1096L<perl>.
1097
1098=cut