1 #!/usr/local/bin/perl -w
8 use vars qw(@ISA $VERSION $CLASS);
10 @ISA = qw(DynaLoader);
12 $VERSION = (qw$Revision: 2.2 $)[1]/10;
16 bootstrap version if $] < 5.009;
18 # Preloaded methods go here.
25 version - Perl extension for Version Objects
30 $version = new version "12.2.1"; # must be quoted!
31 print $version; # 12.2.1
32 print $version->numify; # 12.002001
33 if ( $version > 12.2 ) # true
35 $vstring = new version qw(v1.2); # must be quoted!
38 $betaver = new version "1.2_3"; # must be quoted!
39 print $betaver; # 1.2_3
41 $perlver = new version "5.005_03"; # must be quoted!
42 print $perlver; # 5.5.30
46 Overloaded version objects for all versions of Perl. This module
47 implments all of the features of version objects which will be part
48 of Perl 5.10.0 except automatic v-string handling. See L<"Quoting">.
50 =head2 What IS a version
52 For the purposes of this module, a version "number" is a sequence of
53 positive integral values separated by decimal points and optionally a
54 single underscore. This corresponds to what Perl itself uses for a
55 version, as well as extending the "version as number" that is discussed
56 in the various editions of the Camel book.
58 However, in order to be compatible with earlier Perl version styles,
59 any use of versions of the form 5.006001 will be translated as 5.6.1,
60 In other words a version with a single decimal place will be parsed
61 as implicitely having three places between subversion.
63 Any value passed to the new() operator will be parsed only so far as it
64 contains a numeric, decimal, or underscore character. So, for example:
66 $v1 = new version "99 and 94/100 percent pure"; # $v1 == 99.0
67 $v2 = new version "something"; # $v2 == "" and $v2->numify == 0
69 NOTE: it is strongly recommended that version objects only be created
70 with numeric values based on the different types of versions in this
71 documentation, see L<"Types of Versions Objects">. That way, there is
72 no confusion about what constitutes the version.
76 Overloading has been used with version objects to provide a natural
77 interface for their use. All mathematical operations are forbidden,
78 since they don't make any sense for versions. For the subsequent
79 examples, the following two objects will be used:
81 $ver = new version "1.2.3"; # see "Quoting" below
82 $beta = new version "1.2_3"; # see "Beta versions" below
84 =item * Stringification - Any time a version object is used as a string,
85 a stringified representation is returned in reduced form (no extraneous
88 print $ver->stringify; # prints 1.2.3
89 print $ver; # same thing
91 =item * Numification - although all mathematical operations on version
92 objects are forbidden by default, it is possible to retrieve a number
93 which roughly corresponds to the version object through the use of the
94 $obj->numify method. For formatting purposes, when displaying a number
95 which corresponds a version object, all sub versions are assumed to have
96 three decimal places. So for example:
98 print $ver->numify; # prints 1.002003
100 =item * Comparison operators - Both cmp and <=> operators perform the
101 same comparison between terms (upgrading to a version object
102 automatically). Perl automatically generates all of the other comparison
103 operators based on those two. For example, the following relations hold:
105 As Number As String Truth Value
106 --------- ------------ -----------
107 $ver > 1.0 $ver gt "1.0" true
108 $ver < 2.5 $ver lt true
109 $ver != 1.3 $ver ne "1.3" true
110 $ver == 1.2 $ver eq "1.2" false
111 $ver == 1.2.3 $ver eq "1.2.3" see discussion below
112 $ver == v1.2.3 $ver eq "v1.2.3" ditto
114 In versions of Perl prior to the 5.9.0 development releases, it is not
115 permitted to use bare v-strings in either form, due to the nature of Perl's
116 parsing operation. After that version (and in the stable 5.10.0 release),
117 v-strings can be used with version objects without problem, see L<"Quoting">
118 for more discussion of this topic. In the case of the last two lines of
119 the table above, only the string comparison will be true; the numerical
120 comparison will test false. However, you can do this:
122 $ver == "1.2.3" or $ver = "v.1.2.3" # both true
124 even though you are doing a "numeric" comparison with a "string" value.
125 It is probably best to chose either the numeric notation or the string
126 notation and stick with it, to reduce confusion. See also L<"Quoting">.
130 Because of the nature of the Perl parsing and tokenizing routines,
131 you should always quote the parameter to the new() operator/method. The
132 exact notation is vitally important to correctly determine the version
133 that is requested. You don't B<have> to quote the version parameter,
134 but you should be aware of what Perl is likely to do in those cases.
136 If you use a mathematic formula that resolves to a floating point number,
137 you are dependent on Perl's conversion routines to yield the version you
138 expect. You are pretty safe by dividing by a power of 10, for example,
139 but other operations are not likely to be what you intend. For example:
141 $VERSION = new version (qw$Revision: 1.4)[1]/10;
142 print $VERSION; # yields 0.14
143 $V2 = new version 100/9; # Integer overflow in decimal number
144 print $V2; # yields 11_1285418553
146 You B<can> use a bare number, if you only have a major and minor version,
147 since this should never in practice yield a floating point notation
150 $VERSION = new version 10.2; # almost certainly ok
151 $VERSION = new version "10.2"; # guaranteed ok
153 Perl 5.9.0 and beyond will be able to automatically quote v-strings
154 (which may become the recommended notation), but that is not possible in
155 earlier versions of Perl. In other words:
157 $version = new version "v2.5.4"; # legal in all versions of Perl
158 $newvers = new version v2.5.4; # legal only in Perl > 5.9.0
161 =head2 Types of Versions Objects
163 There are three basic types of Version Objects:
165 =item * Ordinary versions - These are the versions that normal
166 modules will use. Can contain as many subversions as required.
167 In particular, those using RCS/CVS can use one of the following:
169 $VERSION = new version (qw$Revision: 2.1 $)[1]; # all Perls
170 $VERSION = new version qw$Revision: 2.1 $[1]; # Perl >= 5.6.0
172 and the current RCS Revision for that file will be inserted
173 automatically. If the file has been moved to a branch, the
174 Revision will have three or more elements; otherwise, it will
175 have only two. This allows you to automatically increment
176 your module version by using the Revision number from the primary
177 file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">.
179 =item * Beta versions - For module authors using CPAN, the
180 convention has been to note unstable releases with an underscore
181 in the version string, see L<CPAN>. Beta releases will test as being
182 newer than the more recent stable release, and less than the next
183 stable release. For example:
185 $betaver = new version "12.3_1"; # must quote
187 obeys the relationship
189 12.3 < $betaver < 12.4
191 As a matter of fact, if is also true that
193 12.3.0 < $betaver < 12.3.1
195 where the subversion is identical but the beta release is less than
196 the non-beta release.
198 =item * Perl-style versions - an exceptional case is versions that
199 were only used by Perl releases prior to 5.6.0. If a version
200 string contains an underscore immediately followed by a zero followed
201 by a non-zero number, the version is processed according to the rules
202 described in L<perldelta/Improved Perl version numbering system>
203 released with Perl 5.6.0. As an example:
205 $perlver = new version "5.005_03";
207 is interpreted, not as a beta release, but as the version 5.5.30, NOTE
208 that the major and minor versions are unchanged but the subversion is
209 multiplied by 10, since the above was implicitely read as 5.005.030.
210 There are modules currently on CPAN which may fall under of this rule, so
211 module authors are urged to pay close attention to what version they are
214 =head2 Replacement UNIVERSAL::VERSION
216 In addition to the version objects, this modules also replaces the core
217 UNIVERSAL::VERSION function with one that uses version objects for its
218 comparisons. So, for example, with all existing versions of Perl,
219 something like the following pseudocode would fail:
227 even though those versions are meant to be read as 0.045 and 0.005
228 respectively. The UNIVERSAL::VERSION replacement function included
229 with this module changes that behavior so that it will B<not> fail.
237 John Peacock E<lt>jpeacock@rowman.comE<gt>
244 #!/usr/local/bin/perl -w
252 use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK @EXPORT $VERSION $CLASS);
254 @ISA = qw(Exporter DynaLoader);
256 # This allows declaration use version ':all';
257 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
259 %EXPORT_TAGS = ( 'all' => [ qw(
263 @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
268 $VERSION = (qw$Revision: 1.8 $)[1]/10;
272 bootstrap version if $] < 5.009;
274 # Preloaded methods go here.
281 version - Perl extension for Version Objects
286 $version = new version "12.2.1"; # must be quoted!
287 print $version; # 12.2.1
288 print $version->numify; # 12.002001
289 if ( $version > 12.2 ) # true
291 $vstring = new version qw(v1.2); # must be quoted!
292 print $vstring; # 1.2
294 $betaver = new version "1.2_3"; # must be quoted!
295 print $betaver; # 1.2_3
297 $perlver = new version "5.005_03"; # must be quoted!
298 print $perlver; # 5.5.30
302 Overloaded version objects for all versions of Perl. This module
303 implments all of the features of version objects which will be part
304 of Perl 5.10.0 except automatic v-string handling. See L<"Quoting">.
306 =head2 What IS a version
308 For the purposes of this module, a version "number" is a sequence of
309 positive integral values separated by decimal points and optionally a
310 single underscore. This corresponds to what Perl itself uses for a
311 version, as well as including the "version as number" that is discussed
312 in the various editions of the Camel book.
314 =head2 Object Methods
316 Overloading has been used with version objects to provide a natural
317 interface for their use. All mathematical operations are forbidden,
318 since they don't make any sense for versions. For the subsequent
319 examples, the following two objects will be used:
321 $ver = new version "1.2.3"; # see "Quoting" below
322 $beta = new version "1.2_3"; # see "Beta versions" below
324 =item * Stringification - Any time a version object is used as a string,
325 a stringified representation is returned in reduced form (no extraneous
328 print $ver->stringify; # prints 1.2.3
329 print $ver; # same thing
331 =item * Numification - although all mathematical operations on version
332 objects are forbidden by default, it is possible to retrieve a number
333 which roughly corresponds to the version object through the use of the
334 $obj->numify method. For formatting purposes, when displaying a number
335 which corresponds a version object, all sub versions are assumed to have
336 three decimal places. So for example:
338 print $ver->numify; # prints 1.002003
340 =item * Comparison operators - Both cmp and <=> operators perform the
341 same comparison between terms (upgrading to a version object
342 automatically). Perl automatically generates all of the other comparison
343 operators based on those two. For example, the following relations hold:
345 As Number As String Truth Value
346 --------- ------------ -----------
347 $ver > 1.0 $ver gt "1.0" true
348 $ver < 2.5 $ver lt true
349 $ver != 1.3 $ver ne "1.3" true
350 $ver == 1.2 $ver eq "1.2" false
351 $ver == 1.2.3 $ver eq "1.2.3" see discussion below
352 $ver == v1.2.3 $ver eq "v1.2.3" ditto
354 In versions of Perl prior to the 5.9.0 development releases, it is not
355 permitted to use bare v-strings in either form, due to the nature of Perl's
356 parsing operation. After that version (and in the stable 5.10.0 release),
357 v-strings can be used with version objects without problem, see L<"Quoting">
358 for more discussion of this topic. In the case of the last two lines of
359 the table above, only the string comparison will be true; the numerical
360 comparison will test false. However, you can do this:
362 $ver == "1.2.3" or $ver = "v.1.2.3" # both true
364 even though you are doing a "numeric" comparison with a "string" value.
365 It is probably best to chose either the numeric notation or the string
366 notation and stick with it, to reduce confusion. See also L<"Quoting">.
370 Because of the nature of the Perl parsing and tokenizing routines,
371 you should always quote the parameter to the new() operator/method. The
372 exact notation is vitally important to correctly determine the version
373 that is requested. You don't B<have> to quote the version parameter,
374 but you should be aware of what Perl is likely to do in those cases.
376 If you use a mathematic formula that resolves to a floating point number,
377 you are dependent on Perl's conversion routines to yield the version you
378 expect. You are pretty safe by dividing by a power of 10, for example,
379 but other operations are not likely to be what you intend. For example:
381 $VERSION = new version (qw$Revision: 1.4)[1]/10;
382 print $VERSION; # yields 0.14
383 $V2 = new version 100/9; # Integer overflow in decimal number
384 print $V2; # yields 11_1285418553
386 You B<can> use a bare number, if you only have a major and minor version,
387 since this should never in practice yield a floating point notation
390 $VERSION = new version 10.2; # almost certainly ok
391 $VERSION = new version "10.2"; # guaranteed ok
393 Perl 5.9.0 and beyond will be able to automatically quote v-strings
394 (which may become the recommended notation), but that is not possible in
395 earlier versions of Perl. In other words:
397 $version = new version "v2.5.4"; # legal in all versions of Perl
398 $newvers = new version v2.5.4; # legal only in Perl > 5.9.0
401 =head2 Types of Versions Objects
403 There are three basic types of Version Objects:
405 =item * Ordinary versions - These are the versions that normal
406 modules will use. Can contain as many subversions as required.
407 In particular, those using RCS/CVS can use one of the following:
409 $VERSION = new version (qw$Revision: 1.8 $)[1]; # all Perls
410 $VERSION = new version qw$Revision: 1.8 $[1]; # Perl >= 5.6.0
412 and the current RCS Revision for that file will be inserted
413 automatically. If the file has been moved to a branch, the
414 Revision will have three or more elements; otherwise, it will
415 have only two. This allows you to automatically increment
416 your module version by using the Revision number from the primary
417 file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">.
419 =item * Beta versions - For module authors using CPAN, the
420 convention has been to note unstable releases with an underscore
421 in the version string, see L<CPAN>. Beta releases will test as being
422 newer than the more recent stable release, and less than the next
423 stable release. For example:
425 $betaver = new version "12.3_1"; # must quote
427 obeys the relationship
429 12.3 < $betaver < 12.4
431 As a matter of fact, if is also true that
433 12.3.0 < $betaver < 12.3.1
435 where the subversion is identical but the beta release is less than
436 the non-beta release.
438 =item * Perl-style versions - an exceptional case is versions that
439 were only used by Perl releases prior to 5.6.0. If a version
440 string contains an underscore immediately followed by a zero followed
441 by a non-zero number, the version is processed according to the rules
442 described in L<perldelta/Improved Perl version numbering system>
443 released with Perl 5.6.0. As an example:
445 $perlver = new version "5.005_03";
447 is interpreted, not as a beta release, but as the version 5.5.30, NOTE
448 that the major and minor versions are unchanged but the subversion is
449 multiplied by 10, since the above was implicitely read as 5.005.030.
450 There are modules currently on CPAN which may fall under of this rule, so
451 module authors are urged to pay close attention to what version they are
454 =head2 Replacement UNIVERSAL::VERSION
456 In addition to the version objects, this modules also replaces the core
457 UNIVERSAL::VERSION function with one that uses version objects for its
458 comparisons. So, for example, with all existing versions of Perl,
459 something like the following pseudocode would fail:
467 even though those versions are meant to be read as 0.045 and 0.005
468 respectively. The UNIVERSAL::VERSION replacement function included
469 with this module changes that behavior so that it will B<not> fail.
477 John Peacock E<lt>jpeacock@rowman.comE<gt>