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