1version(3) User Contributed Perl Documentation version(3)
2
6 version - Perl extension for Version Objects
7
9 use version;
10 $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
11 print $version; # v12.2.1
12 print $version->numify; # 12.002001
13 if ( $version gt "12.2" ) # true
14 $alphaver = version->new("1.02_03"); # must be quoted!
16 print $alphaver; # 1.02_0300
17 print $alphaver->is_alpha(); # true
18 $ver = qv("1.2.0"); # v1.2.0
20 $perlver = version->new(5.005_03); # must not be quoted!
22 print $perlver; # 5.005030
23
25 Overloaded version objects for all modern versions of Perl. This mod‐
26 ule implements all of the features of version objects which will be
27 part of Perl 5.10.0.
28 BEST PRACTICES
30 If you intend for your module to be used by different releases of Perl,
32 and/or for your $VERSION scalar to mean what you think it means, there
33 are a few simple rules to follow:
34 * Be consistent
36 Whichever of the two types of version objects that you choose to
37 employ, you should stick to either "Numeric Versions" or "Extended
38 Versions" and not mix them together. While this is possible, it is
39 very confusing to the average user.
40 If you intend to use "Extended Versions", you are strongly encour‐
42 aged to use the qv() operator with a quoted term, e.g.:
43 use version; our $VERSION = qv("1.2.3");
45 on a single line as above.
47 At the very least, decide on which of the several ways to initial‐
49 ize your version objects you prefer and stick with it. It is also
50 best to be explicit about what value you intend to assign your ver‐
51 sion object and to not rely on hidden behavior of the parser.
52 * Be careful
54 If you are using Module::Build or ExtUtils::MakeMaker, so that you
55 can release your module to CPAN, you have to recognize that neither
56 of those programs completely handles version objects natively
57 (yet). If you use version objects with Module::Build, you should
58 add an explicit dependency to the release of version.pm in your
59 Build.PL:
60 my $builder = Module::Build->new(
62 ...
63 requires => {
64 ... ,
65 'version' => 0.50,
66 ...,
67 },
68 ...
69 );
70 and it should Just Work(TM). Module::Build will [hopefully soon]
72 include full support for version objects; there are no current
73 plans to patch ExtUtils::MakeMaker to support version objects.
74 Using modules that use version.pm
76 As much as possible, the version.pm module remains compatible with all
78 current code. However, if your module is using a module that has
79 defined $VERSION using the version class, there are a couple of things
80 to be aware of. For purposes of discussion, we will assume that we
81 have the following module installed:
82 package Example;
84 use version; $VERSION = qv('1.2.2');
85 ...module code here...
86 1;
87 Numeric versions always work
89 Code of the form:
90 use Example 1.002003;
92 will always work correctly. The "use" will perform an automatic
94 $VERSION comparison using the floating point number given as the
95 first term after the module name (e.g. above 1.002.003). In this
96 case, the installed module is too old for the requested line, so
97 you would see an error like:
98 Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
100 Extended version work sometimes
102 With Perl >= 5.6.2, you can also use a line like this:
103 use Example 1.2.3;
105 and it will again work (i.e. give the error message as above), even
107 with releases of Perl which do not normally support v-strings (see
108 "What about v-strings" below). This has to do with that fact that
109 "use" only checks to see if the second term looks like a number and
110 passes that to the replacement UNIVERSAL::VERSION. This is not
111 true in Perl 5.005_04, however, so you are strongly encouraged to
112 always use a numeric version in your code, even for those versions
113 of Perl which support the extended version.
114 What IS a version
116 For the purposes of this module, a version "number" is a sequence of
118 positive integer values separated by one or more decimal points and
119 optionally a single underscore. This corresponds to what Perl itself
120 uses for a version, as well as extending the "version as number" that
121 is discussed in the various editions of the Camel book.
122 There are actually two distinct kinds of version objects:
124 * Numeric Versions
126 Any initial parameter which "looks like a number", see "Numeric
127 Versions". This also covers versions with a single decimal point
128 and a single embedded underscore, see "Numeric Alpha Versions",
129 even though these must be quoted to preserve the underscore format‐
130 ting.
131 * Extended Versions
133 Any initial parameter which contains more than one decimal point
134 and an optional embedded underscore, see "Extended Versions". This
135 is what is commonly used in most open source software as the
136 "external" version (the one used as part of the tag or tarfile
137 name). The use of the exported qv() function also produces this
138 kind of version object.
139 Both of these methods will produce similar version objects, in that the
141 default stringification will yield the version "Normal Form" only if
142 required:
143 $v = version->new(1.002); # 1.002, but compares like 1.2.0
145 $v = version->new(1.002003); # 1.002003
146 $v2 = version->new("1.2.3"); # v1.2.3
147 In specific, version numbers initialized as "Numeric Versions" will
149 stringify as they were originally created (i.e. the same string that
150 was passed to "new()". Version numbers initialized as "Extended Ver‐
151 sions" will be stringified as "Normal Form".
152 Numeric Versions
154 These correspond to historical versions of Perl itself prior to 5.6.0,
156 as well as all other modules which follow the Camel rules for the $VER‐
157 SION scalar. A numeric version is initialized with what looks like a
158 floating point number. Leading zeros are significant and trailing
159 zeros are implied so that a minimum of three places is maintained
160 between subversions. What this means is that any subversion (digits to
161 the right of the decimal place) that contains less than three digits
162 will have trailing zeros added to make up the difference, but only for
163 purposes of comparison with other version objects. For example:
164 # Prints Equivalent to
166 $v = version->new( 1.2); # 1.2 v1.200.0
167 $v = version->new( 1.02); # 1.02 v1.20.0
168 $v = version->new( 1.002); # 1.002 v1.2.0
169 $v = version->new( 1.0023); # 1.0023 v1.2.300
170 $v = version->new( 1.00203); # 1.00203 v1.2.30
171 $v = version->new( 1.002003); # 1.002003 v1.2.3
172 All of the preceding examples are true whether or not the input value
174 is quoted. The important feature is that the input value contains only
175 a single decimal. See also "Alpha Versions" for how to handle
176 IMPORTANT NOTE: As shown above, if your numeric version contains more
178 than 3 significant digits after the decimal place, it will be split on
179 each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the
180 need to remain compatible with Perl's own 5.005_03 == 5.5.30 interpre‐
181 tation. Any trailing zeros are ignored for mathematical comparison
182 purposes.
183 Extended Versions
185 These are the newest form of versions, and correspond to Perl's own
187 version style beginning with 5.6.0. Starting with Perl 5.10.0, and
188 most likely Perl 6, this is likely to be the preferred form. This
189 method normally requires that the input parameter be quoted, although
190 Perl's after 5.8.1 can use v-strings as a special form of quoting, but
191 this is highly discouraged.
192 Unlike "Numeric Versions", Extended Versions have more than a single
194 decimal point, e.g.:
195 # Prints
197 $v = version->new( "v1.200"); # v1.200.0
198 $v = version->new("v1.20.0"); # v1.20.0
199 $v = qv("v1.2.3"); # v1.2.3
200 $v = qv("1.2.3"); # v1.2.3
201 $v = qv("1.20"); # v1.20.0
202 In general, Extended Versions permit the greatest amount of freedom to
204 specify a version, whereas Numeric Versions enforce a certain unifor‐
205 mity. See also "New Operator" for an additional method of initializing
206 version objects.
207 Just like "Numeric Versions", Extended Versions can be used as "Alpha
209 Versions".
210 Numeric Alpha Versions
212 The one time that a numeric version must be quoted is when a alpha form
214 is used with an otherwise numeric version (i.e. a single decimal
215 point). This is commonly used for CPAN releases, where CPAN or CPAN‐
216 PLUS will ignore alpha versions for automatic updating purposes. Since
217 some developers have used only two significant decimal places for their
218 non-alpha releases, the version object will automatically take that
219 into account if the initializer is quoted. For example Module::Example
220 was released to CPAN with the following sequence of $VERSION's:
221 # $VERSION Stringified
223 0.01 0.01
224 0.02 0.02
225 0.02_01 0.02_01
226 0.02_02 0.02_02
227 0.03 0.03
228 etc.
229 The stringified form of numeric versions will always be the same string
231 that was used to initialize the version object.
232 Object Methods
234 Overloading has been used with version objects to provide a natural
236 interface for their use. All mathematical operations are forbidden,
237 since they don't make any sense for base version objects. Conse‐
238 quently, there is no overloaded numification available. If you want to
239 use a version object in a numeric context for some reason, see the
240 numify object method.
241 * New Operator
243 Like all OO interfaces, the new() operator is used to initialize
244 version objects. One way to increment versions when programming is
245 to use the CVS variable $Revision, which is automatically incre‐
246 mented by CVS every time the file is committed to the repository.
247 In order to facilitate this feature, the following code can be
249 employed:
250 $VERSION = version->new(qw$Revision: 2.7 $);
252 and the version object will be created as if the following code
254 were used:
255 $VERSION = version->new("v2.7");
257 In other words, the version will be automatically parsed out of the
259 string, and it will be quoted to preserve the meaning CVS normally
260 carries for versions. The CVS $Revision$ increments differently
261 from numeric versions (i.e. 1.10 follows 1.9), so it must be han‐
262 dled as if it were a "Extended Version".
263 A new version object can be created as a copy of an existing ver‐
265 sion object, either as a class method:
266 $v1 = version->new(12.3);
268 $v2 = version->new($v1);
269 or as an object method:
271 $v1 = version->new(12.3);
273 $v2 = $v1->new(12.3);
274 and in each case, $v1 and $v2 will be identical. NOTE: if you cre‐
276 ate a new object using an existing object like this:
277 $v2 = $v1->new();
279 the new object will not be a clone of the existing object. In the
281 example case, $v2 will be an empty object of the same type as $v1.
282 * qv()
284 An alternate way to create a new version object is through the
285 exported qv() sub. This is not strictly like other q? operators
286 (like qq, qw), in that the only delimiters supported are parenthe‐
287 ses (or spaces). It is the best way to initialize a short version
288 without triggering the floating point interpretation. For example:
289 $v1 = qv(1.2); # 1.2.0
291 $v2 = qv("1.2"); # also 1.2.0
292 As you can see, either a bare number or a quoted string can usually
294 be used interchangably, except in the case of a trailing zero,
295 which must be quoted to be converted properly. For this reason, it
296 is strongly recommended that all initializers to qv() be quoted
297 strings instead of bare numbers.
298 To prevent the "qv()" function from being exported to the caller's
300 namespace, either use version with a null parameter:
301 use version ();
303 or just require version, like this:
305 require version;
307 Both methods will prevent the import() method from firing and
309 exporting the "qv()" sub. This is true of subclasses of version as
310 well, see SUBCLASSING for details.
311 For the subsequent examples, the following three objects will be used:
313 $ver = version->new("1.2.3.4"); # see "Quoting" below
315 $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
316 $nver = version->new(1.002); # see "Numeric Versions" above
317 * Normal Form
319 For any version object which is initialized with multiple decimal
320 places (either quoted or if possible v-string), or initialized
321 using the qv() operator, the stringified representation is returned
322 in a normalized or reduced form (no extraneous zeros), and with a
323 leading 'v':
324 print $ver->normal; # prints as v1.2.3.4
326 print $ver->stringify; # ditto
327 print $ver; # ditto
328 print $nver->normal; # prints as v1.2.0
329 print $nver->stringify; # prints as 1.002, see "Stringification"
330 In order to preserve the meaning of the processed version, the nor‐
332 malized representation will always contain at least three sub
333 terms. In other words, the following is guaranteed to always be
334 true:
335 my $newver = version->new($ver->stringify);
337 if ($newver eq $ver ) # always true
338 {...}
339 * Numification
341 Although all mathematical operations on version objects are forbid‐
342 den by default, it is possible to retrieve a number which corre‐
343 sponds to the version object through the use of the $obj->numify
344 method. For formatting purposes, when displaying a number which
345 corresponds a version object, all sub versions are assumed to have
346 three decimal places. So for example:
347 print $ver->numify; # prints 1.002003004
349 print $nver->numify; # prints 1.002
350 Unlike the stringification operator, there is never any need to
352 append trailing zeros to preserve the correct version value.
353 * Stringification
355 The default stringification for version objects returns exactly the
356 same string as was used to create it, whether you used "new()" or
357 "qv()", with one exception. The sole exception is if the object
358 was created using "qv()" and the initializer did not have two deci‐
359 mal places or a leading 'v' (both optional), then the stringified
360 form will have a leading 'v' prepended, in order to support round-
361 trip processing.
362 For example:
364 Initialized as Stringifies to
366 ============== ==============
367 version->new("1.2") 1.2
368 version->new("v1.2") v1.2
369 qv("1.2.3") 1.2.3
370 qv("v1.3.5") v1.3.5
371 qv("1.2") v1.2 ### exceptional case
372 See also UNIVERSAL::VERSION, as this also returns the stringified
374 form when used as a class method.
375 * Comparison operators
377 Both "cmp" and "<=>" operators perform the same comparison between
378 terms (upgrading to a version object automatically). Perl automat‐
379 ically generates all of the other comparison operators based on
380 those two. In addition to the obvious equalities listed below,
381 appending a single trailing 0 term does not change the value of a
382 version for comparison purposes. In other words "v1.2" and "1.2.0"
383 will compare as identical.
384 For example, the following relations hold:
386 As Number As String Truth Value
388 ------------- ---------------- -----------
389 $ver > 1.0 $ver gt "1.0" true
390 $ver < 2.5 $ver lt true
391 $ver != 1.3 $ver ne "1.3" true
392 $ver == 1.2 $ver eq "1.2" false
393 $ver == 1.2.3.4 $ver eq "1.2.3.4" see discussion below
394 It is probably best to chose either the numeric notation or the
396 string notation and stick with it, to reduce confusion. Perl6 ver‐
397 sion objects may only support numeric comparisons. See also Quot‐
398 ing.
399 WARNING: Comparing version with unequal numbers of decimal points
401 (whether explicitly or implicitly initialized), may yield unex‐
402 pected results at first glance. For example, the following
403 inequalities hold:
404 version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0
406 version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
407 For this reason, it is best to use either exclusively "Numeric Ver‐
409 sions" or "Extended Versions" with multiple decimal points.
410 * Logical Operators
412 If you need to test whether a version object has been initialized,
413 you can simply test it directly:
414 $vobj = version->new($something);
416 if ( $vobj ) # true only if $something was non-blank
417 You can also test whether a version object is an "Alpha version",
419 for example to prevent the use of some feature not present in the
420 main release:
421 $vobj = version->new("1.2_3"); # MUST QUOTE
423 ...later...
424 if ( $vobj->is_alpha ) # True
425 Quoting
427 Because of the nature of the Perl parsing and tokenizing routines, cer‐
429 tain initialization values must be quoted in order to correctly parse
430 as the intended version, especially when using the qv() operator. In
431 all cases, a floating point number passed to version->new() will be
432 identically converted whether or not the value itself is quoted. This
433 is not true for qv(), however, when trailing zeros would be stripped on
434 an unquoted input, which would result in a very different version
435 object.
436 In addition, in order to be compatible with earlier Perl version
438 styles, any use of versions of the form 5.006001 will be translated as
439 v5.6.1. In other words, a version with a single decimal point will be
440 parsed as implicitly having three digits between subversions, but only
441 for internal comparison purposes.
442 The complicating factor is that in bare numbers (i.e. unquoted), the
444 underscore is a legal numeric character and is automatically stripped
445 by the Perl tokenizer before the version code is called. However, if a
446 number containing one or more decimals and an underscore is quoted,
447 i.e. not bare, that is considered a "Alpha Version" and the underscore
448 is significant.
449 If you use a mathematic formula that resolves to a floating point num‐
451 ber, you are dependent on Perl's conversion routines to yield the ver‐
452 sion you expect. You are pretty safe by dividing by a power of 10, for
453 example, but other operations are not likely to be what you intend.
454 For example:
455 $VERSION = version->new((qw$Revision: 1.4)[1]/10);
457 print $VERSION; # yields 0.14
458 $V2 = version->new(100/9); # Integer overflow in decimal number
459 print $V2; # yields something like 11.111.111.100
460 Perl 5.8.1 and beyond will be able to automatically quote v-strings but
462 that is not possible in earlier versions of Perl. In other words:
463 $version = version->new("v2.5.4"); # legal in all versions of Perl
465 $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1
466 What about v-strings?
468 Beginning with Perl 5.6.0, an alternate method to code arbitrary
470 strings of bytes was introduced, called v-strings. They were intended
471 to be an easy way to enter, for example, Unicode strings (which contain
472 two bytes per character). Some programs have used them to encode
473 printer control characters (e.g. CRLF). They were also intended to be
474 used for $VERSION, but their use as such has been problematic from the
475 start.
476 There are two ways to enter v-strings: a bare number with two or more
478 decimal points, or a bare number with one or more decimal points and a
479 leading 'v' character (also bare). For example:
480 $vs1 = 1.2.3; # encoded as \1\2\3
482 $vs2 = v1.2; # encoded as \1\2
483 However, the use of bare v-strings to initialize version objects is
485 strongly discouraged in all circumstances (especially the leading 'v'
486 style), since the meaning will change depending on which Perl you are
487 running. It is better to directly use "Extended Versions" to ensure
488 the proper interpretation.
489 If you insist on using bare v-strings with Perl > 5.6.0, be aware of
491 the following limitations:
492 1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely
494 guesses, based on some characteristics of v-strings. You must use a
495 three part version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to
496 be successful.
497 2) For Perl releases 5.8.1 and later, v-strings have changed in the
499 Perl core to be magical, which means that the version.pm code can auto‐
500 matically determine whether the v-string encoding was used.
501 3) In all cases, a version created using v-strings will have a stringi‐
503 fied form that has a leading 'v' character, for the simple reason that
504 sometimes it is impossible to tell whether one was present initially.
505 Types of Versions Objects
507 There are two types of Version Objects:
509 * Ordinary versions
511 These are the versions that normal modules will use. Can contain
512 as many subversions as required. In particular, those using
513 RCS/CVS can use the following:
514 $VERSION = version->new(qw$Revision: 2.7 $);
516 and the current RCS Revision for that file will be inserted auto‐
518 matically. If the file has been moved to a branch, the Revision
519 will have three or more elements; otherwise, it will have only two.
520 This allows you to automatically increment your module version by
521 using the Revision number from the primary file in a distribution,
522 see "VERSION_FROM" in ExtUtils::MakeMaker.
523 * Alpha Versions
525 For module authors using CPAN, the convention has been to note
526 unstable releases with an underscore in the version string, see
527 CPAN. Alpha releases will test as being newer than the more recent
528 stable release, and less than the next stable release. For exam‐
529 ple:
530 $alphaver = version->new("12.03_01"); # must be quoted
532 obeys the relationship
534 12.03 < $alphaver < 12.04
536 Alpha versions with a single decimal point will be treated exactly
538 as if they were "Numeric Versions", for parsing and output pur‐
539 poses. The underscore will be output when an alpha version is
540 stringified, in the same place as it was when input.
541 Alpha versions with more than a single decimal point will be
543 treated exactly as if they were "Extended Versions", and will dis‐
544 play without any trailing (or leading) zeros, in the "Version Nor‐
545 mal" form. For example,
546 $newver = version->new("12.3.1_1");
548 print $newver; # v12.3.1_1
549 Replacement UNIVERSAL::VERSION
551 In addition to the version objects, this modules also replaces the core
553 UNIVERSAL::VERSION function with one that uses version objects for its
554 comparisons. The return from this operator is always the stringified
555 form, but the warning message generated includes either the stringified
556 form or the normal form, depending on how it was called.
557 For example:
559 package Foo;
561 $VERSION = 1.2;
562 package Bar;
564 $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
565 package main;
567 use version;
568 print $Foo::VERSION; # prints 1.2
570 print $Bar::VERSION; # prints 1.003005
572 eval "use foo 10";
574 print $@; # prints "foo version 10 required..."
575 eval "use foo 1.3.5; # work in Perl 5.6.1 or better
576 print $@; # prints "foo version 1.3.5 required..."
577 eval "use bar 1.3.6";
579 print $@; # prints "bar version 1.3.6 required..."
580 eval "use bar 1.004"; # note numeric version
581 print $@; # prints "bar version 1.004 required..."
582 IMPORTANT NOTE: This may mean that code which searches for a specific
584 string (to determine whether a given module is available) may need to
585 be changed. It is always better to use the built-in comparison
586 implicit in "use" or "require", rather than manually poking at
587 "class-"VERSION> and then doing a comparison yourself.
588 The replacement UNIVERSAL::VERSION, when used as a function, like this:
590 print $module->VERSION;
592 will also exclusively return the stringified form. See Stringification
594 for more details.
595
597 This module is specifically designed and tested to be easily sub‐
598 classed. In practice, you only need to override the methods you want
599 to change, but you have to take some care when overriding new() (since
600 that is where all of the parsing takes place). For example, this is a
601 perfect acceptable derived class:
602 package myversion;
604 use base version;
605 sub new {
606 my($self,$n)=@_;
607 my $obj;
608 # perform any special input handling here
609 $obj = $self->SUPER::new($n);
610 # and/or add additional hash elements here
611 return $obj;
612 }
613 See also version::AlphaBeta on CPAN for an alternate representation of
615 version strings.
616 NOTE: Although the qv operator is not a true class method, but rather a
618 function exported into the caller's namespace, a subclass of version
619 will inherit an import() function which will perform the correct magic
620 on behalf of the subclass.
621
623 qv - Extended Version initialization operator
624
626 John Peacock <jpeacock@cpan.org>
627
629 perl.
630perl v5.8.8 2007-04-17 version(3)