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