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<version/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
109 L<version/Alpha Versions>.
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<version/What about v-strings> below). This has to do with that fact that C<use> only checks
274 to see if the second term I<looks like a number> and passes that to the
275 replacement L<UNIVERSAL::VERSION>. This is not true in Perl 5.005_04,
276 however, so you are B<strongly encouraged> to always use a Decimal version
277 in your code, even for those versions of Perl which support the Dotted-Decimal
282 =head2 Object Methods
284 Overloading has been used with version objects to provide a natural
285 interface for their use. All mathematical operations are forbidden,
286 since they don't make any sense for base version objects. Consequently,
287 there is no overloaded numification available. If you want to use a
288 version object in a Decimal context for some reason, see the L<numify>
295 Like all OO interfaces, the new() operator is used to initialize
296 version objects. One way to increment versions when programming is to
297 use the CVS variable $Revision, which is automatically incremented by
298 CVS every time the file is committed to the repository.
300 In order to facilitate this feature, the following
301 code can be employed:
303 $VERSION = version->new(qw$Revision: 2.7 $);
305 and the version object will be created as if the following code
308 $VERSION = version->new("v2.7");
310 In other words, the version will be automatically parsed out of the
311 string, and it will be quoted to preserve the meaning CVS normally
312 carries for versions. The CVS $Revision$ increments differently from
313 Decimal versions (i.e. 1.10 follows 1.9), so it must be handled as if
314 it were a Dotted-Decimal Version.
316 A new version object can be created as a copy of an existing version
317 object, either as a class method:
319 $v1 = version->new(12.3);
320 $v2 = version->new($v1);
322 or as an object method:
324 $v1 = version->new(12.3);
325 $v2 = $v1->new(12.3);
327 and in each case, $v1 and $v2 will be identical. NOTE: if you create
328 a new object using an existing object like this:
332 the new object B<will not> be a clone of the existing object. In the
333 example case, $v2 will be an empty object of the same type as $v1.
341 An alternate way to create a new version object is through the exported
342 qv() sub. This is not strictly like other q? operators (like qq, qw),
343 in that the only delimiters supported are parentheses (or spaces). It is
344 the best way to initialize a short version without triggering the floating
345 point interpretation. For example:
347 $v1 = qv(1.2); # v1.2.0
348 $v2 = qv("1.2"); # also v1.2.0
350 As you can see, either a bare number or a quoted string can usually
351 be used interchangably, except in the case of a trailing zero, which
352 must be quoted to be converted properly. For this reason, it is strongly
353 recommended that all initializers to qv() be quoted strings instead of
356 To prevent the C<qv()> function from being exported to the caller's namespace,
357 either use version with a null parameter:
361 or just require version, like this:
365 Both methods will prevent the import() method from firing and exporting the
366 C<qv()> sub. This is true of subclasses of version as well, see
367 L<SUBCLASSING> for details.
371 For the subsequent examples, the following three objects will be used:
373 $ver = version->new("1.2.3.4"); # see "Quoting" below
374 $alpha = version->new("1.2.3_4"); # see "<version/Alpha versions" below
375 $nver = version->new(1.002); # see "Decimal Versions" above
381 For any version object which is initialized with multiple decimal
382 places (either quoted or if possible v-string), or initialized using
383 the L<qv>() operator, the stringified representation is returned in
384 a normalized or reduced form (no extraneous zeros), and with a leading 'v':
386 print $ver->normal; # prints as v1.2.3.4
387 print $ver->stringify; # ditto
389 print $nver->normal; # prints as v1.2.0
390 print $nver->stringify; # prints as 1.002, see "Stringification"
392 In order to preserve the meaning of the processed version, the
393 normalized representation will always contain at least three sub terms.
394 In other words, the following is guaranteed to always be true:
396 my $newver = version->new($ver->stringify);
397 if ($newver eq $ver ) # always true
406 Although all mathematical operations on version objects are forbidden
407 by default, it is possible to retrieve a number which corresponds
408 to the version object through the use of the $obj->numify
409 method. For formatting purposes, when displaying a number which
410 corresponds a version object, all sub versions are assumed to have
411 three decimal places. So for example:
413 print $ver->numify; # prints 1.002003004
414 print $nver->numify; # prints 1.002
416 Unlike the stringification operator, there is never any need to append
417 trailing zeros to preserve the correct version value.
423 =item Stringification
425 The default stringification for version objects returns exactly the same
426 string as was used to create it, whether you used C<new()> or C<qv()>,
427 with one exception. The sole exception is if the object was created using
428 C<qv()> and the initializer did not have two decimal places or a leading
429 'v' (both optional), then the stringified form will have a leading 'v'
430 prepended, in order to support round-trip processing.
434 Initialized as Stringifies to
435 ============== ==============
436 version->new("1.2") 1.2
437 version->new("v1.2") v1.2
440 qv("1.2") v1.2 ### exceptional case
442 See also L<UNIVERSAL::VERSION>, as this also returns the stringified form
443 when used as a class method.
445 IMPORTANT NOTE: There is one exceptional cases shown in the above table
446 where the "initializer" is not stringwise equivalent to the stringified
447 representation. If you use the C<qv>() operator on a version without a
448 leading 'v' B<and> with only a single decimal place, the stringified output
449 will have a leading 'v', to preserve the sense. See the L<qv>() operator
452 IMPORTANT NOTE 2: Attempting to bypass the normal stringification rules by
453 manually applying L<numify>() and L<normal>() will sometimes yield
456 print version->new(version->new("v1.0")->numify)->normal; # v1.0.0
458 The reason for this is that the L<numify>() operator will turn "v1.0"
459 into the equivalent string "1.000000". Forcing the outer version object
460 to L<normal>() form will display the mathematically equivalent "v1.0.0".
462 As the example in L<new>() shows, you can always create a copy of an
463 existing version object with the same value by the very compact:
467 and be assured that both C<$v1> and C<$v2> will be completely equivalent,
468 down to the same internal representation as well as stringification.
474 =item Comparison operators
476 Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between
477 terms (upgrading to a version object automatically). Perl automatically
478 generates all of the other comparison operators based on those two.
479 In addition to the obvious equalities listed below, appending a single
480 trailing 0 term does not change the value of a version for comparison
481 purposes. In other words "v1.2" and "1.2.0" will compare as identical.
483 For example, the following relations hold:
485 As Number As String Truth Value
486 ------------- ---------------- -----------
487 $ver > 1.0 $ver gt "1.0" true
488 $ver < 2.5 $ver lt true
489 $ver != 1.3 $ver ne "1.3" true
490 $ver == 1.2 $ver eq "1.2" false
491 $ver == 1.2.3.4 $ver eq "1.2.3.4" see discussion below
493 It is probably best to chose either the Decimal notation or the string
494 notation and stick with it, to reduce confusion. Perl6 version objects
495 B<may> only support Decimal comparisons. See also L<Quoting>.
497 WARNING: Comparing version with unequal numbers of decimal points (whether
498 explicitly or implicitly initialized), may yield unexpected results at
499 first glance. For example, the following inequalities hold:
501 version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0
502 version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
504 For this reason, it is best to use either exclusively L<Decimal Versions> or
505 L<Dotted-Decimal Versions> with multiple decimal points.
511 =item Logical Operators
513 If you need to test whether a version object
514 has been initialized, you can simply test it directly:
516 $vobj = version->new($something);
517 if ( $vobj ) # true only if $something was non-blank
519 You can also test whether a version object is an L<version/Alpha version>, for
520 example to prevent the use of some feature not present in the main
523 $vobj = version->new("1.2_3"); # MUST QUOTE
525 if ( $vobj->is_alpha ) # True
531 Because of the nature of the Perl parsing and tokenizing routines,
532 certain initialization values B<must> be quoted in order to correctly
533 parse as the intended version, especially when using the L<qv>() operator.
534 In all cases, a floating point number passed to version->new() will be
535 identically converted whether or not the value itself is quoted. This is
536 not true for L<qv>(), however, when trailing zeros would be stripped on
537 an unquoted input, which would result in a very different version object.
539 In addition, in order to be compatible with earlier Perl version styles,
540 any use of versions of the form 5.006001 will be translated as v5.6.1.
541 In other words, a version with a single decimal point will be parsed as
542 implicitly having three digits between subversions, but only for internal
545 The complicating factor is that in bare numbers (i.e. unquoted), the
546 underscore is a legal Decimal character and is automatically stripped
547 by the Perl tokenizer before the version code is called. However, if
548 a number containing one or more decimals and an underscore is quoted, i.e.
549 not bare, that is considered an L<version/Alpha version> and the underscore is
552 If you use a mathematic formula that resolves to a floating point number,
553 you are dependent on Perl's conversion routines to yield the version you
554 expect. You are pretty safe by dividing by a power of 10, for example,
555 but other operations are not likely to be what you intend. For example:
557 $VERSION = version->new((qw$Revision: 1.4)[1]/10);
558 print $VERSION; # yields 0.14
559 $V2 = version->new(100/9); # Integer overflow in decimal number
560 print $V2; # yields something like 11.111.111.100
562 Perl 5.8.1 and beyond will be able to automatically quote v-strings but
563 that is not possible in earlier versions of Perl. In other words:
565 $version = version->new("v2.5.4"); # legal in all versions of Perl
566 $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1
570 This module is specifically designed and tested to be easily subclassed.
571 In practice, you only need to override the methods you want to change, but
572 you have to take some care when overriding new() (since that is where all
573 of the parsing takes place). For example, this is a perfect acceptable
581 # perform any special input handling here
582 $obj = $self->SUPER::new($n);
583 # and/or add additional hash elements here
587 See also L<version::AlphaBeta> on CPAN for an alternate representation of
590 B<NOTE:> Although the L<qv> operator is not a true class method, but rather a
591 function exported into the caller's namespace, a subclass of version will
592 inherit an import() function which will perform the correct magic on behalf
597 qv - Dotted-Decimal Version initialization operator
601 John Peacock E<lt>jpeacock@cpan.orgE<gt>