3 version::Internal - Perl extension for Version Objects
7 Overloaded version objects for all modern versions of Perl. This documents
8 the internal data representation and underlying code for version.pm. See
9 L<version.pod> for daily usage. This document is only useful for users
10 writing a subclass of version.pm or interested in the gory details.
12 =head1 What IS a version
14 For the purposes of this module, a version "number" is a sequence of
15 positive integer values separated by one or more decimal points and
16 optionally a single underscore. This corresponds to what Perl itself
17 uses for a version, as well as extending the "version as number" that
18 is discussed in the various editions of the Camel book.
20 There are actually two distinct kinds of version objects:
24 =item * Decimal Versions
26 Any version which "looks like a number", see L<Decimal Versions>. This
27 also includes versions with a single decimal point and a single embedded
28 underscore, see L<Decimal Alpha Versions>, even though these must be quoted
29 to preserve the underscore formatting.
31 =item * Dotted-Decimal Versions
33 Also referred to as "Dotted-Integer", these contains more than one decimal
34 point and may have an optional embedded underscore, see L<Dotted-Decimal
35 Versions>. This is what is commonly used in most open source software as
36 the "external" version (the one used as part of the tag or tarfile name).
37 A leading 'v' character is now required and will warn if it missing.
41 Both of these methods will produce similar version objects, in that
42 the default stringification will yield the version L<Normal Form> only
45 $v = version->new(1.002); # 1.002, but compares like 1.2.0
46 $v = version->new(1.002003); # 1.002003
47 $v2 = version->new("v1.2.3"); # v1.2.3
49 In specific, version numbers initialized as L<Decimal Versions> will
50 stringify as they were originally created (i.e. the same string that was
51 passed to C<new()>. Version numbers initialized as L<Dotted-Decimal Versions>
52 will be stringified as L<Normal Form>.
54 =head2 Decimal Versions
56 These correspond to historical versions of Perl itself prior to 5.6.0,
57 as well as all other modules which follow the Camel rules for the
58 $VERSION scalar. A Decimal version is initialized with what looks like
59 a floating point number. Leading zeros B<are> significant and trailing
60 zeros are implied so that a minimum of three places is maintained
61 between subversions. What this means is that any subversion (digits
62 to the right of the decimal place) that contains less than three digits
63 will have trailing zeros added to make up the difference, but only for
64 purposes of comparison with other version objects. For example:
66 # Prints Equivalent to
67 $v = version->new( 1.2); # 1.2 v1.200.0
68 $v = version->new( 1.02); # 1.02 v1.20.0
69 $v = version->new( 1.002); # 1.002 v1.2.0
70 $v = version->new( 1.0023); # 1.0023 v1.2.300
71 $v = version->new( 1.00203); # 1.00203 v1.2.30
72 $v = version->new( 1.002003); # 1.002003 v1.2.3
74 All of the preceding examples are true whether or not the input value is
75 quoted. The important feature is that the input value contains only a
76 single decimal. See also L<Alpha Versions> for how to handle
78 IMPORTANT NOTE: As shown above, if your Decimal version contains more
79 than 3 significant digits after the decimal place, it will be split on
80 each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need
81 to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation.
82 Any trailing zeros are ignored for mathematical comparison purposes.
84 =head2 Dotted-Decimal Versions
86 These are the newest form of versions, and correspond to Perl's own
87 version style beginning with 5.6.0. Starting with Perl 5.10.0,
88 and most likely Perl 6, this is likely to be the preferred form. This
89 method normally requires that the input parameter be quoted, although
90 Perl's after 5.8.1 can use v-strings as a special form of quoting, but
91 this is highly discouraged.
93 Unlike L<Decimal Versions>, Dotted-Decimal Versions have more than
94 a single decimal point, e.g.:
97 $v = version->new( "v1.200"); # v1.200.0
98 $v = version->new("v1.20.0"); # v1.20.0
99 $v = qv("v1.2.3"); # v1.2.3
100 $v = qv("1.2.3"); # v1.2.3
101 $v = qv("1.20"); # v1.20.0
103 In general, Dotted-Decimal Versions permit the greatest amount of freedom
104 to specify a version, whereas Decimal Versions enforce a certain
105 uniformity. See also L<New Operator> for an additional method of
106 initializing version objects.
108 Just like L<Decimal Versions>, Dotted-Decimal Versions can be used as
111 =head2 Decimal Alpha Versions
113 The one time that a Decimal version must be quoted is when a alpha form is
114 used with an otherwise Decimal version (i.e. a single decimal point). This
115 is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
116 versions for automatic updating purposes. Since some developers have used
117 only two significant decimal places for their non-alpha releases, the
118 version object will automatically take that into account if the initializer
119 is quoted. For example Module::Example was released to CPAN with the
120 following sequence of $VERSION's:
122 # $VERSION Stringified
130 The stringified form of Decimal versions will always be the same string
131 that was used to initialize the version object.
133 =head1 High level design
135 =head2 version objects
137 version.pm provides an overloaded version object that is designed to both
138 encapsulate the author's intended $VERSION assignment as well as make it
139 completely natural to use those objects as if they were numbers (e.g. for
140 comparisons). To do this, a version object contains both the original
141 representation as typed by the author, as well as a parsed representation
142 to ease comparisons. Version objects employ L<overload> methods to
143 simplify code that needs to compare, print, etc the objects.
145 The internal structure of version objects is a blessed hash with several
149 'original' => 'v1.2.3_4',
164 A faithful representation of the value used to initialize this version
165 object. The only time this will not be precisely the same characters
166 that exist in the source file is if a short dotted-decimal version like
167 v1.2 was used (in which case it will contain 'v1.2'). This form is
168 B<STRONGLY> discouraged, in that it will confuse you and your users.
172 A boolean that denotes whether this is a decimal or dotted-decimal version.
177 A boolean that denotes whether this is an alpha version. NOTE: that the
178 underscore can can only appear in the last position. See L<is_alpha>.
182 An array of non-negative integers that is used for comparison purposes with
183 other version objects.
187 =head2 Replacement UNIVERSAL::VERSION
189 In addition to the version objects, this modules also replaces the core
190 UNIVERSAL::VERSION function with one that uses version objects for its
191 comparisons. The return from this operator is always the stringified form
192 as a simple scalar (i.e. not an object), but the warning message generated
193 includes either the stringified form or the normal form, depending on how
202 $VERSION = "v1.3.5"; # works with all Perl's (since it is quoted)
207 print $Foo::VERSION; # prints 1.2
209 print $Bar::VERSION; # prints 1.003005
212 print $@; # prints "foo version 10 required..."
213 eval "use foo 1.3.5; # work in Perl 5.6.1 or better
214 print $@; # prints "foo version 1.3.5 required..."
216 eval "use bar 1.3.6";
217 print $@; # prints "bar version 1.3.6 required..."
218 eval "use bar 1.004"; # note Decimal version
219 print $@; # prints "bar version 1.004 required..."
222 IMPORTANT NOTE: This may mean that code which searches for a specific
223 string (to determine whether a given module is available) may need to be
224 changed. It is always better to use the built-in comparison implicit in
225 C<use> or C<require>, rather than manually poking at C<class->VERSION>
226 and then doing a comparison yourself.
228 The replacement UNIVERSAL::VERSION, when used as a function, like this:
230 print $module->VERSION;
232 will also exclusively return the stringified form. See L<Stringification>
235 =head1 Usage question
237 =head2 Using modules that use version.pm
239 As much as possible, the version.pm module remains compatible with all
240 current code. However, if your module is using a module that has defined
241 C<$VERSION> using the version class, there are a couple of things to be
242 aware of. For purposes of discussion, we will assume that we have the
243 following module installed:
246 use version; $VERSION = qv('1.2.2');
247 ...module code here...
252 =item Decimal versions always work
256 use Example 1.002003;
258 will always work correctly. The C<use> will perform an automatic
259 C<$VERSION> comparison using the floating point number given as the first
260 term after the module name (e.g. above 1.002.003). In this case, the
261 installed module is too old for the requested line, so you would see an
264 Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
266 =item Dotted-Decimal version work sometimes
268 With Perl >= 5.6.2, you can also use a line like this:
272 and it will again work (i.e. give the error message as above), even with
273 releases of Perl which do not normally support v-strings (see L<What about
274 v-strings> below). This has to do with that fact that C<use> only checks
275 to see if the second term I<looks like a number> and passes that to the
276 replacement L<UNIVERSAL::VERSION>. This is not true in Perl 5.005_04,
277 however, so you are B<strongly encouraged> to always use a Decimal version
278 in your code, even for those versions of Perl which support the Dotted-Decimal
283 =head2 Object Methods
285 Overloading has been used with version objects to provide a natural
286 interface for their use. All mathematical operations are forbidden,
287 since they don't make any sense for base version objects. Consequently,
288 there is no overloaded numification available. If you want to use a
289 version object in a Decimal context for some reason, see the L<numify>
296 Like all OO interfaces, the new() operator is used to initialize
297 version objects. One way to increment versions when programming is to
298 use the CVS variable $Revision, which is automatically incremented by
299 CVS every time the file is committed to the repository.
301 In order to facilitate this feature, the following
302 code can be employed:
304 $VERSION = version->new(qw$Revision: 2.7 $);
306 and the version object will be created as if the following code
309 $VERSION = version->new("v2.7");
311 In other words, the version will be automatically parsed out of the
312 string, and it will be quoted to preserve the meaning CVS normally
313 carries for versions. The CVS $Revision$ increments differently from
314 Decimal versions (i.e. 1.10 follows 1.9), so it must be handled as if
315 it were a L<Dotted-Decimal Version>.
317 A new version object can be created as a copy of an existing version
318 object, either as a class method:
320 $v1 = version->new(12.3);
321 $v2 = version->new($v1);
323 or as an object method:
325 $v1 = version->new(12.3);
326 $v2 = $v1->new(12.3);
328 and in each case, $v1 and $v2 will be identical. NOTE: if you create
329 a new object using an existing object like this:
333 the new object B<will not> be a clone of the existing object. In the
334 example case, $v2 will be an empty object of the same type as $v1.
342 An alternate way to create a new version object is through the exported
343 qv() sub. This is not strictly like other q? operators (like qq, qw),
344 in that the only delimiters supported are parentheses (or spaces). It is
345 the best way to initialize a short version without triggering the floating
346 point interpretation. For example:
348 $v1 = qv(1.2); # v1.2.0
349 $v2 = qv("1.2"); # also v1.2.0
351 As you can see, either a bare number or a quoted string can usually
352 be used interchangably, except in the case of a trailing zero, which
353 must be quoted to be converted properly. For this reason, it is strongly
354 recommended that all initializers to qv() be quoted strings instead of
357 To prevent the C<qv()> function from being exported to the caller's namespace,
358 either use version with a null parameter:
362 or just require version, like this:
366 Both methods will prevent the import() method from firing and exporting the
367 C<qv()> sub. This is true of subclasses of version as well, see
368 L<SUBCLASSING> for details.
372 For the subsequent examples, the following three objects will be used:
374 $ver = version->new("1.2.3.4"); # see "Quoting" below
375 $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
376 $nver = version->new(1.002); # see "Decimal Versions" above
382 For any version object which is initialized with multiple decimal
383 places (either quoted or if possible v-string), or initialized using
384 the L<qv()> operator, the stringified representation is returned in
385 a normalized or reduced form (no extraneous zeros), and with a leading 'v':
387 print $ver->normal; # prints as v1.2.3.4
388 print $ver->stringify; # ditto
390 print $nver->normal; # prints as v1.2.0
391 print $nver->stringify; # prints as 1.002, see "Stringification"
393 In order to preserve the meaning of the processed version, the
394 normalized representation will always contain at least three sub terms.
395 In other words, the following is guaranteed to always be true:
397 my $newver = version->new($ver->stringify);
398 if ($newver eq $ver ) # always true
407 Although all mathematical operations on version objects are forbidden
408 by default, it is possible to retrieve a number which corresponds
409 to the version object through the use of the $obj->numify
410 method. For formatting purposes, when displaying a number which
411 corresponds a version object, all sub versions are assumed to have
412 three decimal places. So for example:
414 print $ver->numify; # prints 1.002003004
415 print $nver->numify; # prints 1.002
417 Unlike the stringification operator, there is never any need to append
418 trailing zeros to preserve the correct version value.
424 =item * Stringification
426 The default stringification for version objects returns exactly the same
427 string as was used to create it, whether you used C<new()> or C<qv()>,
428 with one exception. The sole exception is if the object was created using
429 C<qv()> and the initializer did not have two decimal places or a leading
430 'v' (both optional), then the stringified form will have a leading 'v'
431 prepended, in order to support round-trip processing.
435 Initialized as Stringifies to
436 ============== ==============
437 version->new("1.2") 1.2
438 version->new("v1.2") v1.2
441 qv("1.2") v1.2 ### exceptional case
443 See also L<UNIVERSAL::VERSION>, as this also returns the stringified form
444 when used as a class method.
446 IMPORTANT NOTE: There is one exceptional cases shown in the above table
447 where the "initializer" is not stringwise equivalent to the stringified
448 representation. If you use the C<qv()> operator on a version without a
449 leading 'v' B<and> with only a single decimal place, the stringified output
450 will have a leading 'v', to preserve the sense. See the L<qv()> operator
453 IMPORTANT NOTE 2: Attempting to bypass the normal stringification rules by
454 manually applying L<numify()> and L<normal()> will sometimes yield
457 print version->new(version->new("v1.0")->numify)->normal; # v1.0.0
459 The reason for this is that the L<numify()> operator will turn "v1.0"
460 into the equivalent string "1.000000". Forcing the outer version object
461 to L<normal()> form will display the mathematically equivalent "v1.0.0".
463 As the example in L<new()> shows, you can always create a copy of an
464 existing version object with the same value by the very compact:
468 and be assured that both C<$v1> and C<$v2> will be completely equivalent,
469 down to the same internal representation as well as stringification.
475 =item * Comparison operators
477 Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between
478 terms (upgrading to a version object automatically). Perl automatically
479 generates all of the other comparison operators based on those two.
480 In addition to the obvious equalities listed below, appending a single
481 trailing 0 term does not change the value of a version for comparison
482 purposes. In other words "v1.2" and "1.2.0" will compare as identical.
484 For example, the following relations hold:
486 As Number As String Truth Value
487 ------------- ---------------- -----------
488 $ver > 1.0 $ver gt "1.0" true
489 $ver < 2.5 $ver lt true
490 $ver != 1.3 $ver ne "1.3" true
491 $ver == 1.2 $ver eq "1.2" false
492 $ver == 1.2.3.4 $ver eq "1.2.3.4" see discussion below
494 It is probably best to chose either the Decimal notation or the string
495 notation and stick with it, to reduce confusion. Perl6 version objects
496 B<may> only support Decimal comparisons. See also L<Quoting>.
498 WARNING: Comparing version with unequal numbers of decimal points (whether
499 explicitly or implicitly initialized), may yield unexpected results at
500 first glance. For example, the following inequalities hold:
502 version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0
503 version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
505 For this reason, it is best to use either exclusively L<Decimal Versions> or
506 L<Dotted-Decimal Versions> with multiple decimal points.
512 =item * Logical Operators
514 If you need to test whether a version object
515 has been initialized, you can simply test it directly:
517 $vobj = version->new($something);
518 if ( $vobj ) # true only if $something was non-blank
520 You can also test whether a version object is an L<Alpha version>, for
521 example to prevent the use of some feature not present in the main
524 $vobj = version->new("1.2_3"); # MUST QUOTE
526 if ( $vobj->is_alpha ) # True
532 Because of the nature of the Perl parsing and tokenizing routines,
533 certain initialization values B<must> be quoted in order to correctly
534 parse as the intended version, especially when using the L<qv()> operator.
535 In all cases, a floating point number passed to version->new() will be
536 identically converted whether or not the value itself is quoted. This is
537 not true for L<qv()>, however, when trailing zeros would be stripped on
538 an unquoted input, which would result in a very different version object.
540 In addition, in order to be compatible with earlier Perl version styles,
541 any use of versions of the form 5.006001 will be translated as v5.6.1.
542 In other words, a version with a single decimal point will be parsed as
543 implicitly having three digits between subversions, but only for internal
546 The complicating factor is that in bare numbers (i.e. unquoted), the
547 underscore is a legal Decimal character and is automatically stripped
548 by the Perl tokenizer before the version code is called. However, if
549 a number containing one or more decimals and an underscore is quoted, i.e.
550 not bare, that is considered a L<Alpha Version> and the underscore is
553 If you use a mathematic formula that resolves to a floating point number,
554 you are dependent on Perl's conversion routines to yield the version you
555 expect. You are pretty safe by dividing by a power of 10, for example,
556 but other operations are not likely to be what you intend. For example:
558 $VERSION = version->new((qw$Revision: 1.4)[1]/10);
559 print $VERSION; # yields 0.14
560 $V2 = version->new(100/9); # Integer overflow in decimal number
561 print $V2; # yields something like 11.111.111.100
563 Perl 5.8.1 and beyond will be able to automatically quote v-strings but
564 that is not possible in earlier versions of Perl. In other words:
566 $version = version->new("v2.5.4"); # legal in all versions of Perl
567 $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1
571 This module is specifically designed and tested to be easily subclassed.
572 In practice, you only need to override the methods you want to change, but
573 you have to take some care when overriding new() (since that is where all
574 of the parsing takes place). For example, this is a perfect acceptable
582 # perform any special input handling here
583 $obj = $self->SUPER::new($n);
584 # and/or add additional hash elements here
588 See also L<version::AlphaBeta> on CPAN for an alternate representation of
591 B<NOTE:> Although the L<qv> operator is not a true class method, but rather a
592 function exported into the caller's namespace, a subclass of version will
593 inherit an import() function which will perform the correct magic on behalf
598 qv - Dotted-Decimal Version initialization operator
602 John Peacock E<lt>jpeacock@cpan.orgE<gt>