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