1version::Internals(3pm)Perl Programmers Reference Guideversion::Internals(3pm)
2
6 version::Internal - Perl extension for Version Objects
7
9 Overloaded version objects for all modern versions of Perl. This
10 documents the internal data representation and underlying code for
11 version.pm. See version.pod for daily usage. This document is only
12 useful for users writing a subclass of version.pm or interested in the
13 gory details.
14
16 For the purposes of this module, a version "number" is a sequence of
17 positive integer values separated by one or more decimal points and
18 optionally a single underscore. This corresponds to what Perl itself
19 uses for a version, as well as extending the "version as number" that
20 is discussed in the various editions of the Camel book.
21 There are actually two distinct kinds of version objects:
23 · Decimal Versions
25 Any version which "looks like a number", see "Decimal Versions".
27 This also includes versions with a single decimal point and a
28 single embedded underscore, see "Decimal Alpha Versions", even
29 though these must be quoted to preserve the underscore formatting.
30 · Dotted-Decimal Versions
32 Also referred to as "Dotted-Integer", these contains more than one
34 decimal point and may have an optional embedded underscore, see
35 Dotted-Decimal Versions. This is what is commonly used in most
36 open source software as the "external" version (the one used as
37 part of the tag or tarfile name). A leading 'v' character is now
38 required and will warn if it missing.
39 Both of these methods will produce similar version objects, in that the
41 default stringification will yield the version "Normal Form" only if
42 required:
43 $v = version->new(1.002); # 1.002, but compares like 1.2.0
45 $v = version->new(1.002003); # 1.002003
46 $v2 = version->new("v1.2.3"); # v1.2.3
47 In specific, version numbers initialized as "Decimal Versions" will
49 stringify as they were originally created (i.e. the same string that
50 was passed to "new()". Version numbers initialized as "Dotted-Decimal
51 Versions" will be stringified as "Normal Form".
52 Decimal Versions
54 These correspond to historical versions of Perl itself prior to 5.6.0,
55 as well as all other modules which follow the Camel rules for the
56 $VERSION scalar. A Decimal version is initialized with what looks like
57 a floating point number. Leading zeros are significant and trailing
58 zeros are implied so that a minimum of three places is maintained
59 between subversions. What this means is that any subversion (digits to
60 the right of the decimal place) that contains less than three digits
61 will have trailing zeros added to make up the difference, but only for
62 purposes of comparison with other version objects. For example:
63 # Prints Equivalent to
65 $v = version->new( 1.2); # 1.2 v1.200.0
66 $v = version->new( 1.02); # 1.02 v1.20.0
67 $v = version->new( 1.002); # 1.002 v1.2.0
68 $v = version->new( 1.0023); # 1.0023 v1.2.300
69 $v = version->new( 1.00203); # 1.00203 v1.2.30
70 $v = version->new( 1.002003); # 1.002003 v1.2.3
71 All of the preceding examples are true whether or not the input value
73 is quoted. The important feature is that the input value contains only
74 a single decimal. See also "Alpha Versions" for how to handle
75 IMPORTANT NOTE: As shown above, if your Decimal version contains more
77 than 3 significant digits after the decimal place, it will be split on
78 each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the
79 need to remain compatible with Perl's own 5.005_03 == 5.5.30
80 interpretation. Any trailing zeros are ignored for mathematical
81 comparison purposes.
82 Dotted-Decimal Versions
84 These are the newest form of versions, and correspond to Perl's own
85 version style beginning with 5.6.0. Starting with Perl 5.10.0, and
86 most likely Perl 6, this is likely to be the preferred form. This
87 method normally requires that the input parameter be quoted, although
88 Perl's after 5.8.1 can use v-strings as a special form of quoting, but
89 this is highly discouraged.
90 Unlike "Decimal Versions", Dotted-Decimal Versions have more than a
92 single decimal point, e.g.:
93 # Prints
95 $v = version->new( "v1.200"); # v1.200.0
96 $v = version->new("v1.20.0"); # v1.20.0
97 $v = qv("v1.2.3"); # v1.2.3
98 $v = qv("1.2.3"); # v1.2.3
99 $v = qv("1.20"); # v1.20.0
100 In general, Dotted-Decimal Versions permit the greatest amount of
102 freedom to specify a version, whereas Decimal Versions enforce a
103 certain uniformity. See also "New Operator" for an additional method
104 of initializing version objects.
105 Just like "Decimal Versions", Dotted-Decimal Versions can be used as
107 "Alpha Versions".
108 Decimal Alpha Versions
110 The one time that a Decimal version must be quoted is when a alpha form
111 is used with an otherwise Decimal version (i.e. a single decimal
112 point). This is commonly used for CPAN releases, where CPAN or
113 CPANPLUS will ignore alpha versions for automatic updating purposes.
114 Since some developers have used only two significant decimal places for
115 their non-alpha releases, the version object will automatically take
116 that into account if the initializer is quoted. For example
117 Module::Example was released to CPAN with the following sequence of
118 $VERSION's:
119 # $VERSION Stringified
121 0.01 0.01
122 0.02 0.02
123 0.02_01 0.02_01
124 0.02_02 0.02_02
125 0.03 0.03
126 etc.
127 The stringified form of Decimal versions will always be the same string
129 that was used to initialize the version object.
130
132 version objects
133 version.pm provides an overloaded version object that is designed to
134 both encapsulate the author's intended $VERSION assignment as well as
135 make it completely natural to use those objects as if they were numbers
136 (e.g. for comparisons). To do this, a version object contains both the
137 original representation as typed by the author, as well as a parsed
138 representation to ease comparisons. Version objects employ overload
139 methods to simplify code that needs to compare, print, etc the objects.
140 The internal structure of version objects is a blessed hash with
142 several components:
143 bless( {
145 'original' => 'v1.2.3_4',
146 'alpha' => 1,
147 'qv' => 1,
148 'version' => [
149 1,
150 2,
151 3,
152 4
153 ]
154 }, 'version' );
155 original
157 A faithful representation of the value used to initialize this
158 version object. The only time this will not be precisely the same
159 characters that exist in the source file is if a short dotted-
160 decimal version like v1.2 was used (in which case it will contain
161 'v1.2'). This form is STRONGLY discouraged, in that it will
162 confuse you and your users.
163 qv A boolean that denotes whether this is a decimal or dotted-decimal
165 version. See is_qv.
166 alpha
168 A boolean that denotes whether this is an alpha version. NOTE:
169 that the underscore can can only appear in the last position. See
170 is_alpha.
171 version
173 An array of non-negative integers that is used for comparison
174 purposes with other version objects.
175 Replacement UNIVERSAL::VERSION
177 In addition to the version objects, this modules also replaces the core
178 UNIVERSAL::VERSION function with one that uses version objects for its
179 comparisons. The return from this operator is always the stringified
180 form as a simple scalar (i.e. not an object), but the warning message
181 generated includes either the stringified form or the normal form,
182 depending on how it was called.
183 For example:
185 package Foo;
187 $VERSION = 1.2;
188 package Bar;
190 $VERSION = "v1.3.5"; # works with all Perl's (since it is quoted)
191 package main;
193 use version;
194 print $Foo::VERSION; # prints 1.2
196 print $Bar::VERSION; # prints 1.003005
198 eval "use foo 10";
200 print $@; # prints "foo version 10 required..."
201 eval "use foo 1.3.5; # work in Perl 5.6.1 or better
202 print $@; # prints "foo version 1.3.5 required..."
203 eval "use bar 1.3.6";
205 print $@; # prints "bar version 1.3.6 required..."
206 eval "use bar 1.004"; # note Decimal version
207 print $@; # prints "bar version 1.004 required..."
208 IMPORTANT NOTE: This may mean that code which searches for a specific
210 string (to determine whether a given module is available) may need to
211 be changed. It is always better to use the built-in comparison
212 implicit in "use" or "require", rather than manually poking at
213 "class-"VERSION> and then doing a comparison yourself.
214 The replacement UNIVERSAL::VERSION, when used as a function, like this:
216 print $module->VERSION;
218 will also exclusively return the stringified form. See Stringification
220 for more details.
221
223 Using modules that use version.pm
224 As much as possible, the version.pm module remains compatible with all
225 current code. However, if your module is using a module that has
226 defined $VERSION using the version class, there are a couple of things
227 to be aware of. For purposes of discussion, we will assume that we
228 have the following module installed:
229 package Example;
231 use version; $VERSION = qv('1.2.2');
232 ...module code here...
233 1;
234 Decimal versions always work
236 Code of the form:
237 use Example 1.002003;
239 will always work correctly. The "use" will perform an automatic
241 $VERSION comparison using the floating point number given as the
242 first term after the module name (e.g. above 1.002.003). In this
243 case, the installed module is too old for the requested line, so
244 you would see an error like:
245 Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
247 Dotted-Decimal version work sometimes
249 With Perl >= 5.6.2, you can also use a line like this:
250 use Example 1.2.3;
252 and it will again work (i.e. give the error message as above), even
254 with releases of Perl which do not normally support v-strings (see
255 "What about v-strings" below). This has to do with that fact that
256 "use" only checks to see if the second term looks like a number and
257 passes that to the replacement UNIVERSAL::VERSION. This is not
258 true in Perl 5.005_04, however, so you are strongly encouraged to
259 always use a Decimal version in your code, even for those versions
260 of Perl which support the Dotted-Decimal version.
261 Object Methods
263 Overloading has been used with version objects to provide a natural
264 interface for their use. All mathematical operations are forbidden,
265 since they don't make any sense for base version objects.
266 Consequently, there is no overloaded numification available. If you
267 want to use a version object in a Decimal context for some reason, see
268 the numify object method.
269 · New Operator
271 Like all OO interfaces, the new() operator is used to initialize
273 version objects. One way to increment versions when programming is
274 to use the CVS variable $Revision, which is automatically
275 incremented by CVS every time the file is committed to the
276 repository.
277 In order to facilitate this feature, the following code can be
279 employed:
280 $VERSION = version->new(qw$Revision: 2.7 $);
282 and the version object will be created as if the following code
284 were used:
285 $VERSION = version->new("v2.7");
287 In other words, the version will be automatically parsed out of the
289 string, and it will be quoted to preserve the meaning CVS normally
290 carries for versions. The CVS $Revision$ increments differently
291 from Decimal versions (i.e. 1.10 follows 1.9), so it must be
292 handled as if it were a "Dotted-Decimal Version".
293 A new version object can be created as a copy of an existing
295 version object, either as a class method:
296 $v1 = version->new(12.3);
298 $v2 = version->new($v1);
299 or as an object method:
301 $v1 = version->new(12.3);
303 $v2 = $v1->new(12.3);
304 and in each case, $v1 and $v2 will be identical. NOTE: if you
306 create a new object using an existing object like this:
307 $v2 = $v1->new();
309 the new object will not be a clone of the existing object. In the
311 example case, $v2 will be an empty object of the same type as $v1.
312 · qv()
314 An alternate way to create a new version object is through the
316 exported qv() sub. This is not strictly like other q? operators
317 (like qq, qw), in that the only delimiters supported are
318 parentheses (or spaces). It is the best way to initialize a short
319 version without triggering the floating point interpretation. For
320 example:
321 $v1 = qv(1.2); # v1.2.0
323 $v2 = qv("1.2"); # also v1.2.0
324 As you can see, either a bare number or a quoted string can usually
326 be used interchangably, except in the case of a trailing zero,
327 which must be quoted to be converted properly. For this reason, it
328 is strongly recommended that all initializers to qv() be quoted
329 strings instead of bare numbers.
330 To prevent the "qv()" function from being exported to the caller's
332 namespace, either use version with a null parameter:
333 use version ();
335 or just require version, like this:
337 require version;
339 Both methods will prevent the import() method from firing and
341 exporting the "qv()" sub. This is true of subclasses of version as
342 well, see SUBCLASSING for details.
343 For the subsequent examples, the following three objects will be used:
345 $ver = version->new("1.2.3.4"); # see "Quoting" below
347 $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
348 $nver = version->new(1.002); # see "Decimal Versions" above
349 · Normal Form
351 For any version object which is initialized with multiple decimal
353 places (either quoted or if possible v-string), or initialized
354 using the qv() operator, the stringified representation is returned
355 in a normalized or reduced form (no extraneous zeros), and with a
356 leading 'v':
357 print $ver->normal; # prints as v1.2.3.4
359 print $ver->stringify; # ditto
360 print $ver; # ditto
361 print $nver->normal; # prints as v1.2.0
362 print $nver->stringify; # prints as 1.002, see "Stringification"
363 In order to preserve the meaning of the processed version, the
365 normalized representation will always contain at least three sub
366 terms. In other words, the following is guaranteed to always be
367 true:
368 my $newver = version->new($ver->stringify);
370 if ($newver eq $ver ) # always true
371 {...}
372 · Numification
374 Although all mathematical operations on version objects are
376 forbidden by default, it is possible to retrieve a number which
377 corresponds to the version object through the use of the
378 $obj->numify method. For formatting purposes, when displaying a
379 number which corresponds a version object, all sub versions are
380 assumed to have three decimal places. So for example:
381 print $ver->numify; # prints 1.002003004
383 print $nver->numify; # prints 1.002
384 Unlike the stringification operator, there is never any need to
386 append trailing zeros to preserve the correct version value.
387 · Stringification
389 The default stringification for version objects returns exactly the
391 same string as was used to create it, whether you used "new()" or
392 "qv()", with one exception. The sole exception is if the object
393 was created using "qv()" and the initializer did not have two
394 decimal places or a leading 'v' (both optional), then the
395 stringified form will have a leading 'v' prepended, in order to
396 support round-trip processing.
397 For example:
399 Initialized as Stringifies to
401 ============== ==============
402 version->new("1.2") 1.2
403 version->new("v1.2") v1.2
404 qv("1.2.3") 1.2.3
405 qv("v1.3.5") v1.3.5
406 qv("1.2") v1.2 ### exceptional case
407 See also UNIVERSAL::VERSION, as this also returns the stringified
409 form when used as a class method.
410 IMPORTANT NOTE: There is one exceptional cases shown in the above
412 table where the "initializer" is not stringwise equivalent to the
413 stringified representation. If you use the "qv()" operator on a
414 version without a leading 'v' and with only a single decimal place,
415 the stringified output will have a leading 'v', to preserve the
416 sense. See the qv() operator for more details.
417 IMPORTANT NOTE 2: Attempting to bypass the normal stringification
419 rules by manually applying numify() and normal() will sometimes
420 yield surprising results:
421 print version->new(version->new("v1.0")->numify)->normal; # v1.0.0
423 The reason for this is that the numify() operator will turn "v1.0"
425 into the equivalent string "1.000000". Forcing the outer version
426 object to normal() form will display the mathematically equivalent
427 "v1.0.0".
428 As the example in new() shows, you can always create a copy of an
430 existing version object with the same value by the very compact:
431 $v2 = $v1->new($v1);
433 and be assured that both $v1 and $v2 will be completely equivalent,
435 down to the same internal representation as well as
436 stringification.
437 · Comparison operators
439 Both "cmp" and "<=>" operators perform the same comparison between
441 terms (upgrading to a version object automatically). Perl
442 automatically generates all of the other comparison operators based
443 on those two. In addition to the obvious equalities listed below,
444 appending a single trailing 0 term does not change the value of a
445 version for comparison purposes. In other words "v1.2" and "1.2.0"
446 will compare as identical.
447 For example, the following relations hold:
449 As Number As String Truth Value
451 ------------- ---------------- -----------
452 $ver > 1.0 $ver gt "1.0" true
453 $ver < 2.5 $ver lt true
454 $ver != 1.3 $ver ne "1.3" true
455 $ver == 1.2 $ver eq "1.2" false
456 $ver == 1.2.3.4 $ver eq "1.2.3.4" see discussion below
457 It is probably best to chose either the Decimal notation or the
459 string notation and stick with it, to reduce confusion. Perl6
460 version objects may only support Decimal comparisons. See also
461 Quoting.
462 WARNING: Comparing version with unequal numbers of decimal points
464 (whether explicitly or implicitly initialized), may yield
465 unexpected results at first glance. For example, the following
466 inequalities hold:
467 version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0
469 version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
470 For this reason, it is best to use either exclusively "Decimal
472 Versions" or "Dotted-Decimal Versions" with multiple decimal
473 points.
474 · Logical Operators
476 If you need to test whether a version object has been initialized,
478 you can simply test it directly:
479 $vobj = version->new($something);
481 if ( $vobj ) # true only if $something was non-blank
482 You can also test whether a version object is an "Alpha version",
484 for example to prevent the use of some feature not present in the
485 main release:
486 $vobj = version->new("1.2_3"); # MUST QUOTE
488 ...later...
489 if ( $vobj->is_alpha ) # True
490 Quoting
492 Because of the nature of the Perl parsing and tokenizing routines,
493 certain initialization values must be quoted in order to correctly
494 parse as the intended version, especially when using the qv() operator.
495 In all cases, a floating point number passed to version->new() will be
496 identically converted whether or not the value itself is quoted. This
497 is not true for qv(), however, when trailing zeros would be stripped on
498 an unquoted input, which would result in a very different version
499 object.
500 In addition, in order to be compatible with earlier Perl version
502 styles, any use of versions of the form 5.006001 will be translated as
503 v5.6.1. In other words, a version with a single decimal point will be
504 parsed as implicitly having three digits between subversions, but only
505 for internal comparison purposes.
506 The complicating factor is that in bare numbers (i.e. unquoted), the
508 underscore is a legal Decimal character and is automatically stripped
509 by the Perl tokenizer before the version code is called. However, if a
510 number containing one or more decimals and an underscore is quoted,
511 i.e. not bare, that is considered a "Alpha Version" and the underscore
512 is significant.
513 If you use a mathematic formula that resolves to a floating point
515 number, you are dependent on Perl's conversion routines to yield the
516 version you expect. You are pretty safe by dividing by a power of 10,
517 for example, but other operations are not likely to be what you intend.
518 For example:
519 $VERSION = version->new((qw$Revision: 1.4)[1]/10);
521 print $VERSION; # yields 0.14
522 $V2 = version->new(100/9); # Integer overflow in decimal number
523 print $V2; # yields something like 11.111.111.100
524 Perl 5.8.1 and beyond will be able to automatically quote v-strings but
526 that is not possible in earlier versions of Perl. In other words:
527 $version = version->new("v2.5.4"); # legal in all versions of Perl
529 $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1
530
532 This module is specifically designed and tested to be easily
533 subclassed. In practice, you only need to override the methods you
534 want to change, but you have to take some care when overriding new()
535 (since that is where all of the parsing takes place). For example,
536 this is a perfect acceptable derived class:
537 package myversion;
539 use base version;
540 sub new {
541 my($self,$n)=@_;
542 my $obj;
543 # perform any special input handling here
544 $obj = $self->SUPER::new($n);
545 # and/or add additional hash elements here
546 return $obj;
547 }
548 See also version::AlphaBeta on CPAN for an alternate representation of
550 version strings.
551 NOTE: Although the qv operator is not a true class method, but rather a
553 function exported into the caller's namespace, a subclass of version
554 will inherit an import() function which will perform the correct magic
555 on behalf of the subclass.
556
558 qv - Dotted-Decimal Version initialization operator
559
561 John Peacock <jpeacock@cpan.org>
562
564 perl.
565perl v5.10.1 2009-07-27 version::Internals(3pm)