1 #!/usr/local/bin/perl -w
8 use vars qw(@ISA $VERSION $CLASS);
10 @ISA = qw(DynaLoader);
12 $VERSION = (qw$Revision: 2.1 $)[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.
60 Overloading has been used with version objects to provide a natural
61 interface for their use. All mathematical operations are forbidden,
62 since they don't make any sense for versions. For the subsequent
63 examples, the following two objects will be used:
65 $ver = new version "1.2.3"; # see "Quoting" below
66 $beta = new version "1.2_3"; # see "Beta versions" below
68 =item * Stringification - Any time a version object is used as a string,
69 a stringified representation is returned in reduced form (no extraneous
72 print $ver->stringify; # prints 1.2.3
73 print $ver; # same thing
75 =item * Numification - although all mathematical operations on version
76 objects are forbidden by default, it is possible to retrieve a number
77 which roughly corresponds to the version object through the use of the
78 $obj->numify method. For formatting purposes, when displaying a number
79 which corresponds a version object, all sub versions are assumed to have
80 three decimal places. So for example:
82 print $ver->numify; # prints 1.002003
84 =item * Comparison operators - Both cmp and <=> operators perform the
85 same comparison between terms (upgrading to a version object
86 automatically). Perl automatically generates all of the other comparison
87 operators based on those two. For example, the following relations hold:
89 As Number As String Truth Value
90 --------- ------------ -----------
91 $ver > 1.0 $ver gt "1.0" true
92 $ver < 2.5 $ver lt true
93 $ver != 1.3 $ver ne "1.3" true
94 $ver == 1.2 $ver eq "1.2" false
95 $ver == 1.2.3 $ver eq "1.2.3" see discussion below
96 $ver == v1.2.3 $ver eq "v1.2.3" ditto
98 In versions of Perl prior to the 5.9.0 development releases, it is not
99 permitted to use bare v-strings in either form, due to the nature of Perl's
100 parsing operation. After that version (and in the stable 5.10.0 release),
101 v-strings can be used with version objects without problem, see L<"Quoting">
102 for more discussion of this topic. In the case of the last two lines of
103 the table above, only the string comparison will be true; the numerical
104 comparison will test false. However, you can do this:
106 $ver == "1.2.3" or $ver = "v.1.2.3" # both true
108 even though you are doing a "numeric" comparison with a "string" value.
109 It is probably best to chose either the numeric notation or the string
110 notation and stick with it, to reduce confusion. See also L<"Quoting">.
114 Because of the nature of the Perl parsing and tokenizing routines,
115 you should always quote the parameter to the new() operator/method. The
116 exact notation is vitally important to correctly determine the version
117 that is requested. You don't B<have> to quote the version parameter,
118 but you should be aware of what Perl is likely to do in those cases.
120 If you use a mathematic formula that resolves to a floating point number,
121 you are dependent on Perl's conversion routines to yield the version you
122 expect. You are pretty safe by dividing by a power of 10, for example,
123 but other operations are not likely to be what you intend. For example:
125 $VERSION = new version (qw$Revision: 1.4)[1]/10;
126 print $VERSION; # yields 0.14
127 $V2 = new version 100/9; # Integer overflow in decimal number
128 print $V2; # yields 11_1285418553
130 You B<can> use a bare number, if you only have a major and minor version,
131 since this should never in practice yield a floating point notation
134 $VERSION = new version 10.2; # almost certainly ok
135 $VERSION = new version "10.2"; # guaranteed ok
137 Perl 5.9.0 and beyond will be able to automatically quote v-strings
138 (which may become the recommended notation), but that is not possible in
139 earlier versions of Perl. In other words:
141 $version = new version "v2.5.4"; # legal in all versions of Perl
142 $newvers = new version v2.5.4; # legal only in Perl > 5.9.0
145 =head2 Types of Versions Objects
147 There are three basic types of Version Objects:
149 =item * Ordinary versions - These are the versions that normal
150 modules will use. Can contain as many subversions as required.
151 In particular, those using RCS/CVS can use one of the following:
153 $VERSION = new version (qw$Revision: 2.1 $)[1]; # all Perls
154 $VERSION = new version qw$Revision: 2.1 $[1]; # Perl >= 5.6.0
156 and the current RCS Revision for that file will be inserted
157 automatically. If the file has been moved to a branch, the
158 Revision will have three or more elements; otherwise, it will
159 have only two. This allows you to automatically increment
160 your module version by using the Revision number from the primary
161 file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">.
163 In order to be compatible with earlier Perl version styles, any use
164 of versions of the form 5.006001 will be translated as 5.6.1, In
165 other words a version with a single decimal place will be parsed
166 as implicitely having three places between subversion.
168 =item * Beta versions - For module authors using CPAN, the
169 convention has been to note unstable releases with an underscore
170 in the version string, see L<CPAN>. Beta releases will test as being
171 newer than the more recent stable release, and less than the next
172 stable release. For example:
174 $betaver = new version "12.3_1"; # must quote
176 obeys the relationship
178 12.3 < $betaver < 12.4
180 As a matter of fact, if is also true that
182 12.3.0 < $betaver < 12.3.1
184 where the subversion is identical but the beta release is less than
185 the non-beta release.
187 =item * Perl-style versions - an exceptional case is versions that
188 were only used by Perl releases prior to 5.6.0. If a version
189 string contains an underscore immediately followed by a zero followed
190 by a non-zero number, the version is processed according to the rules
191 described in L<perldelta/Improved Perl version numbering system>
192 released with Perl 5.6.0. As an example:
194 $perlver = new version "5.005_03";
196 is interpreted, not as a beta release, but as the version 5.5.30, NOTE
197 that the major and minor versions are unchanged but the subversion is
198 multiplied by 10, since the above was implicitely read as 5.005.030.
199 There are modules currently on CPAN which may fall under of this rule, so
200 module authors are urged to pay close attention to what version they are
203 =head2 Replacement UNIVERSAL::VERSION
205 In addition to the version objects, this modules also replaces the core
206 UNIVERSAL::VERSION function with one that uses version objects for its
207 comparisons. So, for example, with all existing versions of Perl,
208 something like the following pseudocode would fail:
216 even though those versions are meant to be read as 0.045 and 0.005
217 respectively. The UNIVERSAL::VERSION replacement function included
218 with this module changes that behavior so that it will B<not> fail.
226 John Peacock E<lt>jpeacock@rowman.comE<gt>
233 #!/usr/local/bin/perl -w
241 use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK @EXPORT $VERSION $CLASS);
243 @ISA = qw(Exporter DynaLoader);
245 # This allows declaration use version ':all';
246 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
248 %EXPORT_TAGS = ( 'all' => [ qw(
252 @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
257 $VERSION = (qw$Revision: 1.8 $)[1]/10;
261 bootstrap version if $] < 5.009;
263 # Preloaded methods go here.
270 version - Perl extension for Version Objects
275 $version = new version "12.2.1"; # must be quoted!
276 print $version; # 12.2.1
277 print $version->numify; # 12.002001
278 if ( $version > 12.2 ) # true
280 $vstring = new version qw(v1.2); # must be quoted!
281 print $vstring; # 1.2
283 $betaver = new version "1.2_3"; # must be quoted!
284 print $betaver; # 1.2_3
286 $perlver = new version "5.005_03"; # must be quoted!
287 print $perlver; # 5.5.30
291 Overloaded version objects for all versions of Perl. This module
292 implments all of the features of version objects which will be part
293 of Perl 5.10.0 except automatic v-string handling. See L<"Quoting">.
295 =head2 What IS a version
297 For the purposes of this module, a version "number" is a sequence of
298 positive integral values separated by decimal points and optionally a
299 single underscore. This corresponds to what Perl itself uses for a
300 version, as well as including the "version as number" that is discussed
301 in the various editions of the Camel book.
303 =head2 Object Methods
305 Overloading has been used with version objects to provide a natural
306 interface for their use. All mathematical operations are forbidden,
307 since they don't make any sense for versions. For the subsequent
308 examples, the following two objects will be used:
310 $ver = new version "1.2.3"; # see "Quoting" below
311 $beta = new version "1.2_3"; # see "Beta versions" below
313 =item * Stringification - Any time a version object is used as a string,
314 a stringified representation is returned in reduced form (no extraneous
317 print $ver->stringify; # prints 1.2.3
318 print $ver; # same thing
320 =item * Numification - although all mathematical operations on version
321 objects are forbidden by default, it is possible to retrieve a number
322 which roughly corresponds to the version object through the use of the
323 $obj->numify method. For formatting purposes, when displaying a number
324 which corresponds a version object, all sub versions are assumed to have
325 three decimal places. So for example:
327 print $ver->numify; # prints 1.002003
329 =item * Comparison operators - Both cmp and <=> operators perform the
330 same comparison between terms (upgrading to a version object
331 automatically). Perl automatically generates all of the other comparison
332 operators based on those two. For example, the following relations hold:
334 As Number As String Truth Value
335 --------- ------------ -----------
336 $ver > 1.0 $ver gt "1.0" true
337 $ver < 2.5 $ver lt true
338 $ver != 1.3 $ver ne "1.3" true
339 $ver == 1.2 $ver eq "1.2" false
340 $ver == 1.2.3 $ver eq "1.2.3" see discussion below
341 $ver == v1.2.3 $ver eq "v1.2.3" ditto
343 In versions of Perl prior to the 5.9.0 development releases, it is not
344 permitted to use bare v-strings in either form, due to the nature of Perl's
345 parsing operation. After that version (and in the stable 5.10.0 release),
346 v-strings can be used with version objects without problem, see L<"Quoting">
347 for more discussion of this topic. In the case of the last two lines of
348 the table above, only the string comparison will be true; the numerical
349 comparison will test false. However, you can do this:
351 $ver == "1.2.3" or $ver = "v.1.2.3" # both true
353 even though you are doing a "numeric" comparison with a "string" value.
354 It is probably best to chose either the numeric notation or the string
355 notation and stick with it, to reduce confusion. See also L<"Quoting">.
359 Because of the nature of the Perl parsing and tokenizing routines,
360 you should always quote the parameter to the new() operator/method. The
361 exact notation is vitally important to correctly determine the version
362 that is requested. You don't B<have> to quote the version parameter,
363 but you should be aware of what Perl is likely to do in those cases.
365 If you use a mathematic formula that resolves to a floating point number,
366 you are dependent on Perl's conversion routines to yield the version you
367 expect. You are pretty safe by dividing by a power of 10, for example,
368 but other operations are not likely to be what you intend. For example:
370 $VERSION = new version (qw$Revision: 1.4)[1]/10;
371 print $VERSION; # yields 0.14
372 $V2 = new version 100/9; # Integer overflow in decimal number
373 print $V2; # yields 11_1285418553
375 You B<can> use a bare number, if you only have a major and minor version,
376 since this should never in practice yield a floating point notation
379 $VERSION = new version 10.2; # almost certainly ok
380 $VERSION = new version "10.2"; # guaranteed ok
382 Perl 5.9.0 and beyond will be able to automatically quote v-strings
383 (which may become the recommended notation), but that is not possible in
384 earlier versions of Perl. In other words:
386 $version = new version "v2.5.4"; # legal in all versions of Perl
387 $newvers = new version v2.5.4; # legal only in Perl > 5.9.0
390 =head2 Types of Versions Objects
392 There are three basic types of Version Objects:
394 =item * Ordinary versions - These are the versions that normal
395 modules will use. Can contain as many subversions as required.
396 In particular, those using RCS/CVS can use one of the following:
398 $VERSION = new version (qw$Revision: 1.8 $)[1]; # all Perls
399 $VERSION = new version qw$Revision: 1.8 $[1]; # Perl >= 5.6.0
401 and the current RCS Revision for that file will be inserted
402 automatically. If the file has been moved to a branch, the
403 Revision will have three or more elements; otherwise, it will
404 have only two. This allows you to automatically increment
405 your module version by using the Revision number from the primary
406 file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">.
408 =item * Beta versions - For module authors using CPAN, the
409 convention has been to note unstable releases with an underscore
410 in the version string, see L<CPAN>. Beta releases will test as being
411 newer than the more recent stable release, and less than the next
412 stable release. For example:
414 $betaver = new version "12.3_1"; # must quote
416 obeys the relationship
418 12.3 < $betaver < 12.4
420 As a matter of fact, if is also true that
422 12.3.0 < $betaver < 12.3.1
424 where the subversion is identical but the beta release is less than
425 the non-beta release.
427 =item * Perl-style versions - an exceptional case is versions that
428 were only used by Perl releases prior to 5.6.0. If a version
429 string contains an underscore immediately followed by a zero followed
430 by a non-zero number, the version is processed according to the rules
431 described in L<perldelta/Improved Perl version numbering system>
432 released with Perl 5.6.0. As an example:
434 $perlver = new version "5.005_03";
436 is interpreted, not as a beta release, but as the version 5.5.30, NOTE
437 that the major and minor versions are unchanged but the subversion is
438 multiplied by 10, since the above was implicitely read as 5.005.030.
439 There are modules currently on CPAN which may fall under of this rule, so
440 module authors are urged to pay close attention to what version they are
443 =head2 Replacement UNIVERSAL::VERSION
445 In addition to the version objects, this modules also replaces the core
446 UNIVERSAL::VERSION function with one that uses version objects for its
447 comparisons. So, for example, with all existing versions of Perl,
448 something like the following pseudocode would fail:
456 even though those versions are meant to be read as 0.045 and 0.005
457 respectively. The UNIVERSAL::VERSION replacement function included
458 with this module changes that behavior so that it will B<not> fail.
466 John Peacock E<lt>jpeacock@rowman.comE<gt>