Commit | Line | Data |
---|---|---|
692a467c JP |
1 | =head1 NAME |
2 | ||
6369c739 | 3 | version::Internals - Perl extension for Version Objects |
692a467c JP |
4 | |
5 | =head1 DESCRIPTION | |
6 | ||
7 | Overloaded version objects for all modern versions of Perl. This documents | |
8 | the internal data representation and underlying code for version.pm. See | |
fe6e8b3e | 9 | F<version.pod> for daily usage. This document is only useful for users |
6369c739 | 10 | interested in the gory details. |
692a467c | 11 | |
6369c739 | 12 | =head1 WHAT IS A VERSION? |
692a467c JP |
13 | |
14 | For the purposes of this module, a version "number" is a sequence of | |
6369c739 DG |
15 | positive integer values separated by one or more decimal points and |
16 | optionally a single underscore. This corresponds to what Perl itself | |
17 | uses for a version, as well as extending the "version as number" that | |
692a467c JP |
18 | is discussed in the various editions of the Camel book. |
19 | ||
20 | There are actually two distinct kinds of version objects: | |
21 | ||
22 | =over 4 | |
23 | ||
345e2394 | 24 | =item Decimal Versions |
692a467c JP |
25 | |
26 | Any version which "looks like a number", see L<Decimal Versions>. This | |
27 | also includes versions with a single decimal point and a single embedded | |
6369c739 | 28 | underscore, see L<Alpha Versions>, even though these must be quoted |
692a467c JP |
29 | to preserve the underscore formatting. |
30 | ||
345e2394 | 31 | =item Dotted-Decimal Versions |
692a467c JP |
32 | |
33 | Also referred to as "Dotted-Integer", these contains more than one decimal | |
34 | point and may have an optional embedded underscore, see L<Dotted-Decimal | |
35 | Versions>. This is what is commonly used in most open source software as | |
36 | the "external" version (the one used as part of the tag or tarfile name). | |
37 | A leading 'v' character is now required and will warn if it missing. | |
38 | ||
39 | =back | |
40 | ||
41 | Both of these methods will produce similar version objects, in that | |
6369c739 | 42 | the default stringification will yield the version L<Normal Form> only |
692a467c JP |
43 | if required: |
44 | ||
45 | $v = version->new(1.002); # 1.002, but compares like 1.2.0 | |
46 | $v = version->new(1.002003); # 1.002003 | |
47 | $v2 = version->new("v1.2.3"); # v1.2.3 | |
48 | ||
49 | In specific, version numbers initialized as L<Decimal Versions> will | |
50 | stringify as they were originally created (i.e. the same string that was | |
51 | passed to C<new()>. Version numbers initialized as L<Dotted-Decimal Versions> | |
52 | will be stringified as L<Normal Form>. | |
53 | ||
54 | =head2 Decimal Versions | |
55 | ||
56 | These correspond to historical versions of Perl itself prior to 5.6.0, | |
57 | as well as all other modules which follow the Camel rules for the | |
58 | $VERSION scalar. A Decimal version is initialized with what looks like | |
59 | a floating point number. Leading zeros B<are> significant and trailing | |
60 | zeros are implied so that a minimum of three places is maintained | |
61 | between subversions. What this means is that any subversion (digits | |
62 | to the right of the decimal place) that contains less than three digits | |
63 | will have trailing zeros added to make up the difference, but only for | |
64 | purposes of comparison with other version objects. For example: | |
65 | ||
6369c739 | 66 | # Prints Equivalent to |
692a467c JP |
67 | $v = version->new( 1.2); # 1.2 v1.200.0 |
68 | $v = version->new( 1.02); # 1.02 v1.20.0 | |
69 | $v = version->new( 1.002); # 1.002 v1.2.0 | |
70 | $v = version->new( 1.0023); # 1.0023 v1.2.300 | |
71 | $v = version->new( 1.00203); # 1.00203 v1.2.30 | |
72 | $v = version->new( 1.002003); # 1.002003 v1.2.3 | |
73 | ||
6369c739 DG |
74 | All of the preceding examples are true whether or not the input value is |
75 | quoted. The important feature is that the input value contains only a | |
76 | single decimal. See also L<Alpha Versions>. | |
692a467c | 77 | |
6369c739 DG |
78 | IMPORTANT NOTE: As shown above, if your Decimal version contains more |
79 | than 3 significant digits after the decimal place, it will be split on | |
80 | each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need | |
81 | to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation. | |
692a467c JP |
82 | Any trailing zeros are ignored for mathematical comparison purposes. |
83 | ||
84 | =head2 Dotted-Decimal Versions | |
85 | ||
86 | These are the newest form of versions, and correspond to Perl's own | |
87 | version style beginning with 5.6.0. Starting with Perl 5.10.0, | |
88 | and most likely Perl 6, this is likely to be the preferred form. This | |
6369c739 | 89 | method normally requires that the input parameter be quoted, although |
692a467c JP |
90 | Perl's after 5.8.1 can use v-strings as a special form of quoting, but |
91 | this is highly discouraged. | |
92 | ||
93 | Unlike L<Decimal Versions>, Dotted-Decimal Versions have more than | |
94 | a single decimal point, e.g.: | |
95 | ||
96 | # Prints | |
97 | $v = version->new( "v1.200"); # v1.200.0 | |
98 | $v = version->new("v1.20.0"); # v1.20.0 | |
99 | $v = qv("v1.2.3"); # v1.2.3 | |
100 | $v = qv("1.2.3"); # v1.2.3 | |
101 | $v = qv("1.20"); # v1.20.0 | |
102 | ||
103 | In general, Dotted-Decimal Versions permit the greatest amount of freedom | |
104 | to specify a version, whereas Decimal Versions enforce a certain | |
dc08a87b | 105 | uniformity. |
692a467c | 106 | |
1adc55b9 KW |
107 | Just like L</Decimal Versions>, Dotted-Decimal Versions can be used as |
108 | L</Alpha Versions>. | |
692a467c | 109 | |
6369c739 | 110 | =head2 Alpha Versions |
692a467c | 111 | |
6369c739 DG |
112 | For module authors using CPAN, the convention has been to note unstable |
113 | releases with an underscore in the version string. (See L<CPAN>.) version.pm | |
114 | follows this convention and alpha releases will test as being newer than the | |
115 | more recent stable release, and less than the next stable release. Only the | |
116 | last element may be separated by an underscore: | |
692a467c | 117 | |
6369c739 DG |
118 | # Declaring |
119 | use version 0.77; our $VERSION = version->declare("v1.2_3"); | |
692a467c | 120 | |
6369c739 DG |
121 | # Parsing |
122 | $v1 = version->parse("v1.2_3"); | |
123 | $v1 = version->parse("1.002_003"); | |
124 | ||
125 | Note that you B<must> quote the version when writing an alpha Decimal version. | |
126 | The stringified form of Decimal versions will always be the same string that | |
127 | was used to initialize the version object. | |
692a467c | 128 | |
42bd538f JP |
129 | =head2 Regular Expressions for Version Parsing |
130 | ||
131 | A formalized definition of the legal forms for version strings is | |
132 | included in the main F<version.pm> file. Primitives are included for | |
133 | common elements, although they are scoped to the file so they are useful | |
134 | for reference purposes only. There are two publicly accessible scalars | |
135 | that can be used in other code (not exported): | |
136 | ||
137 | =over 4 | |
138 | ||
139 | =item C<$version::LAX> | |
140 | ||
141 | This regexp covers all of the legal forms allowed under the current | |
142 | version string parser. This is not to say that all of these forms | |
143 | are recommended, and some of them can only be used when quoted. | |
144 | ||
145 | For dotted decimals: | |
146 | ||
147 | v1.2 | |
148 | 1.2345.6 | |
149 | v1.23_4 | |
150 | ||
151 | The leading 'v' is optional if two or more decimals appear. If only | |
152 | a single decimal is included, then the leading 'v' is required to | |
153 | trigger the dotted-decimal parsing. A leading zero is permitted, | |
154 | though not recommended except when quoted, because of the risk that | |
155 | Perl will treat the number as octal. A trailing underscore plus one | |
156 | or more digits denotes an alpha or development release (and must be | |
157 | quoted to be parsed properly). | |
158 | ||
159 | For decimal versions: | |
160 | ||
161 | 1 | |
162 | 1.2345 | |
163 | 1.2345_01 | |
164 | ||
165 | an integer portion, an optional decimal point, and optionally one or | |
166 | more digits to the right of the decimal are all required. A trailing | |
167 | underscore is permitted and a leading zero is permitted. Just like | |
168 | the lax dotted-decimal version, quoting the values is required for | |
169 | alpha/development forms to be parsed correctly. | |
170 | ||
171 | =item C<$version::STRICT> | |
172 | ||
173 | This regexp covers a much more limited set of formats and constitutes | |
174 | the best practices for initializing version objects. Whether you choose | |
175 | to employ decimal or dotted-decimal for is a personal preference however. | |
176 | ||
177 | =over 4 | |
178 | ||
179 | =item v1.234.5 | |
180 | ||
181 | For dotted-decimal versions, a leading 'v' is required, with three or | |
182 | more sub-versions of no more than three digits. A leading 0 (zero) | |
183 | before the first sub-version (in the above example, '1') is also | |
184 | prohibited. | |
185 | ||
186 | =item 2.3456 | |
187 | ||
188 | For decimal versions, an integer portion (no leading 0), a decimal point, | |
189 | and one or more digits to the right of the decimal are all required. | |
190 | ||
191 | =back | |
192 | ||
193 | =back | |
194 | ||
195 | Both of the provided scalars are already compiled as regular expressions | |
196 | and do not contain either anchors or implicit groupings, so they can be | |
197 | included in your own regular expressions freely. For example, consider | |
198 | the following code: | |
199 | ||
200 | ($pkg, $ver) =~ / | |
201 | ^[ \t]* | |
202 | use [ \t]+($PKGNAME) | |
203 | (?:[ \t]+($version::STRICT))? | |
204 | [ \t]*; | |
205 | /x; | |
206 | ||
207 | This would match a line of the form: | |
208 | ||
209 | use Foo::Bar::Baz v1.2.3; # legal only in Perl 5.8.1+ | |
210 | ||
211 | where C<$PKGNAME> is another regular expression that defines the legal | |
212 | forms for package names. | |
213 | ||
6369c739 DG |
214 | =head1 IMPLEMENTATION DETAILS |
215 | ||
216 | =head2 Equivalence between Decimal and Dotted-Decimal Versions | |
217 | ||
218 | When Perl 5.6.0 was released, the decision was made to provide a | |
219 | transformation between the old-style decimal versions and new-style | |
220 | dotted-decimal versions: | |
221 | ||
222 | 5.6.0 == 5.006000 | |
223 | 5.005_04 == 5.5.40 | |
224 | ||
225 | The floating point number is taken and split first on the single decimal | |
226 | place, then each group of three digits to the right of the decimal makes up | |
227 | the next digit, and so on until the number of significant digits is exhausted, | |
228 | B<plus> enough trailing zeros to reach the next multiple of three. | |
229 | ||
230 | This was the method that version.pm adopted as well. Some examples may be | |
231 | helpful: | |
232 | ||
233 | equivalent | |
234 | decimal zero-padded dotted-decimal | |
235 | ------- ----------- -------------- | |
236 | 1.2 1.200 v1.200.0 | |
237 | 1.02 1.020 v1.20.0 | |
238 | 1.002 1.002 v1.2.0 | |
239 | 1.0023 1.002300 v1.2.300 | |
240 | 1.00203 1.002030 v1.2.30 | |
241 | 1.002003 1.002003 v1.2.3 | |
242 | ||
243 | =head2 Quoting Rules | |
244 | ||
245 | Because of the nature of the Perl parsing and tokenizing routines, | |
246 | certain initialization values B<must> be quoted in order to correctly | |
fe6e8b3e | 247 | parse as the intended version, especially when using the C<declare> or |
c5009e80 | 248 | L</qv()> methods. While you do not have to quote decimal numbers when |
6369c739 DG |
249 | creating version objects, it is always safe to quote B<all> initial values |
250 | when using version.pm methods, as this will ensure that what you type is | |
251 | what is used. | |
252 | ||
253 | Additionally, if you quote your initializer, then the quoted value that goes | |
254 | B<in> will be be exactly what comes B<out> when your $VERSION is printed | |
255 | (stringified). If you do not quote your value, Perl's normal numeric handling | |
256 | comes into play and you may not get back what you were expecting. | |
257 | ||
258 | If you use a mathematic formula that resolves to a floating point number, | |
259 | you are dependent on Perl's conversion routines to yield the version you | |
260 | expect. You are pretty safe by dividing by a power of 10, for example, | |
261 | but other operations are not likely to be what you intend. For example: | |
262 | ||
263 | $VERSION = version->new((qw$Revision: 1.4)[1]/10); | |
264 | print $VERSION; # yields 0.14 | |
265 | $V2 = version->new(100/9); # Integer overflow in decimal number | |
266 | print $V2; # yields something like 11.111.111.100 | |
267 | ||
268 | Perl 5.8.1 and beyond are able to automatically quote v-strings but | |
269 | that is not possible in earlier versions of Perl. In other words: | |
270 | ||
271 | $version = version->new("v2.5.4"); # legal in all versions of Perl | |
272 | $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1 | |
273 | ||
274 | =head2 What about v-strings? | |
275 | ||
276 | There are two ways to enter v-strings: a bare number with two or more | |
277 | decimal points, or a bare number with one or more decimal points and a | |
278 | leading 'v' character (also bare). For example: | |
279 | ||
280 | $vs1 = 1.2.3; # encoded as \1\2\3 | |
281 | $vs2 = v1.2; # encoded as \1\2 | |
282 | ||
283 | However, the use of bare v-strings to initialize version objects is | |
284 | B<strongly> discouraged in all circumstances. Also, bare | |
285 | v-strings are not completely supported in any version of Perl prior to | |
286 | 5.8.1. | |
692a467c | 287 | |
6369c739 DG |
288 | If you insist on using bare v-strings with Perl > 5.6.0, be aware of the |
289 | following limitations: | |
692a467c | 290 | |
6369c739 DG |
291 | 1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses, |
292 | based on some characteristics of v-strings. You B<must> use a three part | |
293 | version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful. | |
294 | ||
295 | 2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl | |
296 | core to be magical, which means that the version.pm code can automatically | |
297 | determine whether the v-string encoding was used. | |
298 | ||
299 | 3) In all cases, a version created using v-strings will have a stringified | |
300 | form that has a leading 'v' character, for the simple reason that sometimes | |
301 | it is impossible to tell whether one was present initially. | |
302 | ||
303 | =head2 Version Object Internals | |
304 | ||
305 | version.pm provides an overloaded version object that is designed to both | |
692a467c JP |
306 | encapsulate the author's intended $VERSION assignment as well as make it |
307 | completely natural to use those objects as if they were numbers (e.g. for | |
6369c739 | 308 | comparisons). To do this, a version object contains both the original |
692a467c JP |
309 | representation as typed by the author, as well as a parsed representation |
310 | to ease comparisons. Version objects employ L<overload> methods to | |
311 | simplify code that needs to compare, print, etc the objects. | |
312 | ||
313 | The internal structure of version objects is a blessed hash with several | |
314 | components: | |
315 | ||
316 | bless( { | |
317 | 'original' => 'v1.2.3_4', | |
318 | 'alpha' => 1, | |
319 | 'qv' => 1, | |
320 | 'version' => [ | |
321 | 1, | |
322 | 2, | |
323 | 3, | |
324 | 4 | |
325 | ] | |
326 | }, 'version' ); | |
327 | ||
328 | =over 4 | |
329 | ||
330 | =item original | |
331 | ||
332 | A faithful representation of the value used to initialize this version | |
333 | object. The only time this will not be precisely the same characters | |
334 | that exist in the source file is if a short dotted-decimal version like | |
335 | v1.2 was used (in which case it will contain 'v1.2'). This form is | |
336 | B<STRONGLY> discouraged, in that it will confuse you and your users. | |
337 | ||
338 | =item qv | |
339 | ||
340 | A boolean that denotes whether this is a decimal or dotted-decimal version. | |
fe6e8b3e | 341 | See L<version/is_qv()>. |
692a467c JP |
342 | |
343 | =item alpha | |
344 | ||
345 | A boolean that denotes whether this is an alpha version. NOTE: that the | |
fe6e8b3e | 346 | underscore can can only appear in the last position. See L<version/is_alpha()>. |
692a467c JP |
347 | |
348 | =item version | |
349 | ||
350 | An array of non-negative integers that is used for comparison purposes with | |
351 | other version objects. | |
352 | ||
353 | =back | |
354 | ||
355 | =head2 Replacement UNIVERSAL::VERSION | |
356 | ||
357 | In addition to the version objects, this modules also replaces the core | |
358 | UNIVERSAL::VERSION function with one that uses version objects for its | |
359 | comparisons. The return from this operator is always the stringified form | |
360 | as a simple scalar (i.e. not an object), but the warning message generated | |
361 | includes either the stringified form or the normal form, depending on how | |
362 | it was called. | |
363 | ||
364 | For example: | |
365 | ||
366 | package Foo; | |
367 | $VERSION = 1.2; | |
368 | ||
369 | package Bar; | |
370 | $VERSION = "v1.3.5"; # works with all Perl's (since it is quoted) | |
371 | ||
372 | package main; | |
373 | use version; | |
374 | ||
375 | print $Foo::VERSION; # prints 1.2 | |
376 | ||
377 | print $Bar::VERSION; # prints 1.003005 | |
378 | ||
379 | eval "use foo 10"; | |
380 | print $@; # prints "foo version 10 required..." | |
381 | eval "use foo 1.3.5; # work in Perl 5.6.1 or better | |
382 | print $@; # prints "foo version 1.3.5 required..." | |
383 | ||
384 | eval "use bar 1.3.6"; | |
385 | print $@; # prints "bar version 1.3.6 required..." | |
386 | eval "use bar 1.004"; # note Decimal version | |
387 | print $@; # prints "bar version 1.004 required..." | |
388 | ||
389 | ||
390 | IMPORTANT NOTE: This may mean that code which searches for a specific | |
391 | string (to determine whether a given module is available) may need to be | |
392 | changed. It is always better to use the built-in comparison implicit in | |
d5213412 | 393 | C<use> or C<require>, rather than manually poking at C<< class->VERSION >> |
692a467c JP |
394 | and then doing a comparison yourself. |
395 | ||
396 | The replacement UNIVERSAL::VERSION, when used as a function, like this: | |
397 | ||
398 | print $module->VERSION; | |
399 | ||
fe6e8b3e | 400 | will also exclusively return the stringified form. See L</Stringification> |
692a467c JP |
401 | for more details. |
402 | ||
6369c739 | 403 | =head1 USAGE DETAILS |
692a467c JP |
404 | |
405 | =head2 Using modules that use version.pm | |
406 | ||
407 | As much as possible, the version.pm module remains compatible with all | |
408 | current code. However, if your module is using a module that has defined | |
409 | C<$VERSION> using the version class, there are a couple of things to be | |
410 | aware of. For purposes of discussion, we will assume that we have the | |
411 | following module installed: | |
412 | ||
413 | package Example; | |
414 | use version; $VERSION = qv('1.2.2'); | |
415 | ...module code here... | |
416 | 1; | |
417 | ||
418 | =over 4 | |
419 | ||
420 | =item Decimal versions always work | |
421 | ||
422 | Code of the form: | |
423 | ||
424 | use Example 1.002003; | |
425 | ||
426 | will always work correctly. The C<use> will perform an automatic | |
427 | C<$VERSION> comparison using the floating point number given as the first | |
428 | term after the module name (e.g. above 1.002.003). In this case, the | |
429 | installed module is too old for the requested line, so you would see an | |
430 | error like: | |
431 | ||
432 | Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)... | |
433 | ||
434 | =item Dotted-Decimal version work sometimes | |
435 | ||
436 | With Perl >= 5.6.2, you can also use a line like this: | |
437 | ||
438 | use Example 1.2.3; | |
439 | ||
440 | and it will again work (i.e. give the error message as above), even with | |
fe6e8b3e | 441 | releases of Perl which do not normally support v-strings (see L<What about v-strings?> above). This has to do with that fact that C<use> only checks |
692a467c | 442 | to see if the second term I<looks like a number> and passes that to the |
5bbbd807 | 443 | replacement L<UNIVERSAL::VERSION|UNIVERSAL/VERSION>. This is not true in Perl 5.005_04, |
692a467c JP |
444 | however, so you are B<strongly encouraged> to always use a Decimal version |
445 | in your code, even for those versions of Perl which support the Dotted-Decimal | |
446 | version. | |
447 | ||
448 | =back | |
449 | ||
450 | =head2 Object Methods | |
451 | ||
692a467c JP |
452 | =over 4 |
453 | ||
6369c739 | 454 | =item new() |
692a467c | 455 | |
6369c739 DG |
456 | Like many OO interfaces, the new() method is used to initialize version |
457 | objects. If two arguments are passed to C<new()>, the B<second> one will be | |
458 | used as if it were prefixed with "v". This is to support historical use of the | |
459 | C<qw> operator with the CVS variable $Revision, which is automatically | |
460 | incremented by CVS every time the file is committed to the repository. | |
692a467c JP |
461 | |
462 | In order to facilitate this feature, the following | |
463 | code can be employed: | |
464 | ||
465 | $VERSION = version->new(qw$Revision: 2.7 $); | |
466 | ||
467 | and the version object will be created as if the following code | |
468 | were used: | |
469 | ||
470 | $VERSION = version->new("v2.7"); | |
471 | ||
472 | In other words, the version will be automatically parsed out of the | |
473 | string, and it will be quoted to preserve the meaning CVS normally | |
474 | carries for versions. The CVS $Revision$ increments differently from | |
475 | Decimal versions (i.e. 1.10 follows 1.9), so it must be handled as if | |
64da3008 | 476 | it were a Dotted-Decimal Version. |
692a467c JP |
477 | |
478 | A new version object can be created as a copy of an existing version | |
479 | object, either as a class method: | |
480 | ||
481 | $v1 = version->new(12.3); | |
482 | $v2 = version->new($v1); | |
483 | ||
484 | or as an object method: | |
485 | ||
486 | $v1 = version->new(12.3); | |
487 | $v2 = $v1->new(12.3); | |
488 | ||
489 | and in each case, $v1 and $v2 will be identical. NOTE: if you create | |
490 | a new object using an existing object like this: | |
491 | ||
492 | $v2 = $v1->new(); | |
493 | ||
494 | the new object B<will not> be a clone of the existing object. In the | |
495 | example case, $v2 will be an empty object of the same type as $v1. | |
496 | ||
497 | =back | |
498 | ||
499 | =over 4 | |
500 | ||
345e2394 | 501 | =item qv() |
692a467c JP |
502 | |
503 | An alternate way to create a new version object is through the exported | |
504 | qv() sub. This is not strictly like other q? operators (like qq, qw), | |
505 | in that the only delimiters supported are parentheses (or spaces). It is | |
506 | the best way to initialize a short version without triggering the floating | |
507 | point interpretation. For example: | |
508 | ||
509 | $v1 = qv(1.2); # v1.2.0 | |
510 | $v2 = qv("1.2"); # also v1.2.0 | |
511 | ||
6369c739 | 512 | As you can see, either a bare number or a quoted string can usually |
98dc9551 | 513 | be used interchangeably, except in the case of a trailing zero, which |
692a467c JP |
514 | must be quoted to be converted properly. For this reason, it is strongly |
515 | recommended that all initializers to qv() be quoted strings instead of | |
516 | bare numbers. | |
517 | ||
518 | To prevent the C<qv()> function from being exported to the caller's namespace, | |
519 | either use version with a null parameter: | |
520 | ||
521 | use version (); | |
522 | ||
523 | or just require version, like this: | |
524 | ||
525 | require version; | |
526 | ||
527 | Both methods will prevent the import() method from firing and exporting the | |
6369c739 | 528 | C<qv()> sub. |
692a467c JP |
529 | |
530 | =back | |
531 | ||
532 | For the subsequent examples, the following three objects will be used: | |
533 | ||
6369c739 DG |
534 | $ver = version->new("1.2.3.4"); # see "Quoting Rules" |
535 | $alpha = version->new("1.2.3_4"); # see "Alpha Versions" | |
536 | $nver = version->new(1.002); # see "Decimal Versions" | |
692a467c JP |
537 | |
538 | =over 4 | |
539 | ||
345e2394 | 540 | =item Normal Form |
692a467c JP |
541 | |
542 | For any version object which is initialized with multiple decimal | |
543 | places (either quoted or if possible v-string), or initialized using | |
fe6e8b3e | 544 | the L<qv()|version/qv()> operator, the stringified representation is returned in |
692a467c JP |
545 | a normalized or reduced form (no extraneous zeros), and with a leading 'v': |
546 | ||
547 | print $ver->normal; # prints as v1.2.3.4 | |
548 | print $ver->stringify; # ditto | |
549 | print $ver; # ditto | |
550 | print $nver->normal; # prints as v1.2.0 | |
6369c739 | 551 | print $nver->stringify; # prints as 1.002, see "Stringification" |
692a467c | 552 | |
6369c739 | 553 | In order to preserve the meaning of the processed version, the |
692a467c JP |
554 | normalized representation will always contain at least three sub terms. |
555 | In other words, the following is guaranteed to always be true: | |
556 | ||
557 | my $newver = version->new($ver->stringify); | |
558 | if ($newver eq $ver ) # always true | |
559 | {...} | |
560 | ||
561 | =back | |
562 | ||
563 | =over 4 | |
564 | ||
345e2394 | 565 | =item Numification |
692a467c JP |
566 | |
567 | Although all mathematical operations on version objects are forbidden | |
6369c739 | 568 | by default, it is possible to retrieve a number which corresponds |
692a467c JP |
569 | to the version object through the use of the $obj->numify |
570 | method. For formatting purposes, when displaying a number which | |
571 | corresponds a version object, all sub versions are assumed to have | |
572 | three decimal places. So for example: | |
573 | ||
574 | print $ver->numify; # prints 1.002003004 | |
575 | print $nver->numify; # prints 1.002 | |
576 | ||
577 | Unlike the stringification operator, there is never any need to append | |
578 | trailing zeros to preserve the correct version value. | |
579 | ||
580 | =back | |
581 | ||
582 | =over 4 | |
583 | ||
345e2394 | 584 | =item Stringification |
692a467c JP |
585 | |
586 | The default stringification for version objects returns exactly the same | |
587 | string as was used to create it, whether you used C<new()> or C<qv()>, | |
588 | with one exception. The sole exception is if the object was created using | |
589 | C<qv()> and the initializer did not have two decimal places or a leading | |
590 | 'v' (both optional), then the stringified form will have a leading 'v' | |
591 | prepended, in order to support round-trip processing. | |
592 | ||
593 | For example: | |
594 | ||
595 | Initialized as Stringifies to | |
596 | ============== ============== | |
597 | version->new("1.2") 1.2 | |
598 | version->new("v1.2") v1.2 | |
599 | qv("1.2.3") 1.2.3 | |
600 | qv("v1.3.5") v1.3.5 | |
6369c739 | 601 | qv("1.2") v1.2 ### exceptional case |
692a467c | 602 | |
fe6e8b3e | 603 | See also L<UNIVERSAL::VERSION|UNIVERSAL/VERSION>, as this also returns the stringified form |
692a467c JP |
604 | when used as a class method. |
605 | ||
606 | IMPORTANT NOTE: There is one exceptional cases shown in the above table | |
607 | where the "initializer" is not stringwise equivalent to the stringified | |
64da3008 | 608 | representation. If you use the C<qv>() operator on a version without a |
692a467c | 609 | leading 'v' B<and> with only a single decimal place, the stringified output |
fe6e8b3e | 610 | will have a leading 'v', to preserve the sense. See the L</qv()> operator |
692a467c JP |
611 | for more details. |
612 | ||
613 | IMPORTANT NOTE 2: Attempting to bypass the normal stringification rules by | |
fe6e8b3e | 614 | manually applying L<numify()|version/numify()> and L<normal()|version/normal()> will sometimes yield |
692a467c JP |
615 | surprising results: |
616 | ||
617 | print version->new(version->new("v1.0")->numify)->normal; # v1.0.0 | |
618 | ||
fe6e8b3e | 619 | The reason for this is that the L<numify()|version/numify()> operator will turn "v1.0" |
692a467c | 620 | into the equivalent string "1.000000". Forcing the outer version object |
fe6e8b3e | 621 | to L<normal()|version/normal()> form will display the mathematically equivalent "v1.0.0". |
692a467c | 622 | |
1adc55b9 | 623 | As the example in L</new()> shows, you can always create a copy of an |
692a467c JP |
624 | existing version object with the same value by the very compact: |
625 | ||
626 | $v2 = $v1->new($v1); | |
627 | ||
628 | and be assured that both C<$v1> and C<$v2> will be completely equivalent, | |
629 | down to the same internal representation as well as stringification. | |
630 | ||
631 | =back | |
632 | ||
633 | =over 4 | |
634 | ||
345e2394 | 635 | =item Comparison operators |
692a467c JP |
636 | |
637 | Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between | |
638 | terms (upgrading to a version object automatically). Perl automatically | |
639 | generates all of the other comparison operators based on those two. | |
640 | In addition to the obvious equalities listed below, appending a single | |
641 | trailing 0 term does not change the value of a version for comparison | |
642 | purposes. In other words "v1.2" and "1.2.0" will compare as identical. | |
643 | ||
644 | For example, the following relations hold: | |
645 | ||
646 | As Number As String Truth Value | |
647 | ------------- ---------------- ----------- | |
648 | $ver > 1.0 $ver gt "1.0" true | |
649 | $ver < 2.5 $ver lt true | |
650 | $ver != 1.3 $ver ne "1.3" true | |
651 | $ver == 1.2 $ver eq "1.2" false | |
652 | $ver == 1.2.3.4 $ver eq "1.2.3.4" see discussion below | |
653 | ||
654 | It is probably best to chose either the Decimal notation or the string | |
655 | notation and stick with it, to reduce confusion. Perl6 version objects | |
6369c739 | 656 | B<may> only support Decimal comparisons. See also L<Quoting Rules>. |
692a467c JP |
657 | |
658 | WARNING: Comparing version with unequal numbers of decimal points (whether | |
659 | explicitly or implicitly initialized), may yield unexpected results at | |
660 | first glance. For example, the following inequalities hold: | |
661 | ||
662 | version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0 | |
663 | version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0 | |
664 | ||
665 | For this reason, it is best to use either exclusively L<Decimal Versions> or | |
666 | L<Dotted-Decimal Versions> with multiple decimal points. | |
667 | ||
668 | =back | |
669 | ||
670 | =over 4 | |
671 | ||
345e2394 | 672 | =item Logical Operators |
692a467c JP |
673 | |
674 | If you need to test whether a version object | |
675 | has been initialized, you can simply test it directly: | |
676 | ||
677 | $vobj = version->new($something); | |
678 | if ( $vobj ) # true only if $something was non-blank | |
679 | ||
dc08a87b | 680 | You can also test whether a version object is an alpha version, for |
692a467c JP |
681 | example to prevent the use of some feature not present in the main |
682 | release: | |
683 | ||
684 | $vobj = version->new("1.2_3"); # MUST QUOTE | |
685 | ...later... | |
686 | if ( $vobj->is_alpha ) # True | |
687 | ||
688 | =back | |
689 | ||
692a467c JP |
690 | =head1 AUTHOR |
691 | ||
692 | John Peacock E<lt>jpeacock@cpan.orgE<gt> | |
693 | ||
694 | =head1 SEE ALSO | |
695 | ||
696 | L<perl>. | |
697 | ||
698 | =cut |