1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "version::Internals 3"
132 .TH version::Internals 3 "2009-10-23" "perl v5.8.7" "User Contributed Perl Documentation"
134 version::Internal \- Perl extension for Version Objects
136 .IX Header "DESCRIPTION"
137 Overloaded version objects for all modern versions of Perl. This documents
138 the internal data representation and underlying code for version.pm. See
139 version.pod for daily usage. This document is only useful for users
140 writing a subclass of version.pm or interested in the gory details.
141 .SH "What IS a version"
142 .IX Header "What IS a version"
143 For the purposes of this module, a version \*(L"number\*(R" is a sequence of
144 positive integer values separated by one or more decimal points and
145 optionally a single underscore. This corresponds to what Perl itself
146 uses for a version, as well as extending the \*(L"version as number\*(R" that
147 is discussed in the various editions of the Camel book.
149 There are actually two distinct kinds of version objects:
150 .IP "* Decimal Versions" 4
151 .IX Item "Decimal Versions"
152 Any version which \*(L"looks like a number\*(R", see \*(L"Decimal Versions\*(R". This
153 also includes versions with a single decimal point and a single embedded
154 underscore, see \*(L"Decimal Alpha Versions\*(R", even though these must be quoted
155 to preserve the underscore formatting.
156 .IP "* Dotted-Decimal Versions" 4
157 .IX Item "Dotted-Decimal Versions"
158 Also referred to as \*(L"Dotted\-Integer\*(R", these contains more than one decimal
159 point and may have an optional embedded underscore, see \*(L"Dotted\-Decimal Versions\*(R". This is what is commonly used in most open source software as
160 the \*(L"external\*(R" version (the one used as part of the tag or tarfile name).
161 A leading 'v' character is now required and will warn if it missing.
163 Both of these methods will produce similar version objects, in that
164 the default stringification will yield the version \*(L"Normal Form\*(R" only
168 \& $v = version\->new(1.002); # 1.002, but compares like 1.2.0
169 \& $v = version\->new(1.002003); # 1.002003
170 \& $v2 = version\->new("v1.2.3"); # v1.2.3
173 In specific, version numbers initialized as \*(L"Decimal Versions\*(R" will
174 stringify as they were originally created (i.e. the same string that was
175 passed to \f(CW\*(C`new()\*(C'\fR. Version numbers initialized as \*(L"Dotted\-Decimal Versions\*(R"
176 will be stringified as \*(L"Normal Form\*(R".
177 .Sh "Decimal Versions"
178 .IX Subsection "Decimal Versions"
179 These correspond to historical versions of Perl itself prior to 5.6.0,
180 as well as all other modules which follow the Camel rules for the
181 \&\f(CW$VERSION\fR scalar. A Decimal version is initialized with what looks like
182 a floating point number. Leading zeros \fBare\fR significant and trailing
183 zeros are implied so that a minimum of three places is maintained
184 between subversions. What this means is that any subversion (digits
185 to the right of the decimal place) that contains less than three digits
186 will have trailing zeros added to make up the difference, but only for
187 purposes of comparison with other version objects. For example:
190 \& # Prints Equivalent to
191 \& $v = version\->new( 1.2); # 1.2 v1.200.0
192 \& $v = version\->new( 1.02); # 1.02 v1.20.0
193 \& $v = version\->new( 1.002); # 1.002 v1.2.0
194 \& $v = version\->new( 1.0023); # 1.0023 v1.2.300
195 \& $v = version\->new( 1.00203); # 1.00203 v1.2.30
196 \& $v = version\->new( 1.002003); # 1.002003 v1.2.3
199 All of the preceding examples are true whether or not the input value is
200 quoted. The important feature is that the input value contains only a
201 single decimal. See also \*(L"Alpha Versions\*(R" for how to handle
203 \&\s-1IMPORTANT\s0 \s-1NOTE:\s0 As shown above, if your Decimal version contains more
204 than 3 significant digits after the decimal place, it will be split on
205 each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need
206 to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation.
207 Any trailing zeros are ignored for mathematical comparison purposes.
208 .Sh "Dotted-Decimal Versions"
209 .IX Subsection "Dotted-Decimal Versions"
210 These are the newest form of versions, and correspond to Perl's own
211 version style beginning with 5.6.0. Starting with Perl 5.10.0,
212 and most likely Perl 6, this is likely to be the preferred form. This
213 method normally requires that the input parameter be quoted, although
214 Perl's after 5.8.1 can use v\-strings as a special form of quoting, but
215 this is highly discouraged.
217 Unlike \*(L"Decimal Versions\*(R", Dotted-Decimal Versions have more than
218 a single decimal point, e.g.:
222 \& $v = version\->new( "v1.200"); # v1.200.0
223 \& $v = version\->new("v1.20.0"); # v1.20.0
224 \& $v = qv("v1.2.3"); # v1.2.3
225 \& $v = qv("1.2.3"); # v1.2.3
226 \& $v = qv("1.20"); # v1.20.0
229 In general, Dotted-Decimal Versions permit the greatest amount of freedom
230 to specify a version, whereas Decimal Versions enforce a certain
231 uniformity. See also \*(L"New Operator\*(R" for an additional method of
232 initializing version objects.
234 Just like \*(L"Decimal Versions\*(R", Dotted-Decimal Versions can be used as
235 \&\*(L"Alpha Versions\*(R".
236 .Sh "Decimal Alpha Versions"
237 .IX Subsection "Decimal Alpha Versions"
238 The one time that a Decimal version must be quoted is when a alpha form is
239 used with an otherwise Decimal version (i.e. a single decimal point). This
240 is commonly used for \s-1CPAN\s0 releases, where \s-1CPAN\s0 or \s-1CPANPLUS\s0 will ignore alpha
241 versions for automatic updating purposes. Since some developers have used
242 only two significant decimal places for their non-alpha releases, the
243 version object will automatically take that into account if the initializer
244 is quoted. For example Module::Example was released to \s-1CPAN\s0 with the
245 following sequence of \f(CW$VERSION\fR's:
248 \& # $VERSION Stringified
257 The stringified form of Decimal versions will always be the same string
258 that was used to initialize the version object.
259 .SH "High level design"
260 .IX Header "High level design"
261 .Sh "version objects"
262 .IX Subsection "version objects"
263 version.pm provides an overloaded version object that is designed to both
264 encapsulate the author's intended \f(CW$VERSION\fR assignment as well as make it
265 completely natural to use those objects as if they were numbers (e.g. for
266 comparisons). To do this, a version object contains both the original
267 representation as typed by the author, as well as a parsed representation
268 to ease comparisons. Version objects employ overload methods to
269 simplify code that needs to compare, print, etc the objects.
271 The internal structure of version objects is a blessed hash with several
276 \& 'original' => 'v1.2.3_4',
289 A faithful representation of the value used to initialize this version
290 object. The only time this will not be precisely the same characters
291 that exist in the source file is if a short dotted-decimal version like
292 v1.2 was used (in which case it will contain 'v1.2'). This form is
293 \&\fB\s-1STRONGLY\s0\fR discouraged, in that it will confuse you and your users.
296 A boolean that denotes whether this is a decimal or dotted-decimal version.
300 A boolean that denotes whether this is an alpha version. \s-1NOTE:\s0 that the
301 underscore can can only appear in the last position. See is_alpha.
304 An array of non-negative integers that is used for comparison purposes with
305 other version objects.
306 .Sh "Replacement \s-1UNIVERSAL::VERSION\s0"
307 .IX Subsection "Replacement UNIVERSAL::VERSION"
308 In addition to the version objects, this modules also replaces the core
309 \&\s-1UNIVERSAL::VERSION\s0 function with one that uses version objects for its
310 comparisons. The return from this operator is always the stringified form
311 as a simple scalar (i.e. not an object), but the warning message generated
312 includes either the stringified form or the normal form, depending on how
324 \& $VERSION = "v1.3.5"; # works with all Perl's (since it is quoted)
333 \& print $Foo::VERSION; # prints 1.2
337 \& print $Bar::VERSION; # prints 1.003005
341 \& eval "use foo 10";
342 \& print $@; # prints "foo version 10 required..."
343 \& eval "use foo 1.3.5; # work in Perl 5.6.1 or better
344 \& print $@; # prints "foo version 1.3.5 required..."
348 \& eval "use bar 1.3.6";
349 \& print $@; # prints "bar version 1.3.6 required..."
350 \& eval "use bar 1.004"; # note Decimal version
351 \& print $@; # prints "bar version 1.004 required..."
354 \&\s-1IMPORTANT\s0 \s-1NOTE:\s0 This may mean that code which searches for a specific
355 string (to determine whether a given module is available) may need to be
356 changed. It is always better to use the built-in comparison implicit in
357 \&\f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR, rather than manually poking at \f(CW\*(C`class\-\*(C'\fR\s-1VERSION\s0>
358 and then doing a comparison yourself.
360 The replacement \s-1UNIVERSAL::VERSION\s0, when used as a function, like this:
363 \& print $module\->VERSION;
366 will also exclusively return the stringified form. See Stringification
369 .IX Header "Usage question"
370 .Sh "Using modules that use version.pm"
371 .IX Subsection "Using modules that use version.pm"
372 As much as possible, the version.pm module remains compatible with all
373 current code. However, if your module is using a module that has defined
374 \&\f(CW$VERSION\fR using the version class, there are a couple of things to be
375 aware of. For purposes of discussion, we will assume that we have the
376 following module installed:
380 \& use version; $VERSION = qv('1.2.2');
381 \& ...module code here...
384 .IP "Decimal versions always work" 4
385 .IX Item "Decimal versions always work"
389 \& use Example 1.002003;
392 will always work correctly. The \f(CW\*(C`use\*(C'\fR will perform an automatic
393 \&\f(CW$VERSION\fR comparison using the floating point number given as the first
394 term after the module name (e.g. above 1.002.003). In this case, the
395 installed module is too old for the requested line, so you would see an
399 \& Example version 1.002003 (v1.2.3) required\-\-this is only version 1.002002 (v1.2.2)...
401 .IP "Dotted-Decimal version work sometimes" 4
402 .IX Item "Dotted-Decimal version work sometimes"
403 With Perl >= 5.6.2, you can also use a line like this:
406 \& use Example 1.2.3;
409 and it will again work (i.e. give the error message as above), even with
410 releases of Perl which do not normally support v\-strings (see \*(L"What about v\-strings\*(R" below). This has to do with that fact that \f(CW\*(C`use\*(C'\fR only checks
411 to see if the second term \fIlooks like a number\fR and passes that to the
412 replacement \s-1UNIVERSAL::VERSION\s0. This is not true in Perl 5.005_04,
413 however, so you are \fBstrongly encouraged\fR to always use a Decimal version
414 in your code, even for those versions of Perl which support the Dotted-Decimal
417 .IX Subsection "Object Methods"
418 Overloading has been used with version objects to provide a natural
419 interface for their use. All mathematical operations are forbidden,
420 since they don't make any sense for base version objects. Consequently,
421 there is no overloaded numification available. If you want to use a
422 version object in a Decimal context for some reason, see the numify
424 .IP "* New Operator" 4
425 .IX Item "New Operator"
426 Like all \s-1OO\s0 interfaces, the \fInew()\fR operator is used to initialize
427 version objects. One way to increment versions when programming is to
428 use the \s-1CVS\s0 variable \f(CW$Revision\fR, which is automatically incremented by
429 \&\s-1CVS\s0 every time the file is committed to the repository.
431 In order to facilitate this feature, the following
432 code can be employed:
435 \& $VERSION = version\->new(qw$Revision: 2.7 $);
438 and the version object will be created as if the following code
442 \& $VERSION = version\->new("v2.7");
445 In other words, the version will be automatically parsed out of the
446 string, and it will be quoted to preserve the meaning \s-1CVS\s0 normally
447 carries for versions. The \s-1CVS\s0 \f(CW$Revision\fR$ increments differently from
448 Decimal versions (i.e. 1.10 follows 1.9), so it must be handled as if
449 it were a \*(L"Dotted\-Decimal Version\*(R".
451 A new version object can be created as a copy of an existing version
452 object, either as a class method:
455 \& $v1 = version\->new(12.3);
456 \& $v2 = version\->new($v1);
459 or as an object method:
462 \& $v1 = version\->new(12.3);
463 \& $v2 = $v1\->new(12.3);
466 and in each case, \f(CW$v1\fR and \f(CW$v2\fR will be identical. \s-1NOTE:\s0 if you create
467 a new object using an existing object like this:
470 \& $v2 = $v1\->new();
473 the new object \fBwill not\fR be a clone of the existing object. In the
474 example case, \f(CW$v2\fR will be an empty object of the same type as \f(CW$v1\fR.
477 An alternate way to create a new version object is through the exported
478 \&\fIqv()\fR sub. This is not strictly like other q? operators (like qq, qw),
479 in that the only delimiters supported are parentheses (or spaces). It is
480 the best way to initialize a short version without triggering the floating
481 point interpretation. For example:
484 \& $v1 = qv(1.2); # v1.2.0
485 \& $v2 = qv("1.2"); # also v1.2.0
488 As you can see, either a bare number or a quoted string can usually
489 be used interchangably, except in the case of a trailing zero, which
490 must be quoted to be converted properly. For this reason, it is strongly
491 recommended that all initializers to \fIqv()\fR be quoted strings instead of
494 To prevent the \f(CW\*(C`qv()\*(C'\fR function from being exported to the caller's namespace,
495 either use version with a null parameter:
501 or just require version, like this:
507 Both methods will prevent the \fIimport()\fR method from firing and exporting the
508 \&\f(CW\*(C`qv()\*(C'\fR sub. This is true of subclasses of version as well, see
509 \&\s-1SUBCLASSING\s0 for details.
511 For the subsequent examples, the following three objects will be used:
514 \& $ver = version\->new("1.2.3.4"); # see "Quoting" below
515 \& $alpha = version\->new("1.2.3_4"); # see "Alpha versions" below
516 \& $nver = version\->new(1.002); # see "Decimal Versions" above
518 .IP "* Normal Form" 4
519 .IX Item "Normal Form"
520 For any version object which is initialized with multiple decimal
521 places (either quoted or if possible v\-string), or initialized using
522 the \fIqv()\fR operator, the stringified representation is returned in
523 a normalized or reduced form (no extraneous zeros), and with a leading 'v':
526 \& print $ver\->normal; # prints as v1.2.3.4
527 \& print $ver\->stringify; # ditto
528 \& print $ver; # ditto
529 \& print $nver\->normal; # prints as v1.2.0
530 \& print $nver\->stringify; # prints as 1.002, see "Stringification"
533 In order to preserve the meaning of the processed version, the
534 normalized representation will always contain at least three sub terms.
535 In other words, the following is guaranteed to always be true:
538 \& my $newver = version\->new($ver\->stringify);
539 \& if ($newver eq $ver ) # always true
542 .IP "* Numification" 4
543 .IX Item "Numification"
544 Although all mathematical operations on version objects are forbidden
545 by default, it is possible to retrieve a number which corresponds
546 to the version object through the use of the \f(CW$obj\fR\->numify
547 method. For formatting purposes, when displaying a number which
548 corresponds a version object, all sub versions are assumed to have
549 three decimal places. So for example:
552 \& print $ver\->numify; # prints 1.002003004
553 \& print $nver\->numify; # prints 1.002
556 Unlike the stringification operator, there is never any need to append
557 trailing zeros to preserve the correct version value.
558 .IP "* Stringification" 4
559 .IX Item "Stringification"
560 The default stringification for version objects returns exactly the same
561 string as was used to create it, whether you used \f(CW\*(C`new()\*(C'\fR or \f(CW\*(C`qv()\*(C'\fR,
562 with one exception. The sole exception is if the object was created using
563 \&\f(CW\*(C`qv()\*(C'\fR and the initializer did not have two decimal places or a leading
564 \&'v' (both optional), then the stringified form will have a leading 'v'
565 prepended, in order to support round-trip processing.
570 \& Initialized as Stringifies to
571 \& ============== ==============
572 \& version\->new("1.2") 1.2
573 \& version\->new("v1.2") v1.2
575 \& qv("v1.3.5") v1.3.5
576 \& qv("1.2") v1.2 ### exceptional case
579 See also \s-1UNIVERSAL::VERSION\s0, as this also returns the stringified form
580 when used as a class method.
582 \&\s-1IMPORTANT\s0 \s-1NOTE:\s0 There is one exceptional cases shown in the above table
583 where the \*(L"initializer\*(R" is not stringwise equivalent to the stringified
584 representation. If you use the \f(CW\*(C`qv()\*(C'\fR operator on a version without a
585 leading 'v' \fBand\fR with only a single decimal place, the stringified output
586 will have a leading 'v', to preserve the sense. See the \fIqv()\fR operator
589 \&\s-1IMPORTANT\s0 \s-1NOTE\s0 2: Attempting to bypass the normal stringification rules by
590 manually applying \fInumify()\fR and \fInormal()\fR will sometimes yield
594 \& print version\->new(version\->new("v1.0")\->numify)\->normal; # v1.0.0
597 The reason for this is that the \fInumify()\fR operator will turn \*(L"v1.0\*(R"
598 into the equivalent string \*(L"1.000000\*(R". Forcing the outer version object
599 to \fInormal()\fR form will display the mathematically equivalent \*(L"v1.0.0\*(R".
601 As the example in \fInew()\fR shows, you can always create a copy of an
602 existing version object with the same value by the very compact:
605 \& $v2 = $v1\->new($v1);
608 and be assured that both \f(CW$v1\fR and \f(CW$v2\fR will be completely equivalent,
609 down to the same internal representation as well as stringification.
610 .IP "* Comparison operators" 4
611 .IX Item "Comparison operators"
612 Both \f(CW\*(C`cmp\*(C'\fR and \f(CW\*(C`<=>\*(C'\fR operators perform the same comparison between
613 terms (upgrading to a version object automatically). Perl automatically
614 generates all of the other comparison operators based on those two.
615 In addition to the obvious equalities listed below, appending a single
616 trailing 0 term does not change the value of a version for comparison
617 purposes. In other words \*(L"v1.2\*(R" and \*(L"1.2.0\*(R" will compare as identical.
619 For example, the following relations hold:
622 \& As Number As String Truth Value
623 \& \-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
624 \& $ver > 1.0 $ver gt "1.0" true
625 \& $ver < 2.5 $ver lt true
626 \& $ver != 1.3 $ver ne "1.3" true
627 \& $ver == 1.2 $ver eq "1.2" false
628 \& $ver == 1.2.3.4 $ver eq "1.2.3.4" see discussion below
631 It is probably best to chose either the Decimal notation or the string
632 notation and stick with it, to reduce confusion. Perl6 version objects
633 \&\fBmay\fR only support Decimal comparisons. See also Quoting.
635 \&\s-1WARNING:\s0 Comparing version with unequal numbers of decimal points (whether
636 explicitly or implicitly initialized), may yield unexpected results at
637 first glance. For example, the following inequalities hold:
640 \& version\->new(0.96) > version\->new(0.95); # 0.960.0 > 0.950.0
641 \& version\->new("0.96.1") < version\->new(0.95); # 0.096.1 < 0.950.0
644 For this reason, it is best to use either exclusively \*(L"Decimal Versions\*(R" or
645 \&\*(L"Dotted\-Decimal Versions\*(R" with multiple decimal points.
646 .IP "* Logical Operators" 4
647 .IX Item "Logical Operators"
648 If you need to test whether a version object
649 has been initialized, you can simply test it directly:
652 \& $vobj = version\->new($something);
653 \& if ( $vobj ) # true only if $something was non\-blank
656 You can also test whether a version object is an \*(L"Alpha version\*(R", for
657 example to prevent the use of some feature not present in the main
661 \& $vobj = version\->new("1.2_3"); # MUST QUOTE
663 \& if ( $vobj\->is_alpha ) # True
666 .IX Subsection "Quoting"
667 Because of the nature of the Perl parsing and tokenizing routines,
668 certain initialization values \fBmust\fR be quoted in order to correctly
669 parse as the intended version, especially when using the \fIqv()\fR operator.
670 In all cases, a floating point number passed to version\->\fInew()\fR will be
671 identically converted whether or not the value itself is quoted. This is
672 not true for \fIqv()\fR, however, when trailing zeros would be stripped on
673 an unquoted input, which would result in a very different version object.
675 In addition, in order to be compatible with earlier Perl version styles,
676 any use of versions of the form 5.006001 will be translated as v5.6.1.
677 In other words, a version with a single decimal point will be parsed as
678 implicitly having three digits between subversions, but only for internal
681 The complicating factor is that in bare numbers (i.e. unquoted), the
682 underscore is a legal Decimal character and is automatically stripped
683 by the Perl tokenizer before the version code is called. However, if
684 a number containing one or more decimals and an underscore is quoted, i.e.
685 not bare, that is considered a \*(L"Alpha Version\*(R" and the underscore is
688 If you use a mathematic formula that resolves to a floating point number,
689 you are dependent on Perl's conversion routines to yield the version you
690 expect. You are pretty safe by dividing by a power of 10, for example,
691 but other operations are not likely to be what you intend. For example:
694 \& $VERSION = version\->new((qw$Revision: 1.4)[1]/10);
695 \& print $VERSION; # yields 0.14
696 \& $V2 = version\->new(100/9); # Integer overflow in decimal number
697 \& print $V2; # yields something like 11.111.111.100
700 Perl 5.8.1 and beyond will be able to automatically quote v\-strings but
701 that is not possible in earlier versions of Perl. In other words:
704 \& $version = version\->new("v2.5.4"); # legal in all versions of Perl
705 \& $newvers = version\->new(v2.5.4); # legal only in Perl >= 5.8.1
708 .IX Header "SUBCLASSING"
709 This module is specifically designed and tested to be easily subclassed.
710 In practice, you only need to override the methods you want to change, but
711 you have to take some care when overriding \fInew()\fR (since that is where all
712 of the parsing takes place). For example, this is a perfect acceptable
716 \& package myversion;
721 \& # perform any special input handling here
722 \& $obj = $self\->SUPER::new($n);
723 \& # and/or add additional hash elements here
728 See also version::AlphaBeta on \s-1CPAN\s0 for an alternate representation of
731 \&\fB\s-1NOTE:\s0\fR Although the qv operator is not a true class method, but rather a
732 function exported into the caller's namespace, a subclass of version will
733 inherit an \fIimport()\fR function which will perform the correct magic on behalf
737 qv \- Dotted-Decimal Version initialization operator
740 John Peacock <jpeacock@cpan.org>
742 .IX Header "SEE ALSO"
projects / catagits/Gitalist.git / blob