1 #!/usr/local/bin/perl -w
8 use vars qw(@ISA $VERSION $CLASS);
10 @ISA = qw(DynaLoader);
12 $VERSION = (qw$Revision: 2.3 $)[1]/10;
16 local $^W; # shut up the 'redefined' warning for UNIVERSAL::VERSION
17 bootstrap version if $] < 5.009;
19 # Preloaded methods go here.
26 version - Perl extension for Version Objects
31 $version = new version "12.2.1"; # must be quoted!
32 print $version; # 12.2.1
33 print $version->numify; # 12.002001
34 if ( $version > 12.2 ) # true
36 $vstring = new version qw(v1.2); # must be quoted!
39 $betaver = new version "1.2_3"; # must be quoted!
40 print $betaver; # 1.2_3
42 $perlver = new version "5.005_03"; # must be quoted!
43 print $perlver; # 5.5.30
47 Overloaded version objects for all versions of Perl. This module
48 implements all of the features of version objects which will be part
49 of Perl 5.10.0 except automatic v-string handling. See L<"Quoting">.
51 =head2 What IS a version
53 For the purposes of this module, a version "number" is a sequence of
54 positive integral values separated by decimal points and optionally a
55 single underscore. This corresponds to what Perl itself uses for a
56 version, as well as extending the "version as number" that is discussed
57 in the various editions of the Camel book.
59 However, in order to be compatible with earlier Perl version styles,
60 any use of versions of the form 5.006001 will be translated as 5.6.1,
61 In other words, a version with a single decimal place will be parsed
62 as implicitly having three places between subversion.
64 Any value passed to the new() operator will be parsed only so far as it
65 contains a numeric, decimal, or underscore character. So, for example:
67 $v1 = new version "99 and 94/100 percent pure"; # $v1 == 99.0
68 $v2 = new version "something"; # $v2 == "" and $v2->numify == 0
70 NOTE: it is strongly recommended that version objects only be created
71 with numeric values based on the different types of versions in this
72 documentation, see L<"Types of Versions Objects">. That way, there is
73 no confusion about what constitutes the version.
77 Overloading has been used with version objects to provide a natural
78 interface for their use. All mathematical operations are forbidden,
79 since they don't make any sense for versions. For the subsequent
80 examples, the following two objects will be used:
82 $ver = new version "1.2.3"; # see "Quoting" below
83 $beta = new version "1.2_3"; # see "Beta versions" below
85 =item * Stringification - Any time a version object is used as a string,
86 a stringified representation is returned in reduced form (no extraneous
89 print $ver->stringify; # prints 1.2.3
90 print $ver; # same thing
92 =item * Numification - although all mathematical operations on version
93 objects are forbidden by default, it is possible to retrieve a number
94 which roughly corresponds to the version object through the use of the
95 $obj->numify method. For formatting purposes, when displaying a number
96 which corresponds a version object, all sub versions are assumed to have
97 three decimal places. So for example:
99 print $ver->numify; # prints 1.002003
101 =item * Comparison operators - Both cmp and <=> operators perform the
102 same comparison between terms (upgrading to a version object
103 automatically). Perl automatically generates all of the other comparison
104 operators based on those two. For example, the following relations hold:
106 As Number As String Truth Value
107 --------- ------------ -----------
108 $ver > 1.0 $ver gt "1.0" true
109 $ver < 2.5 $ver lt true
110 $ver != 1.3 $ver ne "1.3" true
111 $ver == 1.2 $ver eq "1.2" false
112 $ver == 1.2.3 $ver eq "1.2.3" see discussion below
113 $ver == v1.2.3 $ver eq "v1.2.3" ditto
115 In versions of Perl prior to the 5.9.0 development releases, it is not
116 permitted to use bare v-strings in either form, due to the nature of Perl's
117 parsing operation. After that version (and in the stable 5.10.0 release),
118 v-strings can be used with version objects without problem, see L<"Quoting">
119 for more discussion of this topic. In the case of the last two lines of
120 the table above, only the string comparison will be true; the numerical
121 comparison will test false. However, you can do this:
123 $ver == "1.2.3" or $ver == "v1.2.3" # both true
125 even though you are doing a "numeric" comparison with a "string" value.
126 It is probably best to chose either the numeric notation or the string
127 notation and stick with it, to reduce confusion. See also L<"Quoting">.
131 Because of the nature of the Perl parsing and tokenizing routines,
132 you should always quote the parameter to the new() operator/method. The
133 exact notation is vitally important to correctly determine the version
134 that is requested. You don't B<have> to quote the version parameter,
135 but you should be aware of what Perl is likely to do in those cases.
137 If you use a mathematic formula that resolves to a floating point number,
138 you are dependent on Perl's conversion routines to yield the version you
139 expect. You are pretty safe by dividing by a power of 10, for example,
140 but other operations are not likely to be what you intend. For example:
142 $VERSION = new version (qw$Revision: 1.4)[1]/10;
143 print $VERSION; # yields 0.14
144 $V2 = new version 100/9; # Integer overflow in decimal number
145 print $V2; # yields 11_1285418553
147 You B<can> use a bare number, if you only have a major and minor version,
148 since this should never in practice yield a floating point notation
151 $VERSION = new version 10.2; # almost certainly ok
152 $VERSION = new version "10.2"; # guaranteed ok
154 Perl 5.9.0 and beyond will be able to automatically quote v-strings
155 (which may become the recommended notation), but that is not possible in
156 earlier versions of Perl. In other words:
158 $version = new version "v2.5.4"; # legal in all versions of Perl
159 $newvers = new version v2.5.4; # legal only in Perl > 5.9.0
162 =head2 Types of Versions Objects
164 There are three basic types of Version Objects:
166 =item * Ordinary versions - These are the versions that normal
167 modules will use. Can contain as many subversions as required.
168 In particular, those using RCS/CVS can use one of the following:
170 $VERSION = new version (qw$Revision: 2.3 $)[1]; # all Perls
171 $VERSION = new version qw$Revision: 2.3 $[1]; # Perl >= 5.6.0
173 and the current RCS Revision for that file will be inserted
174 automatically. If the file has been moved to a branch, the
175 Revision will have three or more elements; otherwise, it will
176 have only two. This allows you to automatically increment
177 your module version by using the Revision number from the primary
178 file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">.
180 =item * Beta versions - For module authors using CPAN, the
181 convention has been to note unstable releases with an underscore
182 in the version string, see L<CPAN>. Beta releases will test as being
183 newer than the more recent stable release, and less than the next
184 stable release. For example:
186 $betaver = new version "12.3_1"; # must quote
188 obeys the relationship
190 12.3 < $betaver < 12.4
192 As a matter of fact, if is also true that
194 12.3.0 < $betaver < 12.3.1
196 where the subversion is identical but the beta release is less than
197 the non-beta release.
199 =item * Perl-style versions - an exceptional case is versions that
200 were only used by Perl releases prior to 5.6.0. If a version
201 string contains an underscore immediately followed by a zero followed
202 by a non-zero number, the version is processed according to the rules
203 described in L<perldelta/Improved Perl version numbering system>
204 released with Perl 5.6.0. As an example:
206 $perlver = new version "5.005_03";
208 is interpreted, not as a beta release, but as the version 5.5.30, NOTE
209 that the major and minor versions are unchanged but the subversion is
210 multiplied by 10, since the above was implicitly read as 5.005.030.
211 There are modules currently on CPAN which may fall under of this rule, so
212 module authors are urged to pay close attention to what version they are
215 =head2 Replacement UNIVERSAL::VERSION
217 In addition to the version objects, this modules also replaces the core
218 UNIVERSAL::VERSION function with one that uses version objects for its
219 comparisons. So, for example, with all existing versions of Perl,
220 something like the following pseudocode would fail:
228 even though those versions are meant to be read as 0.045 and 0.005
229 respectively. The UNIVERSAL::VERSION replacement function included
230 with this module changes that behavior so that it will B<not> fail.
238 John Peacock E<lt>jpeacock@rowman.comE<gt>