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