This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
856383cf12ea1bb2891557fe0002d7735dd3786e
[perl5.git] / lib / version / Internals.pod
1 =head1 NAME
2
3 version::Internal - Perl extension for Version Objects
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
9 L<version.pod> for daily usage.  This document is only useful for users
10 writing a subclass of version.pm or interested in the gory details.
11
12 =head1 What IS a version
13
14 For the purposes of this module, a version "number" is a sequence of
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 
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
24 =item Decimal Versions
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
28 underscore, see L<Decimal Alpha Versions>, even though these must be quoted
29 to preserve the underscore formatting.
30
31 =item Dotted-Decimal Versions
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
42 the default stringification will yield the version L<Normal Form> only 
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
66                                    # Prints     Equivalent to  
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
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<version/Alpha Versions> for how to handle
77
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.  
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
89 method normally requires that the input parameter be quoted, although 
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
105 uniformity.  See also L<New Operator> for an additional method of
106 initializing version objects.
107
108 Just like L<Decimal Versions>, Dotted-Decimal Versions can be used as 
109 L<version/Alpha Versions>.
110
111 =head2 Decimal Alpha Versions
112
113 The one time that a Decimal version must be quoted is when a alpha form is
114 used with an otherwise Decimal version (i.e. a single decimal point).  This
115 is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
116 versions for automatic updating purposes.  Since some developers have used
117 only two significant decimal places for their non-alpha releases, the
118 version object will automatically take that into account if the initializer
119 is quoted.  For example Module::Example was released to CPAN with the
120 following sequence of $VERSION's:
121
122   # $VERSION    Stringified
123   0.01          0.01
124   0.02          0.02
125   0.02_01       0.02_01
126   0.02_02       0.02_02
127   0.03          0.03
128   etc.
129
130 The stringified form of Decimal versions will always be the same string
131 that was used to initialize the version object.
132
133 =head2 Regular Expressions for Version Parsing
134
135 A formalized definition of the legal forms for version strings is
136 included in the main F<version.pm> file.  Primitives are included for
137 common elements, although they are scoped to the file so they are useful
138 for reference purposes only.  There are two publicly accessible scalars
139 that can be used in other code (not exported):
140
141 =over 4
142
143 =item C<$version::LAX>
144
145 This regexp covers all of the legal forms allowed under the current
146 version string parser.  This is not to say that all of these forms
147 are recommended, and some of them can only be used when quoted.
148
149 For dotted decimals:
150
151     v1.2
152     1.2345.6
153     v1.23_4
154
155 The leading 'v' is optional if two or more decimals appear.  If only
156 a single decimal is included, then the leading 'v' is required to
157 trigger the dotted-decimal parsing.  A leading zero is permitted,
158 though not recommended except when quoted, because of the risk that
159 Perl will treat the number as octal.  A trailing underscore plus one
160 or more digits denotes an alpha or development release (and must be
161 quoted to be parsed properly).
162
163 For decimal versions:
164
165     1
166     1.2345
167     1.2345_01
168
169 an integer portion, an optional decimal point, and optionally one or
170 more digits to the right of the decimal are all required.  A trailing
171 underscore is permitted and a leading zero is permitted.  Just like
172 the lax dotted-decimal version, quoting the values is required for
173 alpha/development forms to be parsed correctly.
174
175 =item C<$version::STRICT>
176
177 This regexp covers a much more limited set of formats and constitutes
178 the best practices for initializing version objects.  Whether you choose
179 to employ decimal or dotted-decimal for is a personal preference however.
180
181 =over 4
182
183 =item v1.234.5
184
185 For dotted-decimal versions, a leading 'v' is required, with three or
186 more sub-versions of no more than three digits.  A leading 0 (zero)
187 before the first sub-version (in the above example, '1') is also
188 prohibited.
189
190 =item 2.3456
191
192 For decimal versions, an integer portion (no leading 0), a decimal point,
193 and one or more digits to the right of the decimal are all required.
194
195 =back
196
197 =back
198
199 Both of the provided scalars are already compiled as regular expressions
200 and do not contain either anchors or implicit groupings, so they can be
201 included in your own regular expressions freely.  For example, consider
202 the following code:
203
204         ($pkg, $ver) =~ /
205                 ^[ \t]*
206                 use [ \t]+($PKGNAME)
207                 (?:[ \t]+($version::STRICT))?
208                 [ \t]*;
209         /x;
210
211 This would match a line of the form:
212
213         use Foo::Bar::Baz v1.2.3;       # legal only in Perl 5.8.1+
214
215 where C<$PKGNAME> is another regular expression that defines the legal
216 forms for package names.
217
218 =head1 High level design
219
220 =head2 version objects
221
222 version.pm provides an overloaded version object that is designed to both 
223 encapsulate the author's intended $VERSION assignment as well as make it
224 completely natural to use those objects as if they were numbers (e.g. for
225 comparisons).  To do this, a version object contains both the original 
226 representation as typed by the author, as well as a parsed representation
227 to ease comparisons.  Version objects employ L<overload> methods to
228 simplify code that needs to compare, print, etc the objects.
229
230 The internal structure of version objects is a blessed hash with several
231 components:
232
233     bless( {
234       'original' => 'v1.2.3_4',
235       'alpha' => 1,
236       'qv' => 1,
237       'version' => [
238         1,
239         2,
240         3,
241         4
242       ]
243     }, 'version' );
244
245 =over 4
246
247 =item original
248
249 A faithful representation of the value used to initialize this version
250 object.  The only time this will not be precisely the same characters
251 that exist in the source file is if a short dotted-decimal version like
252 v1.2 was used (in which case it will contain 'v1.2').  This form is
253 B<STRONGLY> discouraged, in that it will confuse you and your users.
254
255 =item qv
256
257 A boolean that denotes whether this is a decimal or dotted-decimal version.
258 See L<is_qv>.
259
260 =item alpha
261
262 A boolean that denotes whether this is an alpha version.  NOTE: that the
263 underscore can can only appear in the last position.  See L<is_alpha>.
264
265 =item version
266
267 An array of non-negative integers that is used for comparison purposes with
268 other version objects.
269
270 =back
271
272 =head2 Replacement UNIVERSAL::VERSION
273
274 In addition to the version objects, this modules also replaces the core
275 UNIVERSAL::VERSION function with one that uses version objects for its
276 comparisons.  The return from this operator is always the stringified form
277 as a simple scalar (i.e. not an object), but the warning message generated
278 includes either the stringified form or the normal form, depending on how
279 it was called.
280
281 For example:
282
283   package Foo;
284   $VERSION = 1.2;
285
286   package Bar;
287   $VERSION = "v1.3.5"; # works with all Perl's (since it is quoted)
288
289   package main;
290   use version;
291
292   print $Foo::VERSION; # prints 1.2
293
294   print $Bar::VERSION; # prints 1.003005
295
296   eval "use foo 10";
297   print $@; # prints "foo version 10 required..."
298   eval "use foo 1.3.5; # work in Perl 5.6.1 or better
299   print $@; # prints "foo version 1.3.5 required..."
300
301   eval "use bar 1.3.6";
302   print $@; # prints "bar version 1.3.6 required..."
303   eval "use bar 1.004"; # note Decimal version
304   print $@; # prints "bar version 1.004 required..."
305
306
307 IMPORTANT NOTE: This may mean that code which searches for a specific
308 string (to determine whether a given module is available) may need to be
309 changed.  It is always better to use the built-in comparison implicit in
310 C<use> or C<require>, rather than manually poking at C<< class->VERSION >>
311 and then doing a comparison yourself.
312
313 The replacement UNIVERSAL::VERSION, when used as a function, like this:
314
315   print $module->VERSION;
316
317 will also exclusively return the stringified form.  See L<Stringification>
318 for more details.
319
320 =head1 Usage question
321
322 =head2 Using modules that use version.pm
323
324 As much as possible, the version.pm module remains compatible with all
325 current code.  However, if your module is using a module that has defined
326 C<$VERSION> using the version class, there are a couple of things to be
327 aware of.  For purposes of discussion, we will assume that we have the
328 following module installed:
329
330   package Example;
331   use version;  $VERSION = qv('1.2.2');
332   ...module code here...
333   1;
334
335 =over 4
336
337 =item Decimal versions always work
338
339 Code of the form:
340
341   use Example 1.002003;
342
343 will always work correctly.  The C<use> will perform an automatic
344 C<$VERSION> comparison using the floating point number given as the first
345 term after the module name (e.g. above 1.002.003).  In this case, the
346 installed module is too old for the requested line, so you would see an
347 error like:
348
349   Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
350
351 =item Dotted-Decimal version work sometimes
352
353 With Perl >= 5.6.2, you can also use a line like this:
354
355   use Example 1.2.3;
356
357 and it will again work (i.e. give the error message as above), even with
358 releases of Perl which do not normally support v-strings (see L<version/What about v-strings> below).  This has to do with that fact that C<use> only checks
359 to see if the second term I<looks like a number> and passes that to the
360 replacement L<UNIVERSAL::VERSION>.  This is not true in Perl 5.005_04,
361 however, so you are B<strongly encouraged> to always use a Decimal version
362 in your code, even for those versions of Perl which support the Dotted-Decimal
363 version.
364
365 =back
366
367 =head2 Object Methods
368
369 Overloading has been used with version objects to provide a natural
370 interface for their use.  All mathematical operations are forbidden,
371 since they don't make any sense for base version objects.  Consequently,
372 there is no overloaded numification available.  If you want to use a
373 version object in a Decimal context for some reason, see the L<numify>
374 object method.
375
376 =over 4
377
378 =item New Operator
379
380 Like all OO interfaces, the new() operator is used to initialize
381 version objects.  One way to increment versions when programming is to
382 use the CVS variable $Revision, which is automatically incremented by
383 CVS every time the file is committed to the repository.
384
385 In order to facilitate this feature, the following
386 code can be employed:
387
388   $VERSION = version->new(qw$Revision: 2.7 $);
389
390 and the version object will be created as if the following code
391 were used:
392
393   $VERSION = version->new("v2.7");
394
395 In other words, the version will be automatically parsed out of the
396 string, and it will be quoted to preserve the meaning CVS normally
397 carries for versions.  The CVS $Revision$ increments differently from
398 Decimal versions (i.e. 1.10 follows 1.9), so it must be handled as if
399 it were a Dotted-Decimal Version.
400
401 A new version object can be created as a copy of an existing version
402 object, either as a class method:
403
404   $v1 = version->new(12.3);
405   $v2 = version->new($v1);
406
407 or as an object method:
408
409   $v1 = version->new(12.3);
410   $v2 = $v1->new(12.3);
411
412 and in each case, $v1 and $v2 will be identical.  NOTE: if you create
413 a new object using an existing object like this:
414
415   $v2 = $v1->new();
416
417 the new object B<will not> be a clone of the existing object.  In the
418 example case, $v2 will be an empty object of the same type as $v1.
419
420 =back
421
422 =over 4
423
424 =item qv()
425
426 An alternate way to create a new version object is through the exported
427 qv() sub.  This is not strictly like other q? operators (like qq, qw),
428 in that the only delimiters supported are parentheses (or spaces).  It is
429 the best way to initialize a short version without triggering the floating
430 point interpretation.  For example:
431
432   $v1 = qv(1.2);         # v1.2.0
433   $v2 = qv("1.2");       # also v1.2.0
434
435 As you can see, either a bare number or a quoted string can usually 
436 be used interchangably, except in the case of a trailing zero, which
437 must be quoted to be converted properly.  For this reason, it is strongly
438 recommended that all initializers to qv() be quoted strings instead of
439 bare numbers.
440
441 To prevent the C<qv()> function from being exported to the caller's namespace,
442 either use version with a null parameter:
443
444   use version ();
445
446 or just require version, like this:
447
448   require version;
449
450 Both methods will prevent the import() method from firing and exporting the
451 C<qv()> sub.  This is true of subclasses of version as well, see
452 L<SUBCLASSING> for details.
453
454 =back
455
456 For the subsequent examples, the following three objects will be used:
457
458   $ver   = version->new("1.2.3.4"); # see "Quoting" below
459   $alpha = version->new("1.2.3_4"); # see "<version/Alpha versions" below
460   $nver  = version->new(1.002);     # see "Decimal Versions" above
461
462 =over 4
463
464 =item Normal Form
465
466 For any version object which is initialized with multiple decimal
467 places (either quoted or if possible v-string), or initialized using
468 the L<qv>() operator, the stringified representation is returned in
469 a normalized or reduced form (no extraneous zeros), and with a leading 'v':
470
471   print $ver->normal;         # prints as v1.2.3.4
472   print $ver->stringify;      # ditto
473   print $ver;                 # ditto
474   print $nver->normal;        # prints as v1.2.0
475   print $nver->stringify;     # prints as 1.002, see "Stringification" 
476
477 In order to preserve the meaning of the processed version, the 
478 normalized representation will always contain at least three sub terms.
479 In other words, the following is guaranteed to always be true:
480
481   my $newver = version->new($ver->stringify);
482   if ($newver eq $ver ) # always true
483     {...}
484
485 =back
486
487 =over 4
488
489 =item Numification
490
491 Although all mathematical operations on version objects are forbidden
492 by default, it is possible to retrieve a number which corresponds 
493 to the version object through the use of the $obj->numify
494 method.  For formatting purposes, when displaying a number which
495 corresponds a version object, all sub versions are assumed to have
496 three decimal places.  So for example:
497
498   print $ver->numify;         # prints 1.002003004
499   print $nver->numify;        # prints 1.002
500
501 Unlike the stringification operator, there is never any need to append
502 trailing zeros to preserve the correct version value.
503
504 =back
505
506 =over 4
507
508 =item Stringification
509
510 The default stringification for version objects returns exactly the same
511 string as was used to create it, whether you used C<new()> or C<qv()>,
512 with one exception.  The sole exception is if the object was created using
513 C<qv()> and the initializer did not have two decimal places or a leading
514 'v' (both optional), then the stringified form will have a leading 'v'
515 prepended, in order to support round-trip processing.
516
517 For example:
518
519   Initialized as          Stringifies to
520   ==============          ==============
521   version->new("1.2")       1.2
522   version->new("v1.2")     v1.2
523   qv("1.2.3")               1.2.3
524   qv("v1.3.5")             v1.3.5
525   qv("1.2")                v1.2   ### exceptional case 
526
527 See also L<UNIVERSAL::VERSION>, as this also returns the stringified form
528 when used as a class method.
529
530 IMPORTANT NOTE: There is one exceptional cases shown in the above table
531 where the "initializer" is not stringwise equivalent to the stringified
532 representation.  If you use the C<qv>() operator on a version without a
533 leading 'v' B<and> with only a single decimal place, the stringified output
534 will have a leading 'v', to preserve the sense.  See the L<qv>() operator
535 for more details.
536
537 IMPORTANT NOTE 2: Attempting to bypass the normal stringification rules by
538 manually applying L<numify>() and L<normal>() will sometimes yield
539 surprising results:
540
541   print version->new(version->new("v1.0")->numify)->normal; # v1.0.0
542
543 The reason for this is that the L<numify>() operator will turn "v1.0"
544 into the equivalent string "1.000000".  Forcing the outer version object
545 to L<normal>() form will display the mathematically equivalent "v1.0.0".
546
547 As the example in L<new>() shows, you can always create a copy of an
548 existing version object with the same value by the very compact:
549
550   $v2 = $v1->new($v1);
551
552 and be assured that both C<$v1> and C<$v2> will be completely equivalent,
553 down to the same internal representation as well as stringification.
554
555 =back
556
557 =over 4
558
559 =item Comparison operators
560
561 Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between
562 terms (upgrading to a version object automatically).  Perl automatically
563 generates all of the other comparison operators based on those two.
564 In addition to the obvious equalities listed below, appending a single
565 trailing 0 term does not change the value of a version for comparison
566 purposes.  In other words "v1.2" and "1.2.0" will compare as identical.
567
568 For example, the following relations hold:
569
570   As Number        As String           Truth Value
571   -------------    ----------------    -----------
572   $ver >  1.0      $ver gt "1.0"       true
573   $ver <  2.5      $ver lt             true
574   $ver != 1.3      $ver ne "1.3"       true
575   $ver == 1.2      $ver eq "1.2"       false
576   $ver == 1.2.3.4  $ver eq "1.2.3.4"   see discussion below
577
578 It is probably best to chose either the Decimal notation or the string
579 notation and stick with it, to reduce confusion.  Perl6 version objects
580 B<may> only support Decimal comparisons.  See also L<Quoting>.
581
582 WARNING: Comparing version with unequal numbers of decimal points (whether
583 explicitly or implicitly initialized), may yield unexpected results at
584 first glance.  For example, the following inequalities hold:
585
586   version->new(0.96)     > version->new(0.95); # 0.960.0 > 0.950.0
587   version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
588
589 For this reason, it is best to use either exclusively L<Decimal Versions> or
590 L<Dotted-Decimal Versions> with multiple decimal points.
591
592 =back
593
594 =over 4
595
596 =item Logical Operators
597
598 If you need to test whether a version object
599 has been initialized, you can simply test it directly:
600
601   $vobj = version->new($something);
602   if ( $vobj )   # true only if $something was non-blank
603
604 You can also test whether a version object is an L<version/Alpha version>, for
605 example to prevent the use of some feature not present in the main
606 release:
607
608   $vobj = version->new("1.2_3"); # MUST QUOTE
609   ...later...
610   if ( $vobj->is_alpha )       # True
611
612 =back
613
614 =head2 Quoting
615
616 Because of the nature of the Perl parsing and tokenizing routines,
617 certain initialization values B<must> be quoted in order to correctly
618 parse as the intended version, especially when using the L<qv>() operator.
619 In all cases, a floating point number passed to version->new() will be
620 identically converted whether or not the value itself is quoted.  This is
621 not true for L<qv>(), however, when trailing zeros would be stripped on
622 an unquoted input, which would result in a very different version object.
623
624 In addition, in order to be compatible with earlier Perl version styles,
625 any use of versions of the form 5.006001 will be translated as v5.6.1.  
626 In other words, a version with a single decimal point will be parsed as
627 implicitly having three digits between subversions, but only for internal
628 comparison purposes.
629
630 The complicating factor is that in bare numbers (i.e. unquoted), the
631 underscore is a legal Decimal character and is automatically stripped
632 by the Perl tokenizer before the version code is called.  However, if
633 a number containing one or more decimals and an underscore is quoted, i.e.
634 not bare, that is considered an L<version/Alpha version> and the underscore is
635 significant.
636
637 If you use a mathematic formula that resolves to a floating point number,
638 you are dependent on Perl's conversion routines to yield the version you
639 expect.  You are pretty safe by dividing by a power of 10, for example,
640 but other operations are not likely to be what you intend.  For example:
641
642   $VERSION = version->new((qw$Revision: 1.4)[1]/10);
643   print $VERSION;          # yields 0.14
644   $V2 = version->new(100/9); # Integer overflow in decimal number
645   print $V2;               # yields something like 11.111.111.100
646
647 Perl 5.8.1 and beyond will be able to automatically quote v-strings but
648 that is not possible in earlier versions of Perl.  In other words:
649
650   $version = version->new("v2.5.4");  # legal in all versions of Perl
651   $newvers = version->new(v2.5.4);    # legal only in Perl >= 5.8.1
652
653 =head1 SUBCLASSING
654
655 This module is specifically designed and tested to be easily subclassed.
656 In practice, you only need to override the methods you want to change, but
657 you have to take some care when overriding new() (since that is where all
658 of the parsing takes place).  For example, this is a perfect acceptable
659 derived class:
660
661   package myversion;
662   use base version;
663   sub new { 
664       my($self,$n)=@_;
665       my $obj;
666       # perform any special input handling here
667       $obj = $self->SUPER::new($n);
668       # and/or add additional hash elements here
669       return $obj;
670   }
671
672 See also L<version::AlphaBeta> on CPAN for an alternate representation of
673 version strings.
674
675 B<NOTE:> Although the L<qv> operator is not a true class method, but rather a
676 function exported into the caller's namespace, a subclass of version will 
677 inherit an import() function which will perform the correct magic on behalf
678 of the subclass.
679
680 =head1 EXPORT
681
682 qv - Dotted-Decimal Version initialization operator
683
684 =head1 AUTHOR
685
686 John Peacock E<lt>jpeacock@cpan.orgE<gt>
687
688 =head1 SEE ALSO
689
690 L<perl>.
691
692 =cut