Commit | Line | Data |
a7ad731c |
1 | #!/usr/local/bin/perl -w |
2 | package version; |
3 | |
4 | use 5.005_03; |
5 | use strict; |
6 | |
7 | require DynaLoader; |
8 | use vars qw(@ISA $VERSION $CLASS); |
9 | |
10 | @ISA = qw(DynaLoader); |
11 | |
26ec6fc3 |
12 | $VERSION = (qw$Revision: 2.3 $)[1]/10; |
a7ad731c |
13 | |
14 | $CLASS = 'version'; |
15 | |
26ec6fc3 |
16 | local $^W; # shut up the 'redefined' warning for UNIVERSAL::VERSION |
a7ad731c |
17 | bootstrap version if $] < 5.009; |
18 | |
19 | # Preloaded methods go here. |
20 | |
21 | 1; |
22 | __END__ |
23 | |
24 | =head1 NAME |
25 | |
26 | version - Perl extension for Version Objects |
27 | |
28 | =head1 SYNOPSIS |
29 | |
30 | use version; |
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 |
35 | |
36 | $vstring = new version qw(v1.2); # must be quoted! |
37 | print $vstring; # 1.2 |
38 | |
39 | $betaver = new version "1.2_3"; # must be quoted! |
40 | print $betaver; # 1.2_3 |
41 | |
42 | $perlver = new version "5.005_03"; # must be quoted! |
43 | print $perlver; # 5.5.30 |
44 | |
45 | =head1 DESCRIPTION |
46 | |
47 | Overloaded version objects for all versions of Perl. This module |
26ec6fc3 |
48 | implements all of the features of version objects which will be part |
a7ad731c |
49 | of Perl 5.10.0 except automatic v-string handling. See L<"Quoting">. |
50 | |
51 | =head2 What IS a version |
52 | |
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. |
58 | |
46314c13 |
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, |
26ec6fc3 |
61 | In other words, a version with a single decimal place will be parsed |
62 | as implicitly having three places between subversion. |
46314c13 |
63 | |
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: |
66 | |
67 | $v1 = new version "99 and 94/100 percent pure"; # $v1 == 99.0 |
68 | $v2 = new version "something"; # $v2 == "" and $v2->numify == 0 |
69 | |
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. |
74 | |
a7ad731c |
75 | =head2 Object Methods |
76 | |
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: |
81 | |
82 | $ver = new version "1.2.3"; # see "Quoting" below |
83 | $beta = new version "1.2_3"; # see "Beta versions" below |
84 | |
85 | =item * Stringification - Any time a version object is used as a string, |
86 | a stringified representation is returned in reduced form (no extraneous |
87 | zeros): |
88 | |
89 | print $ver->stringify; # prints 1.2.3 |
90 | print $ver; # same thing |
91 | |
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: |
98 | |
99 | print $ver->numify; # prints 1.002003 |
100 | |
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: |
105 | |
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 |
114 | |
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: |
122 | |
26ec6fc3 |
123 | $ver == "1.2.3" or $ver == "v1.2.3" # both true |
a7ad731c |
124 | |
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">. |
128 | |
129 | =head2 Quoting |
130 | |
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. |
136 | |
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: |
141 | |
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 |
146 | |
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 |
149 | error. For example: |
150 | |
151 | $VERSION = new version 10.2; # almost certainly ok |
152 | $VERSION = new version "10.2"; # guaranteed ok |
153 | |
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: |
157 | |
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 |
160 | |
161 | |
162 | =head2 Types of Versions Objects |
163 | |
164 | There are three basic types of Version Objects: |
165 | |
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: |
169 | |
26ec6fc3 |
170 | $VERSION = new version (qw$Revision: 2.3 $)[1]; # all Perls |
171 | $VERSION = new version qw$Revision: 2.3 $[1]; # Perl >= 5.6.0 |
a7ad731c |
172 | |
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">. |
179 | |
a7ad731c |
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: |
185 | |
186 | $betaver = new version "12.3_1"; # must quote |
187 | |
188 | obeys the relationship |
189 | |
190 | 12.3 < $betaver < 12.4 |
191 | |
192 | As a matter of fact, if is also true that |
193 | |
194 | 12.3.0 < $betaver < 12.3.1 |
195 | |
196 | where the subversion is identical but the beta release is less than |
197 | the non-beta release. |
198 | |
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: |
205 | |
206 | $perlver = new version "5.005_03"; |
207 | |
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 |
26ec6fc3 |
210 | multiplied by 10, since the above was implicitly read as 5.005.030. |
a7ad731c |
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 |
213 | specifying. |
214 | |
215 | =head2 Replacement UNIVERSAL::VERSION |
216 | |
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: |
221 | |
222 | package vertest; |
223 | $VERSION = 0.45; |
224 | |
225 | package main; |
226 | use vertest 0.5; |
227 | |
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. |
231 | |
232 | =head1 EXPORT |
233 | |
234 | None by default. |
235 | |
236 | =head1 AUTHOR |
237 | |
238 | John Peacock E<lt>jpeacock@rowman.comE<gt> |
239 | |
240 | =head1 SEE ALSO |
241 | |
242 | L<perl>. |
243 | |
244 | =cut |