Commit | Line | Data |
129318bd |
1 | #!/usr/bin/perl -w |
a7ad731c |
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 | |
129318bd |
12 | $VERSION = (qw$Revision: 2.7 $)[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 |
129318bd |
34 | if ( $version gt "v12.2" ) # true |
a7ad731c |
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 | |
129318bd |
42 | $perlver = new version 5.005_03; # must not be quoted! |
a7ad731c |
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 | |
129318bd |
59 | There are actually two distinct ways to initialize versions: |
60 | |
61 | =over 4 |
62 | |
63 | =item * Numeric Versions - any initial parameter which "looks like |
64 | a number", see L<Numeric Versions>. |
65 | |
66 | =item * V-String Versions - any initial parameter which contains more |
67 | than one decimal point, contains an embedded underscore, or has a |
68 | leading 'v' see L<V-String Versions>. |
69 | |
70 | =back |
71 | |
72 | Both of these methods will produce similar version objects, in that |
73 | the default stringification will always be in a reduced form, i.e.: |
74 | |
75 | $v = new version 1.002003; # 1.2.3 |
76 | $v2 = new version "1.2.3"; # 1.2.3 |
77 | $v3 = new version v1.2.3; # 1.2.3 for Perl > v5.8.0 |
78 | $v4 = new version 1.2.3; # 1.2.3 for Perl > v5.8.0 |
79 | |
80 | Please see L<Quoting> for more details on how Perl will parse various |
81 | input values. |
46314c13 |
82 | |
83 | Any value passed to the new() operator will be parsed only so far as it |
84 | contains a numeric, decimal, or underscore character. So, for example: |
85 | |
86 | $v1 = new version "99 and 94/100 percent pure"; # $v1 == 99.0 |
87 | $v2 = new version "something"; # $v2 == "" and $v2->numify == 0 |
88 | |
129318bd |
89 | However, see L<New Operator> for one case where non-numeric text is |
90 | acceptable when initializing version objects. |
91 | |
92 | =head2 Numeric Versions |
93 | |
94 | These correspond to historical versions of Perl itself prior to v5.6.0, |
95 | as well as all other modules which follow the Camel rules for the |
96 | $VERSION scalar. A numeric version is initialized with what looks like |
97 | a floating point number. Leading zeros B<are> significant and trailing |
98 | zeros are implied so that a minimum of three places is maintained |
99 | between subversions. What this means is that any subversion (digits |
100 | to the right of the decimal place) that contains less than three digits |
101 | will have trailing zeros added to make up the difference. For example: |
102 | |
103 | $v = new version 1.2; # 1.200 |
104 | $v = new version 1.02; # 1.20 |
105 | $v = new version 1.002; # 1.2 |
106 | $v = new version 1.0023; # 1.2.300 |
107 | $v = new version 1.00203; # 1.2.30 |
108 | $v = new version 1.002_03; # 1.2.30 See L<Quoting> |
109 | $v = new version 1.002003; # 1.2.3 |
110 | |
111 | All of the preceeding examples except the second to last are true |
112 | whether or not the input value is quoted. The important feature is that |
113 | the input value contains only a single decimal. |
114 | |
115 | =head2 V-String Versions |
116 | |
117 | These are the newest form of versions, and correspond to Perl's own |
118 | version style beginning with v5.6.0. Starting with Perl v5.10.0, |
119 | this is likely to be the preferred form. This method requires that |
120 | the input parameter be quoted, although Perl > v5.9.0 can use bare |
121 | v-strings as a special form of quoting. |
122 | |
123 | Unlike L<Numeric Versions>, V-String Versions must either have more than |
124 | a single decimal point, e.g. "5.6.1" B<or> must be prefaced by a "v" |
125 | like this "v5.6" (much like v-string notation). In fact, with the |
126 | newest Perl v-strings themselves can be used to initialize version |
127 | objects. Also unlike L<Numeric Versions>, leading zeros are B<not> |
128 | significant, and trailing zeros must be explicitely specified (i.e. |
129 | will not be automatically added). In addition, the subversions are |
130 | not enforced to be three decimal places. |
131 | |
132 | So, for example: |
133 | |
134 | $v = new version "v1.2"; # 1.2 |
135 | $v = new version "v1.002"; # 1.2 |
136 | $v = new version "1.2.3"; # 1.2.3 |
137 | $v = new version "v1.2.3"; # 1.2.3 |
138 | $v = new version "v1.0003"; # 1.3 |
139 | |
140 | In additional to conventional versions, V-String Versions can be |
141 | used to create L<Beta Versions>. |
142 | |
143 | In general, V-String Versions permit the greatest amount of freedom |
144 | to specify a version, whereas Numeric Versions enforce a certain |
145 | uniformity. See also L<New Operator> for an additional method of |
146 | initializing version objects. |
46314c13 |
147 | |
a7ad731c |
148 | =head2 Object Methods |
149 | |
150 | Overloading has been used with version objects to provide a natural |
151 | interface for their use. All mathematical operations are forbidden, |
129318bd |
152 | since they don't make any sense for versions. |
153 | |
154 | =over 4 |
155 | |
156 | =item * New Operator - Like all OO interfaces, the new() operator is |
157 | used to initialize version objects. One way to increment versions |
158 | when programming is to use the CVS variable $Revision, which is |
159 | automatically incremented by CVS every time the file is committed to |
160 | the repository. |
161 | |
162 | =back |
163 | |
164 | In order to facilitate this feature, the following |
165 | code can be employed: |
166 | |
167 | $VERSION = new version qw$Revision: 2.7 $; |
168 | |
169 | and the version object will be created as if the following code |
170 | were used: |
171 | |
172 | $VERSION = new version "v2.6"; |
173 | |
174 | In other words, the version will be automatically parsed out of the |
175 | string, and it will be quoted to preserve the meaning CVS normally |
176 | carries for versions. |
177 | |
178 | For the subsequent examples, the following two objects will be used: |
a7ad731c |
179 | |
180 | $ver = new version "1.2.3"; # see "Quoting" below |
181 | $beta = new version "1.2_3"; # see "Beta versions" below |
182 | |
129318bd |
183 | =over 4 |
184 | |
a7ad731c |
185 | =item * Stringification - Any time a version object is used as a string, |
186 | a stringified representation is returned in reduced form (no extraneous |
187 | zeros): |
188 | |
129318bd |
189 | =back |
190 | |
a7ad731c |
191 | print $ver->stringify; # prints 1.2.3 |
192 | print $ver; # same thing |
193 | |
129318bd |
194 | =over 4 |
195 | |
a7ad731c |
196 | =item * Numification - although all mathematical operations on version |
197 | objects are forbidden by default, it is possible to retrieve a number |
198 | which roughly corresponds to the version object through the use of the |
199 | $obj->numify method. For formatting purposes, when displaying a number |
200 | which corresponds a version object, all sub versions are assumed to have |
201 | three decimal places. So for example: |
202 | |
129318bd |
203 | =back |
204 | |
a7ad731c |
205 | print $ver->numify; # prints 1.002003 |
206 | |
129318bd |
207 | =over 4 |
208 | |
a7ad731c |
209 | =item * Comparison operators - Both cmp and <=> operators perform the |
210 | same comparison between terms (upgrading to a version object |
211 | automatically). Perl automatically generates all of the other comparison |
129318bd |
212 | operators based on those two. In addition to the obvious equalities |
213 | listed below, appending a single trailing 0 term does not change the |
214 | value of a version for comparison purposes. In other words "v1.2" and |
215 | "v1.2.0" are identical versions. |
216 | |
217 | =back |
218 | |
219 | For example, the following relations hold: |
a7ad731c |
220 | |
129318bd |
221 | As Number As String Truth Value |
222 | --------- ------------ ----------- |
a7ad731c |
223 | $ver > 1.0 $ver gt "1.0" true |
224 | $ver < 2.5 $ver lt true |
225 | $ver != 1.3 $ver ne "1.3" true |
226 | $ver == 1.2 $ver eq "1.2" false |
227 | $ver == 1.2.3 $ver eq "1.2.3" see discussion below |
228 | $ver == v1.2.3 $ver eq "v1.2.3" ditto |
229 | |
230 | In versions of Perl prior to the 5.9.0 development releases, it is not |
231 | permitted to use bare v-strings in either form, due to the nature of Perl's |
232 | parsing operation. After that version (and in the stable 5.10.0 release), |
233 | v-strings can be used with version objects without problem, see L<"Quoting"> |
234 | for more discussion of this topic. In the case of the last two lines of |
235 | the table above, only the string comparison will be true; the numerical |
236 | comparison will test false. However, you can do this: |
237 | |
26ec6fc3 |
238 | $ver == "1.2.3" or $ver == "v1.2.3" # both true |
a7ad731c |
239 | |
240 | even though you are doing a "numeric" comparison with a "string" value. |
241 | It is probably best to chose either the numeric notation or the string |
242 | notation and stick with it, to reduce confusion. See also L<"Quoting">. |
243 | |
244 | =head2 Quoting |
245 | |
246 | Because of the nature of the Perl parsing and tokenizing routines, |
129318bd |
247 | certain initialization values B<must> be quoted in order to correctly |
248 | parse as the intended version, and additionally, some initial values |
249 | B<must not> be quoted to obtain the intended version. |
250 | |
251 | Except for L<Beta versions>, any version initialized with something |
252 | that looks like a number (a single decimal place) will be parsed in |
253 | the same way whether or not the term is quoted. In order to be |
254 | compatible with earlier Perl version styles, any use of versions of |
255 | the form 5.006001 will be translated as 5.6.1. In other words, a |
256 | version with a single decimal place will be parsed as implicitly |
257 | having three places between subversions. |
258 | |
259 | The complicating factor is that in bare numbers (i.e. unquoted), the |
260 | underscore is a legal numeric character and is automatically stripped |
261 | by the Perl tokenizer before the version code is called. However, if |
262 | a number containing a single decimal and an underscore is quoted, i.e. |
263 | not bare, that is considered a L<Beta Version> and the underscore is |
264 | significant. |
a7ad731c |
265 | |
266 | If you use a mathematic formula that resolves to a floating point number, |
267 | you are dependent on Perl's conversion routines to yield the version you |
268 | expect. You are pretty safe by dividing by a power of 10, for example, |
269 | but other operations are not likely to be what you intend. For example: |
270 | |
271 | $VERSION = new version (qw$Revision: 1.4)[1]/10; |
272 | print $VERSION; # yields 0.14 |
273 | $V2 = new version 100/9; # Integer overflow in decimal number |
274 | print $V2; # yields 11_1285418553 |
275 | |
a7ad731c |
276 | Perl 5.9.0 and beyond will be able to automatically quote v-strings |
277 | (which may become the recommended notation), but that is not possible in |
278 | earlier versions of Perl. In other words: |
279 | |
280 | $version = new version "v2.5.4"; # legal in all versions of Perl |
281 | $newvers = new version v2.5.4; # legal only in Perl > 5.9.0 |
282 | |
283 | |
284 | =head2 Types of Versions Objects |
285 | |
129318bd |
286 | There are two types of Version Objects: |
287 | |
288 | =over 4 |
a7ad731c |
289 | |
290 | =item * Ordinary versions - These are the versions that normal |
291 | modules will use. Can contain as many subversions as required. |
292 | In particular, those using RCS/CVS can use one of the following: |
293 | |
129318bd |
294 | =back |
295 | |
296 | $VERSION = new version qw$Revision: 2.7 $; |
a7ad731c |
297 | |
298 | and the current RCS Revision for that file will be inserted |
299 | automatically. If the file has been moved to a branch, the |
300 | Revision will have three or more elements; otherwise, it will |
301 | have only two. This allows you to automatically increment |
302 | your module version by using the Revision number from the primary |
303 | file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">. |
304 | |
129318bd |
305 | =over 4 |
306 | |
a7ad731c |
307 | =item * Beta versions - For module authors using CPAN, the |
308 | convention has been to note unstable releases with an underscore |
309 | in the version string, see L<CPAN>. Beta releases will test as being |
310 | newer than the more recent stable release, and less than the next |
311 | stable release. For example: |
312 | |
129318bd |
313 | =back |
314 | |
a7ad731c |
315 | $betaver = new version "12.3_1"; # must quote |
316 | |
317 | obeys the relationship |
318 | |
319 | 12.3 < $betaver < 12.4 |
320 | |
321 | As a matter of fact, if is also true that |
322 | |
323 | 12.3.0 < $betaver < 12.3.1 |
324 | |
325 | where the subversion is identical but the beta release is less than |
326 | the non-beta release. |
327 | |
a7ad731c |
328 | =head2 Replacement UNIVERSAL::VERSION |
329 | |
330 | In addition to the version objects, this modules also replaces the core |
331 | UNIVERSAL::VERSION function with one that uses version objects for its |
129318bd |
332 | comparisons. |
a7ad731c |
333 | |
334 | =head1 EXPORT |
335 | |
336 | None by default. |
337 | |
338 | =head1 AUTHOR |
339 | |
340 | John Peacock E<lt>jpeacock@rowman.comE<gt> |
341 | |
342 | =head1 SEE ALSO |
343 | |
344 | L<perl>. |
345 | |
346 | =cut |