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 | |
12 | $VERSION = (qw$Revision: 2.1 $)[1]/10; |
13 | |
14 | $CLASS = 'version'; |
15 | |
16 | bootstrap version if $] < 5.009; |
17 | |
18 | # Preloaded methods go here. |
19 | |
20 | 1; |
21 | __END__ |
22 | |
23 | =head1 NAME |
24 | |
25 | version - Perl extension for Version Objects |
26 | |
27 | =head1 SYNOPSIS |
28 | |
29 | use version; |
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 |
34 | |
35 | $vstring = new version qw(v1.2); # must be quoted! |
36 | print $vstring; # 1.2 |
37 | |
38 | $betaver = new version "1.2_3"; # must be quoted! |
39 | print $betaver; # 1.2_3 |
40 | |
41 | $perlver = new version "5.005_03"; # must be quoted! |
42 | print $perlver; # 5.5.30 |
43 | |
44 | =head1 DESCRIPTION |
45 | |
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">. |
49 | |
50 | =head2 What IS a version |
51 | |
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. |
57 | |
58 | =head2 Object Methods |
59 | |
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: |
64 | |
65 | $ver = new version "1.2.3"; # see "Quoting" below |
66 | $beta = new version "1.2_3"; # see "Beta versions" below |
67 | |
68 | =item * Stringification - Any time a version object is used as a string, |
69 | a stringified representation is returned in reduced form (no extraneous |
70 | zeros): |
71 | |
72 | print $ver->stringify; # prints 1.2.3 |
73 | print $ver; # same thing |
74 | |
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: |
81 | |
82 | print $ver->numify; # prints 1.002003 |
83 | |
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: |
88 | |
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 |
97 | |
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: |
105 | |
106 | $ver == "1.2.3" or $ver = "v.1.2.3" # both true |
107 | |
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">. |
111 | |
112 | =head2 Quoting |
113 | |
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. |
119 | |
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: |
124 | |
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 |
129 | |
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 |
132 | error. For example: |
133 | |
134 | $VERSION = new version 10.2; # almost certainly ok |
135 | $VERSION = new version "10.2"; # guaranteed ok |
136 | |
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: |
140 | |
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 |
143 | |
144 | |
145 | =head2 Types of Versions Objects |
146 | |
147 | There are three basic types of Version Objects: |
148 | |
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: |
152 | |
153 | $VERSION = new version (qw$Revision: 2.1 $)[1]; # all Perls |
154 | $VERSION = new version qw$Revision: 2.1 $[1]; # Perl >= 5.6.0 |
155 | |
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">. |
162 | |
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. |
167 | |
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: |
173 | |
174 | $betaver = new version "12.3_1"; # must quote |
175 | |
176 | obeys the relationship |
177 | |
178 | 12.3 < $betaver < 12.4 |
179 | |
180 | As a matter of fact, if is also true that |
181 | |
182 | 12.3.0 < $betaver < 12.3.1 |
183 | |
184 | where the subversion is identical but the beta release is less than |
185 | the non-beta release. |
186 | |
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: |
193 | |
194 | $perlver = new version "5.005_03"; |
195 | |
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 |
201 | specifying. |
202 | |
203 | =head2 Replacement UNIVERSAL::VERSION |
204 | |
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: |
209 | |
210 | package vertest; |
211 | $VERSION = 0.45; |
212 | |
213 | package main; |
214 | use vertest 0.5; |
215 | |
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. |
219 | |
220 | =head1 EXPORT |
221 | |
222 | None by default. |
223 | |
224 | =head1 AUTHOR |
225 | |
226 | John Peacock E<lt>jpeacock@rowman.comE<gt> |
227 | |
228 | =head1 SEE ALSO |
229 | |
230 | L<perl>. |
231 | |
232 | =cut |
233 | #!/usr/local/bin/perl -w |
234 | package version; |
235 | |
236 | use 5.005_03; |
237 | use strict; |
238 | |
239 | require Exporter; |
240 | require DynaLoader; |
241 | use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK @EXPORT $VERSION $CLASS); |
242 | |
243 | @ISA = qw(Exporter DynaLoader); |
244 | |
245 | # This allows declaration use version ':all'; |
246 | # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK |
247 | # will save memory. |
248 | %EXPORT_TAGS = ( 'all' => [ qw( |
249 | |
250 | ) ] ); |
251 | |
252 | @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); |
253 | |
254 | @EXPORT = qw( |
255 | ); |
256 | |
257 | $VERSION = (qw$Revision: 1.8 $)[1]/10; |
258 | |
259 | $CLASS = 'version'; |
260 | |
261 | bootstrap version if $] < 5.009; |
262 | |
263 | # Preloaded methods go here. |
264 | |
265 | 1; |
266 | __END__ |
267 | |
268 | =head1 NAME |
269 | |
270 | version - Perl extension for Version Objects |
271 | |
272 | =head1 SYNOPSIS |
273 | |
274 | use version; |
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 |
279 | |
280 | $vstring = new version qw(v1.2); # must be quoted! |
281 | print $vstring; # 1.2 |
282 | |
283 | $betaver = new version "1.2_3"; # must be quoted! |
284 | print $betaver; # 1.2_3 |
285 | |
286 | $perlver = new version "5.005_03"; # must be quoted! |
287 | print $perlver; # 5.5.30 |
288 | |
289 | =head1 DESCRIPTION |
290 | |
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">. |
294 | |
295 | =head2 What IS a version |
296 | |
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. |
302 | |
303 | =head2 Object Methods |
304 | |
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: |
309 | |
310 | $ver = new version "1.2.3"; # see "Quoting" below |
311 | $beta = new version "1.2_3"; # see "Beta versions" below |
312 | |
313 | =item * Stringification - Any time a version object is used as a string, |
314 | a stringified representation is returned in reduced form (no extraneous |
315 | zeros): |
316 | |
317 | print $ver->stringify; # prints 1.2.3 |
318 | print $ver; # same thing |
319 | |
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: |
326 | |
327 | print $ver->numify; # prints 1.002003 |
328 | |
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: |
333 | |
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 |
342 | |
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: |
350 | |
351 | $ver == "1.2.3" or $ver = "v.1.2.3" # both true |
352 | |
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">. |
356 | |
357 | =head2 Quoting |
358 | |
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. |
364 | |
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: |
369 | |
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 |
374 | |
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 |
377 | error. For example: |
378 | |
379 | $VERSION = new version 10.2; # almost certainly ok |
380 | $VERSION = new version "10.2"; # guaranteed ok |
381 | |
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: |
385 | |
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 |
388 | |
389 | |
390 | =head2 Types of Versions Objects |
391 | |
392 | There are three basic types of Version Objects: |
393 | |
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: |
397 | |
398 | $VERSION = new version (qw$Revision: 1.8 $)[1]; # all Perls |
399 | $VERSION = new version qw$Revision: 1.8 $[1]; # Perl >= 5.6.0 |
400 | |
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">. |
407 | |
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: |
413 | |
414 | $betaver = new version "12.3_1"; # must quote |
415 | |
416 | obeys the relationship |
417 | |
418 | 12.3 < $betaver < 12.4 |
419 | |
420 | As a matter of fact, if is also true that |
421 | |
422 | 12.3.0 < $betaver < 12.3.1 |
423 | |
424 | where the subversion is identical but the beta release is less than |
425 | the non-beta release. |
426 | |
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: |
433 | |
434 | $perlver = new version "5.005_03"; |
435 | |
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 |
441 | specifying. |
442 | |
443 | =head2 Replacement UNIVERSAL::VERSION |
444 | |
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: |
449 | |
450 | package vertest; |
451 | $VERSION = 0.45; |
452 | |
453 | package main; |
454 | use vertest 0.5; |
455 | |
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. |
459 | |
460 | =head1 EXPORT |
461 | |
462 | None by default. |
463 | |
464 | =head1 AUTHOR |
465 | |
466 | John Peacock E<lt>jpeacock@rowman.comE<gt> |
467 | |
468 | =head1 SEE ALSO |
469 | |
470 | L<perl>. |
471 | |
472 | =cut |