Commit | Line | Data |
c8d69e4a |
1 | #!perl -w |
a7ad731c |
2 | package version; |
3 | |
4 | use 5.005_03; |
5 | use strict; |
6 | |
137d6fc0 |
7 | require Exporter; |
a7ad731c |
8 | require DynaLoader; |
137d6fc0 |
9 | use vars qw(@ISA $VERSION $CLASS @EXPORT); |
a7ad731c |
10 | |
137d6fc0 |
11 | @ISA = qw(Exporter DynaLoader); |
a7ad731c |
12 | |
137d6fc0 |
13 | @EXPORT = qw(qv); |
14 | |
15 | $VERSION = 0.36; # stop using CVS and switch to subversion |
a7ad731c |
16 | |
17 | $CLASS = 'version'; |
18 | |
26ec6fc3 |
19 | local $^W; # shut up the 'redefined' warning for UNIVERSAL::VERSION |
a7ad731c |
20 | bootstrap version if $] < 5.009; |
21 | |
22 | # Preloaded methods go here. |
23 | |
24 | 1; |
25 | __END__ |
26 | |
27 | =head1 NAME |
28 | |
29 | version - Perl extension for Version Objects |
30 | |
31 | =head1 SYNOPSIS |
32 | |
33 | use version; |
34 | $version = new version "12.2.1"; # must be quoted! |
35 | print $version; # 12.2.1 |
36 | print $version->numify; # 12.002001 |
137d6fc0 |
37 | if ( $version gt "12.2" ) # true |
a7ad731c |
38 | |
137d6fc0 |
39 | $vstring = new version qw(1.2); # must be quoted! |
a7ad731c |
40 | print $vstring; # 1.2 |
41 | |
c8d69e4a |
42 | $alphaver = new version "1.2_3"; # must be quoted! |
43 | print $alphaver; # 1.2_3 |
44 | print $alphaver->is_alpha(); # true |
137d6fc0 |
45 | |
46 | $ver = qv(1.2); # 1.2.0 |
47 | $ver = qv("1.2"); # 1.2.0 |
a7ad731c |
48 | |
129318bd |
49 | $perlver = new version 5.005_03; # must not be quoted! |
a7ad731c |
50 | print $perlver; # 5.5.30 |
51 | |
52 | =head1 DESCRIPTION |
53 | |
54 | Overloaded version objects for all versions of Perl. This module |
26ec6fc3 |
55 | implements all of the features of version objects which will be part |
137d6fc0 |
56 | of Perl 5.10.0 except automatic version object creation. |
a7ad731c |
57 | |
58 | =head2 What IS a version |
59 | |
60 | For the purposes of this module, a version "number" is a sequence of |
61 | positive integral values separated by decimal points and optionally a |
62 | single underscore. This corresponds to what Perl itself uses for a |
63 | version, as well as extending the "version as number" that is discussed |
64 | in the various editions of the Camel book. |
65 | |
129318bd |
66 | There are actually two distinct ways to initialize versions: |
67 | |
68 | =over 4 |
69 | |
c8d69e4a |
70 | =item * Numeric Versions |
129318bd |
71 | |
c8d69e4a |
72 | Any initial parameter which "looks like a number", see L<Numeric |
73 | Versions>. |
74 | |
137d6fc0 |
75 | =item * Quoted Versions |
c8d69e4a |
76 | |
137d6fc0 |
77 | Any initial parameter which contains more than one decimal point |
78 | or contains an embedded underscore, see L<Quoted Versions>. The |
79 | most recent development version of Perl (5.9.x) and the next major |
80 | release (5.10.0) will automatically create version objects for bare |
81 | numbers containing more than one decimal point. |
129318bd |
82 | |
83 | =back |
84 | |
85 | Both of these methods will produce similar version objects, in that |
86 | the default stringification will always be in a reduced form, i.e.: |
87 | |
88 | $v = new version 1.002003; # 1.2.3 |
89 | $v2 = new version "1.2.3"; # 1.2.3 |
137d6fc0 |
90 | $v3 = new version 1.2.3; # 1.2.3 for Perl > 5.8.0 |
129318bd |
91 | |
137d6fc0 |
92 | Note that the default stringification will display at least three sub |
93 | terms (to ensure that appropriate round-trip processing is possible). |
c8d69e4a |
94 | Please see L<"Quoting"> for more details on how Perl will parse various |
129318bd |
95 | input values. |
46314c13 |
96 | |
97 | Any value passed to the new() operator will be parsed only so far as it |
98 | contains a numeric, decimal, or underscore character. So, for example: |
99 | |
100 | $v1 = new version "99 and 94/100 percent pure"; # $v1 == 99.0 |
101 | $v2 = new version "something"; # $v2 == "" and $v2->numify == 0 |
102 | |
129318bd |
103 | However, see L<New Operator> for one case where non-numeric text is |
104 | acceptable when initializing version objects. |
105 | |
137d6fc0 |
106 | =head2 What about v-strings? |
107 | |
108 | Beginning with Perl 5.6.0, an alternate method to code arbitrary strings |
109 | of bytes was introduced, called v-strings. They were intended to be an |
110 | easy way to enter, for example, Unicode strings (which contain two bytes |
111 | per character). Some programs have used them to encode printer control |
112 | characters (e.g. CRLF). They were also intended to be used for $VERSION. |
113 | Their use has been problematic from the start and they will be phased out |
114 | beginning in Perl 5.10.0. |
115 | |
116 | There are two ways to enter v-strings: a bare number with two or more |
117 | decimal places, or a bare number with one or more decimal places and a |
118 | leading 'v' character (also bare). For example: |
119 | |
120 | $vs1 = 1.2.3; # encoded as \1\2\3 |
121 | $vs2 = v1.2; # encoded as \1\2 |
122 | |
123 | The first of those two syntaxes is destined to be the default way to create |
124 | a version object in 5.10.0, whereas the second will issue a mandatory |
125 | deprecation warning beginning at the same time. |
126 | |
127 | Consequently, the use of v-strings to initialize version objects with |
128 | this module is only possible with Perl 5.8.1 (which will contain special |
129 | code to enable it). Their use is B<strongly> discouraged in all |
130 | circumstances(especially the leading 'v' style), since the meaning will |
131 | change depending on which Perl you are running. It is better to use |
132 | L<"Quoted Versions"> to ensure the proper interpretation. |
133 | |
129318bd |
134 | =head2 Numeric Versions |
135 | |
137d6fc0 |
136 | These correspond to historical versions of Perl itself prior to 5.6.0, |
129318bd |
137 | as well as all other modules which follow the Camel rules for the |
138 | $VERSION scalar. A numeric version is initialized with what looks like |
139 | a floating point number. Leading zeros B<are> significant and trailing |
140 | zeros are implied so that a minimum of three places is maintained |
141 | between subversions. What this means is that any subversion (digits |
142 | to the right of the decimal place) that contains less than three digits |
143 | will have trailing zeros added to make up the difference. For example: |
144 | |
145 | $v = new version 1.2; # 1.200 |
146 | $v = new version 1.02; # 1.20 |
147 | $v = new version 1.002; # 1.2 |
148 | $v = new version 1.0023; # 1.2.300 |
149 | $v = new version 1.00203; # 1.2.30 |
137d6fc0 |
150 | $v = new version 1.002_03; # 1.2.30 See "Quoting" |
129318bd |
151 | $v = new version 1.002003; # 1.2.3 |
152 | |
c8d69e4a |
153 | All of the preceeding examples except the second to last are true |
129318bd |
154 | whether or not the input value is quoted. The important feature is that |
155 | the input value contains only a single decimal. |
156 | |
137d6fc0 |
157 | =head2 Quoted Versions |
129318bd |
158 | |
159 | These are the newest form of versions, and correspond to Perl's own |
137d6fc0 |
160 | version style beginning with 5.6.0. Starting with Perl 5.10.0, |
161 | and most likely Perl 6, this is likely to be the preferred form. This |
162 | method requires that the input parameter be quoted, although Perl's after |
163 | 5.9.0 can use bare numbers with multiple decimal places as a special form |
164 | of quoting. |
165 | |
166 | Unlike L<Numeric Versions>, Quoted Versions may have more than |
167 | a single decimal point, e.g. "5.6.1" but must be quoted like this "5.6" in |
168 | order to prevent the Numeric Version interpretation. Also unlike |
169 | L<Numeric Versions>, leading zeros are B<not> significant, and trailing |
170 | zeros must be explicitely specified (i.e. will not be automatically added). |
171 | In addition, the subversions are not enforced to be three decimal places. |
129318bd |
172 | |
173 | So, for example: |
174 | |
137d6fc0 |
175 | $v = new version "1.002"; # 1.2 |
129318bd |
176 | $v = new version "1.2.3"; # 1.2.3 |
137d6fc0 |
177 | $v = new version "1.2.3"; # 1.2.3 |
178 | $v = new version "1.0003"; # 1.3 |
129318bd |
179 | |
137d6fc0 |
180 | In addition to conventional versions, Quoted Versions can be |
c8d69e4a |
181 | used to create L<Alpha Versions>. |
129318bd |
182 | |
137d6fc0 |
183 | In general, Quoted Versions permit the greatest amount of freedom |
c8d69e4a |
184 | to specify a version, whereas Numeric Versions enforce a certain |
129318bd |
185 | uniformity. See also L<New Operator> for an additional method of |
186 | initializing version objects. |
46314c13 |
187 | |
a7ad731c |
188 | =head2 Object Methods |
189 | |
190 | Overloading has been used with version objects to provide a natural |
191 | interface for their use. All mathematical operations are forbidden, |
c8d69e4a |
192 | since they don't make any sense for base version objects. |
129318bd |
193 | |
194 | =over 4 |
195 | |
c8d69e4a |
196 | =item * New Operator |
197 | |
198 | Like all OO interfaces, the new() operator is used to initialize |
199 | version objects. One way to increment versions when programming is to |
200 | use the CVS variable $Revision, which is automatically incremented by |
201 | CVS every time the file is committed to the repository. |
129318bd |
202 | |
129318bd |
203 | In order to facilitate this feature, the following |
204 | code can be employed: |
205 | |
206 | $VERSION = new version qw$Revision: 2.7 $; |
207 | |
208 | and the version object will be created as if the following code |
209 | were used: |
210 | |
137d6fc0 |
211 | $VERSION = new version "2.7"; |
129318bd |
212 | |
213 | In other words, the version will be automatically parsed out of the |
214 | string, and it will be quoted to preserve the meaning CVS normally |
215 | carries for versions. |
216 | |
137d6fc0 |
217 | =back |
218 | |
219 | =over 4 |
220 | |
221 | =item * qv() |
222 | |
223 | An alternate way to create a new version object is through the exported |
224 | qv() sub. This is not strictly like other q? operators (like qq, qw), |
225 | in that the only delimiters supported are parentheses (or spaces). It is |
226 | the best way to initialize a short version without triggering the floating |
227 | point interpretation. For example: |
228 | |
229 | $v1 = qv(1.2); # 1.2.0 |
230 | $v2 = qv("1.2"); # also 1.2.0 |
231 | |
232 | As you can see, either a bare number or a quoted string can be used, and |
233 | either will yield the same version number. |
234 | |
235 | =back |
236 | |
129318bd |
237 | For the subsequent examples, the following two objects will be used: |
a7ad731c |
238 | |
239 | $ver = new version "1.2.3"; # see "Quoting" below |
c8d69e4a |
240 | $alpha = new version "1.2_3"; # see "Alpha versions" below |
a7ad731c |
241 | |
129318bd |
242 | =over 4 |
243 | |
c8d69e4a |
244 | =item * Stringification |
245 | |
246 | Any time a version object is used as a string, a stringified |
247 | representation is returned in reduced form (no extraneous zeros): |
a7ad731c |
248 | |
249 | print $ver->stringify; # prints 1.2.3 |
250 | print $ver; # same thing |
251 | |
137d6fc0 |
252 | In order to preserve the meaning of the processed version, the |
253 | default stringified representation will always contain at least |
254 | three sub terms. In other words, the following is guaranteed to |
255 | always be true: |
256 | |
257 | my $newver = version->new($ver->stringify); |
258 | if ($newver eq $ver ) # always true |
259 | {...} |
260 | |
261 | If the string representation "looked like a number" then there is |
262 | a possibility that creating a new version object from that would use |
263 | the Numeric Version interpretation, If a version object contains only |
264 | two terms internally, it will stringify with an explicit '.0' appended. |
265 | |
266 | =back |
267 | |
129318bd |
268 | =over 4 |
269 | |
c8d69e4a |
270 | =item * Numification |
a7ad731c |
271 | |
c8d69e4a |
272 | Although all mathematical operations on version objects are forbidden |
273 | by default, it is possible to retrieve a number which roughly |
274 | corresponds to the version object through the use of the $obj->numify |
275 | method. For formatting purposes, when displaying a number which |
276 | corresponds a version object, all sub versions are assumed to have |
277 | three decimal places. So for example: |
129318bd |
278 | |
a7ad731c |
279 | print $ver->numify; # prints 1.002003 |
280 | |
137d6fc0 |
281 | Unlike the stringification operator, there is never any need to append |
282 | trailing zeros to preserve the correct version value. |
283 | |
284 | =back |
285 | |
286 | =over 4 |
287 | |
c8d69e4a |
288 | =item * Comparison operators |
129318bd |
289 | |
c8d69e4a |
290 | Both cmp and <=> operators perform the same comparison between terms |
291 | (upgrading to a version object automatically). Perl automatically |
292 | generates all of the other comparison operators based on those two. |
293 | In addition to the obvious equalities listed below, appending a single |
294 | trailing 0 term does not change the value of a version for comparison |
137d6fc0 |
295 | purposes. In other words "v1.2" and "1.2.0" will compare as identical. |
129318bd |
296 | |
297 | For example, the following relations hold: |
a7ad731c |
298 | |
129318bd |
299 | As Number As String Truth Value |
300 | --------- ------------ ----------- |
a7ad731c |
301 | $ver > 1.0 $ver gt "1.0" true |
302 | $ver < 2.5 $ver lt true |
303 | $ver != 1.3 $ver ne "1.3" true |
304 | $ver == 1.2 $ver eq "1.2" false |
305 | $ver == 1.2.3 $ver eq "1.2.3" see discussion below |
a7ad731c |
306 | |
137d6fc0 |
307 | It is probably best to chose either the numeric notation or the string |
308 | notation and stick with it, to reduce confusion. Perl6 version objects |
309 | B<may> only support numeric comparisons. See also L<"Quoting">. |
a7ad731c |
310 | |
137d6fc0 |
311 | =back |
a7ad731c |
312 | |
137d6fc0 |
313 | =over 4 |
a7ad731c |
314 | |
c8d69e4a |
315 | =item * Logical Operators |
316 | |
317 | If you need to test whether a version object |
318 | has been initialized, you can simply test it directly: |
319 | |
320 | $vobj = new version $something; |
321 | if ( $vobj ) # true only if $something was non-blank |
322 | |
137d6fc0 |
323 | You can also test whether a version object is an L<Alpha version>, for |
c8d69e4a |
324 | example to prevent the use of some feature not present in the main |
325 | release: |
326 | |
327 | $vobj = new version "1.2_3"; # MUST QUOTE |
328 | ...later... |
329 | if ( $vobj->is_alpha ) # True |
330 | |
331 | =back |
332 | |
a7ad731c |
333 | =head2 Quoting |
334 | |
c8d69e4a |
335 | Because of the nature of the Perl parsing and tokenizing routines, |
129318bd |
336 | certain initialization values B<must> be quoted in order to correctly |
337 | parse as the intended version, and additionally, some initial values |
338 | B<must not> be quoted to obtain the intended version. |
339 | |
c8d69e4a |
340 | Except for L<Alpha versions>, any version initialized with something |
129318bd |
341 | that looks like a number (a single decimal place) will be parsed in |
342 | the same way whether or not the term is quoted. In order to be |
343 | compatible with earlier Perl version styles, any use of versions of |
344 | the form 5.006001 will be translated as 5.6.1. In other words, a |
345 | version with a single decimal place will be parsed as implicitly |
346 | having three places between subversions. |
347 | |
348 | The complicating factor is that in bare numbers (i.e. unquoted), the |
349 | underscore is a legal numeric character and is automatically stripped |
350 | by the Perl tokenizer before the version code is called. However, if |
351 | a number containing a single decimal and an underscore is quoted, i.e. |
c8d69e4a |
352 | not bare, that is considered a L<Alpha Version> and the underscore is |
129318bd |
353 | significant. |
a7ad731c |
354 | |
355 | If you use a mathematic formula that resolves to a floating point number, |
356 | you are dependent on Perl's conversion routines to yield the version you |
357 | expect. You are pretty safe by dividing by a power of 10, for example, |
358 | but other operations are not likely to be what you intend. For example: |
359 | |
360 | $VERSION = new version (qw$Revision: 1.4)[1]/10; |
361 | print $VERSION; # yields 0.14 |
362 | $V2 = new version 100/9; # Integer overflow in decimal number |
363 | print $V2; # yields 11_1285418553 |
364 | |
137d6fc0 |
365 | Perl 5.8.1 and beyond will be able to automatically quote v-strings |
366 | (although a warning will be issued under 5.9.x and 5.10.0), but that |
367 | is not possible in earlier versions of Perl. In other words: |
a7ad731c |
368 | |
369 | $version = new version "v2.5.4"; # legal in all versions of Perl |
137d6fc0 |
370 | $newvers = new version v2.5.4; # legal only in Perl > 5.8.1 |
a7ad731c |
371 | |
372 | |
373 | =head2 Types of Versions Objects |
374 | |
129318bd |
375 | There are two types of Version Objects: |
376 | |
377 | =over 4 |
a7ad731c |
378 | |
c8d69e4a |
379 | =item * Ordinary versions |
a7ad731c |
380 | |
c8d69e4a |
381 | These are the versions that normal modules will use. Can contain as |
382 | many subversions as required. In particular, those using RCS/CVS can |
383 | use one of the following: |
129318bd |
384 | |
c8d69e4a |
385 | $VERSION = new version qw$Revision: 2.7 $; |
a7ad731c |
386 | |
c8d69e4a |
387 | and the current RCS Revision for that file will be inserted |
388 | automatically. If the file has been moved to a branch, the Revision |
389 | will have three or more elements; otherwise, it will have only two. |
390 | This allows you to automatically increment your module version by |
391 | using the Revision number from the primary file in a distribution, see |
392 | L<ExtUtils::MakeMaker/"VERSION_FROM">. |
a7ad731c |
393 | |
137d6fc0 |
394 | =item * Alpha versions |
129318bd |
395 | |
c8d69e4a |
396 | For module authors using CPAN, the convention has been to note |
397 | unstable releases with an underscore in the version string, see |
398 | L<CPAN>. Alpha releases will test as being newer than the more recent |
399 | stable release, and less than the next stable release. For example: |
129318bd |
400 | |
c8d69e4a |
401 | $alphaver = new version "12.3_1"; # must quote |
a7ad731c |
402 | |
403 | obeys the relationship |
404 | |
c8d69e4a |
405 | 12.3 < $alphaver < 12.4 |
a7ad731c |
406 | |
407 | As a matter of fact, if is also true that |
408 | |
c8d69e4a |
409 | 12.3.0 < $alphaver < 12.3.1 |
a7ad731c |
410 | |
c8d69e4a |
411 | where the subversion is identical but the alpha release is less than |
412 | the non-alpha release. |
a7ad731c |
413 | |
a7ad731c |
414 | =head2 Replacement UNIVERSAL::VERSION |
415 | |
416 | In addition to the version objects, this modules also replaces the core |
417 | UNIVERSAL::VERSION function with one that uses version objects for its |
129318bd |
418 | comparisons. |
a7ad731c |
419 | |
420 | =head1 EXPORT |
421 | |
137d6fc0 |
422 | qv - quoted version initialization operator |
a7ad731c |
423 | |
424 | =head1 AUTHOR |
425 | |
426 | John Peacock E<lt>jpeacock@rowman.comE<gt> |
427 | |
428 | =head1 SEE ALSO |
429 | |
430 | L<perl>. |
431 | |
432 | =cut |