This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
sv_dup
[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
RGS
263
264=back
265
266For the subsequent examples, the following three objects will be used:
267
268 $ver = version->new("1.2.3.4"); # see "Quoting" below
269 $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
43eaf59d 270 $nver = version->new(1.002); # see "Numeric Versions" above
cb5772bb
RGS
271
272=over 4
273
274=item * Normal Form
275
276For any version object which is initialized with multiple decimal
277places (either quoted or if possible v-string), or initialized using
278the L<qv()> operator, the stringified representation is returned in
279a normalized or reduced form (no extraneous zeros), and with a leading 'v':
280
43eaf59d 281 print $ver->normal; # prints as v1.2.3.4
cb5772bb
RGS
282 print $ver->stringify; # ditto
283 print $ver; # ditto
284 print $nver->normal; # prints as v1.2.0
285 print $nver->stringify; # prints as 1.002, see "Stringification"
286
287In order to preserve the meaning of the processed version, the
288normalized representation will always contain at least three sub terms.
289In other words, the following is guaranteed to always be true:
290
291 my $newver = version->new($ver->stringify);
292 if ($newver eq $ver ) # always true
293 {...}
294
295=back
296
297=over 4
298
299=item * Numification
300
301Although all mathematical operations on version objects are forbidden
43eaf59d
SP
302by default, it is possible to retrieve a number which corresponds
303to the version object through the use of the $obj->numify
cb5772bb
RGS
304method. For formatting purposes, when displaying a number which
305corresponds a version object, all sub versions are assumed to have
306three decimal places. So for example:
307
43eaf59d 308 print $ver->numify; # prints 1.002003004
cb5772bb
RGS
309 print $nver->numify; # prints 1.002
310
311Unlike the stringification operator, there is never any need to append
312trailing zeros to preserve the correct version value.
313
314=back
315
316=over 4
317
318=item * Stringification
319
320In order to mirror as much as possible the existing behavior of ordinary
321$VERSION scalars, the stringification operation will display differently,
322depending on whether the version was initialized as a L<Numeric Version>
7de739db 323or L<Extended Version>.
cb5772bb
RGS
324
325What this means in practice is that if the normal CPAN and Camel rules are
326followed ($VERSION is a floating point number with no more than 3 decimal
43eaf59d 327points), the stringified output will be exactly the same as the numified
cb5772bb
RGS
328output. There will be no visible difference, although the internal
329representation will be different, and the L<Comparison operators> will
330function using the internal coding.
331
43eaf59d
SP
332If a version object is initialized using a L<Extended Version> form, then
333the stringified form will be the L<Normal Form>. The $obj->normal
334operation can always be used to produce the L<Normal Form>, even if the
335version was originally a L<Numeric Version>.
cb5772bb 336
43eaf59d 337 print $ver->stringify; # prints v1.2.3.4
cb5772bb
RGS
338 print $nver->stringify; # prints 1.002
339
340=back
341
342=over 4
343
344=item * Comparison operators
345
43eaf59d
SP
346Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between
347terms (upgrading to a version object automatically). Perl automatically
cb5772bb
RGS
348generates all of the other comparison operators based on those two.
349In addition to the obvious equalities listed below, appending a single
350trailing 0 term does not change the value of a version for comparison
351purposes. In other words "v1.2" and "1.2.0" will compare as identical.
352
353For example, the following relations hold:
354
43eaf59d
SP
355 As Number As String Truth Value
356 ------------- ---------------- -----------
357 $ver > 1.0 $ver gt "1.0" true
358 $ver < 2.5 $ver lt true
359 $ver != 1.3 $ver ne "1.3" true
360 $ver == 1.2 $ver eq "1.2" false
361 $ver == 1.2.3.4 $ver eq "1.2.3.4" see discussion below
cb5772bb
RGS
362
363It is probably best to chose either the numeric notation or the string
364notation and stick with it, to reduce confusion. Perl6 version objects
43eaf59d 365B<may> only support numeric comparisons. See also L<Quoting>.
cb5772bb 366
43eaf59d 367WARNING: Comparing version with unequal numbers of decimal points (whether
cb5772bb
RGS
368explicitly or implicitly initialized), may yield unexpected results at
369first glance. For example, the following inequalities hold:
370
371 version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0
372 version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
373
374For this reason, it is best to use either exclusively L<Numeric Versions> or
43eaf59d 375L<Extended Versions> with multiple decimal points.
cb5772bb
RGS
376
377=back
378
379=over 4
380
381=item * Logical Operators
382
383If you need to test whether a version object
384has been initialized, you can simply test it directly:
385
386 $vobj = version->new($something);
387 if ( $vobj ) # true only if $something was non-blank
388
389You can also test whether a version object is an L<Alpha version>, for
390example to prevent the use of some feature not present in the main
391release:
392
393 $vobj = version->new("1.2_3"); # MUST QUOTE
394 ...later...
395 if ( $vobj->is_alpha ) # True
396
397=back
398
399=head2 Quoting
400
401Because of the nature of the Perl parsing and tokenizing routines,
402certain initialization values B<must> be quoted in order to correctly
43eaf59d
SP
403parse as the intended version, especially when using the L<qv()> operator.
404In all cases, a floating point number passed to version->new() will be
405identically converted whether or not the value itself is quoted. This is
406not true for L<qv()>, however, when trailing zeros would be stripped on
407an unquoted input, which would result in a very different version object.
408
409In addition, in order to be compatible with earlier Perl version styles,
410any use of versions of the form 5.006001 will be translated as v5.6.1.
411In other words, a version with a single decimal point will be parsed as
412implicitly having three digits between subversions, but only for internal
413comparison purposes.
cb5772bb
RGS
414
415The complicating factor is that in bare numbers (i.e. unquoted), the
416underscore is a legal numeric character and is automatically stripped
417by the Perl tokenizer before the version code is called. However, if
418a number containing one or more decimals and an underscore is quoted, i.e.
419not bare, that is considered a L<Alpha Version> and the underscore is
420significant.
421
422If you use a mathematic formula that resolves to a floating point number,
423you are dependent on Perl's conversion routines to yield the version you
424expect. You are pretty safe by dividing by a power of 10, for example,
425but other operations are not likely to be what you intend. For example:
426
427 $VERSION = version->new((qw$Revision: 1.4)[1]/10);
428 print $VERSION; # yields 0.14
429 $V2 = version->new(100/9); # Integer overflow in decimal number
430 print $V2; # yields something like 11.111.111.100
431
432Perl 5.8.1 and beyond will be able to automatically quote v-strings but
433that is not possible in earlier versions of Perl. In other words:
434
435 $version = version->new("v2.5.4"); # legal in all versions of Perl
436 $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1
437
43eaf59d
SP
438=head2 What about v-strings?
439
440Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
441of bytes was introduced, called v-strings. They were intended to be an
442easy way to enter, for example, Unicode strings (which contain two bytes
443per character). Some programs have used them to encode printer control
444characters (e.g. CRLF). They were also intended to be used for $VERSION,
445but their use as such has been problematic from the start.
446
447There are two ways to enter v-strings: a bare number with two or more
448decimal points, or a bare number with one or more decimal points and a
449leading 'v' character (also bare). For example:
450
451 $vs1 = 1.2.3; # encoded as \1\2\3
452 $vs2 = v1.2; # encoded as \1\2
453
454However, the use of v-strings to initialize version objects with this
455module is only possible with Perl 5.8.1 or better (which contain special
456code to enable it). Their use is B<strongly> discouraged in all
457circumstances (especially the leading 'v' style), since the meaning will
458change depending on which Perl you are running. It is better to directly
459use L<"Extended Versions"> to ensure the proper interpretation.
460
cb5772bb
RGS
461
462=head2 Types of Versions Objects
463
464There are two types of Version Objects:
465
466=over 4
467
468=item * Ordinary versions
469
470These are the versions that normal modules will use. Can contain as
471many subversions as required. In particular, those using RCS/CVS can
472use the following:
473
474 $VERSION = version->new(qw$Revision: 2.7 $);
475
476and the current RCS Revision for that file will be inserted
477automatically. If the file has been moved to a branch, the Revision
478will have three or more elements; otherwise, it will have only two.
479This allows you to automatically increment your module version by
480using the Revision number from the primary file in a distribution, see
481L<ExtUtils::MakeMaker/"VERSION_FROM">.
482
483=item * Alpha Versions
484
485For module authors using CPAN, the convention has been to note
486unstable releases with an underscore in the version string, see
487L<CPAN>. Alpha releases will test as being newer than the more recent
488stable release, and less than the next stable release. For example:
489
490 $alphaver = version->new("12.03_01"); # must be quoted
491
492obeys the relationship
493
494 12.03 < $alphaver < 12.04
495
43eaf59d 496Alpha versions with a single decimal point will be treated exactly as if
cb5772bb 497they were L<Numeric Versions>, for parsing purposes. The stringification for
43eaf59d 498alpha versions with a single decimal point may seem surprising, since any
cb5772bb
RGS
499trailing zeros will visible. For example, the above $alphaver will print as
500
501 12.03_0100
502
503which is mathematically equivalent and ASCII sorts exactly the same as
504without the trailing zeros.
505
43eaf59d 506Alpha versions with more than a single decimal point will be treated
7de739db 507exactly as if they were L<Extended Versions>, and will display without any
cb5772bb
RGS
508trailing (or leading) zeros, in the L<Version Normal> form. For example,
509
510 $newver = version->new("12.3.1_1");
511 print $newver; # v12.3.1_1
512
513=head2 Replacement UNIVERSAL::VERSION
514
515In addition to the version objects, this modules also replaces the core
516UNIVERSAL::VERSION function with one that uses version objects for its
517comparisons. The return from this operator is always the numified form,
518and the warning message generated includes both the numified and normal
519forms (for clarity).
520
521For example:
522
523 package Foo;
524 $VERSION = 1.2;
525
526 package Bar;
527 $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
528
529 package main;
530 use version;
531
532 print $Foo::VERSION; # prints 1.2
533
534 print $Bar::VERSION; # prints 1.003005
535
536 eval "use CGI 10"; # some far future release
537 print $@; # prints "CGI version 10 (10.0.0) required..."
538
539IMPORTANT NOTE: This may mean that code which searches for a specific
540string (to determine whether a given module is available) may need to be
541changed.
542
543The replacement UNIVERSAL::VERSION, when used as a function, like this:
544
545 print $module->VERSION;
546
547will also exclusively return the numified form. Technically, the
548$module->VERSION function returns a string (PV) that can be converted to a
549number following the normal Perl rules, when used in a numeric context.
550
551=head1 SUBCLASSING
552
553This module is specifically designed and tested to be easily subclassed.
554In practice, you only need to override the methods you want to change, but
555you have to take some care when overriding new() (since that is where all
556of the parsing takes place). For example, this is a perfect acceptable
557derived class:
558
559 package myversion;
560 use base version;
561 sub new {
562 my($self,$n)=@_;
563 my $obj;
564 # perform any special input handling here
565 $obj = $self->SUPER::new($n);
566 # and/or add additional hash elements here
567 return $obj;
568 }
569
570See also L<version::AlphaBeta> on CPAN for an alternate representation of
571version strings.
572
7de739db
SP
573B<NOTE:> the L<qv> operator is not a class method and will not be inherited
574in the same way as the other methods. L<qv> will always return an object of
575type L<version> and not an object in the derived class. If you need to
576have L<qv> return an object in your derived class, add something like this:
cb5772bb 577
7de739db 578 *::qv = sub { return bless version::qv(shift), __PACKAGE__ };
cb5772bb 579
7de739db 580as seen in the test file F<t/02derived.t>.
cb5772bb
RGS
581
582=head1 EXPORT
583
7de739db 584qv - Extended Version initialization operator
cb5772bb
RGS
585
586=head1 AUTHOR
587
588John Peacock E<lt>jpeacock@cpan.orgE<gt>
589
590=head1 SEE ALSO
591
592L<perl>.
593
594=cut