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