This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fwd: CPAN Upload: J/JP/JPEACOCK/version-0.70.tar.gz
[perl5.git] / lib / version.pod
1 =head1 NAME
2
3 version - Perl extension for Version Objects
4
5 =head1 SYNOPSIS
6
7   use version;
8   $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
9   print $version;               # v12.2.1
10   print $version->numify;       # 12.002001
11   if ( $version gt "12.2" )     # true
12
13   $alphaver = version->new("1.02_03"); # must be quoted!
14   print $alphaver;              # 1.02_0300
15   print $alphaver->is_alpha();  # true
16   
17   $ver = qv("1.2.0");           # v1.2.0
18
19   $perlver = version->new(5.005_03); # must not be quoted!
20   print $perlver;               # 5.005030
21
22 =head1 DESCRIPTION
23
24 Overloaded version objects for all modern versions of Perl.  This module
25 implements all of the features of version objects which will be part
26 of Perl 5.10.0.
27
28 =head2 BEST PRACTICES
29
30 If you intend for your module to be used by different releases of Perl,
31 and/or for your $VERSION scalar to mean what you think it means, there 
32 are a few simple rules to follow:
33
34 =over 4
35
36 =item * Be consistent
37
38 Whichever of the two types of version objects that you choose to employ, 
39 you should stick to either L<Numeric Versions> or L<Extended Versions>
40 and not mix them together.  While this is I<possible>, it is very 
41 confusing to the average user.
42
43 If you intend to use L<Extended Versions>, you are strongly encouraged 
44 to use the L<qv()> operator with a quoted term, e.g.:
45
46   use version; our $VERSION = qv("1.2.3");
47
48 on a single line as above. 
49
50 At the very least, decide on which of the several ways to initialize 
51 your version objects you prefer and stick with it.  It is also best to 
52 be explicit about what value you intend to assign your version object 
53 and to not rely on hidden behavior of the parser. 
54
55 =item * Be careful
56
57 If you are using Module::Build or ExtUtils::MakeMaker, so that you can
58 release your module to CPAN, you have to recognize that neither of those
59 programs completely handles version objects natively (yet).  If you use
60 version objects with Module::Build, you should add an explicit dependency
61 to the release of version.pm in your Build.PL:
62
63   my $builder = Module::Build->new(
64      ...
65      requires => {
66          ... ,
67          'version'    => 0.50,
68          ...,
69      },
70      ...
71   );
72
73 and it should Just Work(TM).  Module::Build will [hopefully soon] 
74 include full support for version objects; there are no current plans 
75 to patch ExtUtils::MakeMaker to support version objects.
76
77 =back
78
79 =head2 Using modules that use version.pm
80
81 As much as possible, the version.pm module remains compatible with all
82 current code.  However, if your module is using a module that has defined
83 C<$VERSION> using the version class, there are a couple of things to be
84 aware of.  For purposes of discussion, we will assume that we have the
85 following module installed:
86
87   package Example;
88   use version;  $VERSION = qv('1.2.2');
89   ...module code here...
90   1;
91
92 =over 4
93
94 =item Numeric versions always work
95
96 Code of the form:
97
98   use Example 1.002003;
99
100 will always work correctly.  The C<use> will perform an automatic
101 C<$VERSION> comparison using the floating point number given as the first
102 term after the module name (e.g. above 1.002.003).  In this case, the
103 installed module is too old for the requested line, so you would see an
104 error like:
105
106   Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
107
108 =item Extended version work sometimes
109
110 With Perl >= 5.6.2, you can also use a line like this:
111
112   use Example 1.2.3;
113
114 and it will again work (i.e. give the error message as above), even with
115 releases of Perl which do not normally support v-strings (see L<What about
116 v-strings> below).  This has to do with that fact that C<use> only checks
117 to see if the second term I<looks like a number> and passes that to the
118 replacement L<UNIVERSAL::VERSION>.  This is not true in Perl 5.005_04,
119 however, so you are B<strongly encouraged> to always use a numeric version
120 in your code, even for those versions of Perl which support the extended
121 version.
122
123 =back
124
125 =head2 What IS a version
126
127 For the purposes of this module, a version "number" is a sequence of
128 positive integer values separated by one or more decimal points and 
129 optionally a single underscore.  This corresponds to what Perl itself 
130 uses for a version, as well as extending the "version as number" that 
131 is discussed in the various editions of the Camel book.
132
133 There are actually two distinct kinds of version objects:
134
135 =over 4
136
137 =item * Numeric Versions
138
139 Any initial parameter which "looks like a number", see L<Numeric
140 Versions>.  This also covers versions with a single decimal point and
141 a single embedded underscore, see L<Numeric Alpha Versions>, even though
142 these must be quoted to preserve the underscore formatting.
143
144 =item * Extended Versions
145
146 Any initial parameter which contains more than one decimal point
147 and an optional embedded underscore, see L<Extended Versions>.  This 
148 is what is commonly used in most open source software as the "external"
149 version (the one used as part of the tag or tarfile name).  The use
150 of the exported L<qv()> function also produces this kind of version
151 object.
152
153 =back
154
155 Both of these methods will produce similar version objects, in that
156 the default stringification will yield the version L<Normal Form> only 
157 if required:
158
159   $v  = version->new(1.002);     # 1.002, but compares like 1.2.0
160   $v  = version->new(1.002003);  # 1.002003
161   $v2 = version->new("1.2.3");   # v1.2.3
162
163 In specific, version numbers initialized as L<Numeric Versions> will
164 stringify in Numeric form.  Version numbers initialized as L<Extended Versions>
165 will be stringified as L<Normal Form>.
166
167 =head2 Numeric Versions
168
169 These correspond to historical versions of Perl itself prior to 5.6.0,
170 as well as all other modules which follow the Camel rules for the
171 $VERSION scalar.  A numeric version is initialized with what looks like
172 a floating point number.  Leading zeros B<are> significant and trailing
173 zeros are implied so that a minimum of three places is maintained
174 between subversions.  What this means is that any subversion (digits
175 to the right of the decimal place) that contains less than three digits
176 will have trailing zeros added to make up the difference, but only for
177 purposes of comparison with other version objects.  For example:
178
179                                    # Prints     Equivalent to  
180   $v = version->new(      1.2);    # 1.200      v1.200.0
181   $v = version->new(     1.02);    # 1.020      v1.20.0
182   $v = version->new(    1.002);    # 1.002      v1.2.0
183   $v = version->new(   1.0023);    # 1.002300   v1.2.300
184   $v = version->new(  1.00203);    # 1.002030   v1.2.30
185   $v = version->new( 1.002003);    # 1.002003   v1.2.3
186
187 All of the preceding examples are true whether or not the input value is 
188 quoted.  The important feature is that the input value contains only a 
189 single decimal.  See also L<Alpha Versions> for how to handle 
190
191 IMPORTANT NOTE: As shown above, if your numeric version contains more 
192 than 3 significant digits after the decimal place, it will be split on 
193 each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need 
194 to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation.  
195 Any trailing zeros are ignored for mathematical comparison purposes.
196
197 =head2 Extended Versions
198
199 These are the newest form of versions, and correspond to Perl's own
200 version style beginning with 5.6.0.  Starting with Perl 5.10.0,
201 and most likely Perl 6, this is likely to be the preferred form.  This
202 method normally requires that the input parameter be quoted, although 
203 Perl's after 5.8.1 can use v-strings as a special form of quoting, but
204 this is highly discouraged.
205
206 Unlike L<Numeric Versions>, Extended Versions have more than
207 a single decimal point, e.g.:
208
209                                    # Prints
210   $v = version->new( "v1.200");    # v1.200.0
211   $v = version->new("v1.20.0");    # v1.20.0
212   $v = qv("v1.2.3");               # v1.2.3
213   $v = qv("1.2.3");                # v1.2.3
214   $v = qv("1.20");                 # v1.20.0
215
216 In general, Extended Versions permit the greatest amount of freedom
217 to specify a version, whereas Numeric Versions enforce a certain
218 uniformity.  See also L<New Operator> for an additional method of
219 initializing version objects.
220
221 Just like L<Numeric Versions>, Extended Versions can be used as 
222 L<Alpha Versions>.
223
224 =head2 Numeric Alpha Versions
225
226 The one time that a numeric version must be quoted is when a alpha form is
227 used with an otherwise numeric version (i.e. a single decimal point).  This
228 is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
229 versions for automatic updating purposes.  Since some developers have used
230 only two significant decimal places for their non-alpha releases, the
231 version object will automatically take that into account if the initializer
232 is quoted.  For example Module::Example was released to CPAN with the
233 following sequence of $VERSION's:
234
235   # $VERSION    Stringified
236   0.01          0.010
237   0.02          0.020
238   0.02_01       0.02_0100
239   0.02_02       0.02_0200
240   0.03          0.030
241   etc.
242
243 As you can see, the version object created from the values in the first
244 column may contain a trailing 0, but will otherwise be both mathematically
245 equivalent and sorts alpha-numerically as would be expected.
246
247 =head2 Object Methods
248
249 Overloading has been used with version objects to provide a natural
250 interface for their use.  All mathematical operations are forbidden,
251 since they don't make any sense for base version objects.  Consequently,
252 there is no overloaded numification available.  If you want to use a
253 version object in a numeric context for some reason, see the L<numify>
254 object method.
255
256 =over 4
257
258 =item * New Operator
259
260 Like all OO interfaces, the new() operator is used to initialize
261 version objects.  One way to increment versions when programming is to
262 use the CVS variable $Revision, which is automatically incremented by
263 CVS every time the file is committed to the repository.
264
265 In order to facilitate this feature, the following
266 code can be employed:
267
268   $VERSION = version->new(qw$Revision: 2.7 $);
269
270 and the version object will be created as if the following code
271 were used:
272
273   $VERSION = version->new("v2.7");
274
275 In other words, the version will be automatically parsed out of the
276 string, and it will be quoted to preserve the meaning CVS normally
277 carries for versions.  The CVS $Revision$ increments differently from
278 numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
279 it were a L<Extended Version>.
280
281 A new version object can be created as a copy of an existing version
282 object, either as a class method:
283
284   $v1 = version->new(12.3);
285   $v2 = version->new($v1);
286
287 or as an object method:
288
289   $v1 = version->new(12.3);
290   $v2 = $v1->new(12.3);
291
292 and in each case, $v1 and $v2 will be identical.  NOTE: if you create
293 a new object using an existing object like this:
294
295   $v2 = $v1->new();
296
297 the new object B<will not> be a clone of the existing object.  In the
298 example case, $v2 will be an empty object of the same type as $v1.
299
300 =back
301
302 =over 4
303
304 =item * qv()
305
306 An alternate way to create a new version object is through the exported
307 qv() sub.  This is not strictly like other q? operators (like qq, qw),
308 in that the only delimiters supported are parentheses (or spaces).  It is
309 the best way to initialize a short version without triggering the floating
310 point interpretation.  For example:
311
312   $v1 = qv(1.2);         # 1.2.0
313   $v2 = qv("1.2");       # also 1.2.0
314
315 As you can see, either a bare number or a quoted string can usually 
316 be used interchangably, except in the case of a trailing zero, which
317 must be quoted to be converted properly.  For this reason, it is strongly
318 recommended that all initializers to qv() be quoted strings instead of
319 bare numbers.
320
321 To prevent the C<qv()> function from being exported to the caller's namespace,
322 either use version with a null parameter:
323
324   use version ();
325
326 or just require version, like this:
327
328   require version;
329
330 Both methods will prevent the import() method from firing and exporting the
331 C<qv()> sub.  This is true of subclasses of version as well, see
332 L<SUBCLASSING> for details.
333
334 =back
335
336 For the subsequent examples, the following three objects will be used:
337
338   $ver   = version->new("1.2.3.4"); # see "Quoting" below
339   $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
340   $nver  = version->new(1.002);     # see "Numeric Versions" above
341
342 =over 4
343
344 =item * Normal Form
345
346 For any version object which is initialized with multiple decimal
347 places (either quoted or if possible v-string), or initialized using
348 the L<qv()> operator, the stringified representation is returned in
349 a normalized or reduced form (no extraneous zeros), and with a leading 'v':
350
351   print $ver->normal;         # prints as v1.2.3.4
352   print $ver->stringify;      # ditto
353   print $ver;                 # ditto
354   print $nver->normal;        # prints as v1.2.0
355   print $nver->stringify;     # prints as 1.002, see "Stringification" 
356
357 In order to preserve the meaning of the processed version, the 
358 normalized representation will always contain at least three sub terms.
359 In other words, the following is guaranteed to always be true:
360
361   my $newver = version->new($ver->stringify);
362   if ($newver eq $ver ) # always true
363     {...}
364
365 =back
366
367 =over 4
368
369 =item * Numification
370
371 Although all mathematical operations on version objects are forbidden
372 by default, it is possible to retrieve a number which corresponds 
373 to the version object through the use of the $obj->numify
374 method.  For formatting purposes, when displaying a number which
375 corresponds a version object, all sub versions are assumed to have
376 three decimal places.  So for example:
377
378   print $ver->numify;         # prints 1.002003004
379   print $nver->numify;        # prints 1.002
380
381 Unlike the stringification operator, there is never any need to append
382 trailing zeros to preserve the correct version value.
383
384 =back
385
386 =over 4
387
388 =item * Stringification
389
390 In order to mirror as much as possible the existing behavior of ordinary
391 $VERSION scalars, the stringification operation will display differently,
392 depending on whether the version was initialized as a L<Numeric Version>
393 or L<Extended Version>.
394
395 What this means in practice is that if the normal CPAN and Camel rules are
396 followed ($VERSION is a floating point number with no more than 3 decimal
397 points), the stringified output will be exactly the same as the numified
398 output.  There will be no visible difference, although the internal 
399 representation will be different, and the L<Comparison operators> will 
400 function using the internal coding.
401
402 If a version object is initialized using a L<Extended Version> form, then
403 the stringified form will be the L<Normal Form>.  The $obj->normal
404 operation can always be used to produce the L<Normal Form>, even if the
405 version was originally a L<Numeric Version>.
406
407   print $ver->stringify;    # prints v1.2.3.4
408   print $nver->stringify;   # prints 1.002
409
410 =back
411
412 =over 4
413
414 =item * Comparison operators
415
416 Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between
417 terms (upgrading to a version object automatically).  Perl automatically
418 generates all of the other comparison operators based on those two.
419 In addition to the obvious equalities listed below, appending a single
420 trailing 0 term does not change the value of a version for comparison
421 purposes.  In other words "v1.2" and "1.2.0" will compare as identical.
422
423 For example, the following relations hold:
424
425   As Number        As String           Truth Value
426   -------------    ----------------    -----------
427   $ver >  1.0      $ver gt "1.0"       true
428   $ver <  2.5      $ver lt             true
429   $ver != 1.3      $ver ne "1.3"       true
430   $ver == 1.2      $ver eq "1.2"       false
431   $ver == 1.2.3.4  $ver eq "1.2.3.4"   see discussion below
432
433 It is probably best to chose either the numeric notation or the string
434 notation and stick with it, to reduce confusion.  Perl6 version objects
435 B<may> only support numeric comparisons.  See also L<Quoting>.
436
437 WARNING: Comparing version with unequal numbers of decimal points (whether
438 explicitly or implicitly initialized), may yield unexpected results at
439 first glance.  For example, the following inequalities hold:
440
441   version->new(0.96)     > version->new(0.95); # 0.960.0 > 0.950.0
442   version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
443
444 For this reason, it is best to use either exclusively L<Numeric Versions> or
445 L<Extended Versions> with multiple decimal points.
446
447 =back
448
449 =over 4
450
451 =item * Logical Operators 
452
453 If you need to test whether a version object
454 has been initialized, you can simply test it directly:
455
456   $vobj = version->new($something);
457   if ( $vobj )   # true only if $something was non-blank
458
459 You can also test whether a version object is an L<Alpha version>, for
460 example to prevent the use of some feature not present in the main
461 release:
462
463   $vobj = version->new("1.2_3"); # MUST QUOTE
464   ...later...
465   if ( $vobj->is_alpha )       # True
466
467 =back
468
469 =head2 Quoting
470
471 Because of the nature of the Perl parsing and tokenizing routines,
472 certain initialization values B<must> be quoted in order to correctly
473 parse as the intended version, especially when using the L<qv()> operator.
474 In all cases, a floating point number passed to version->new() will be
475 identically converted whether or not the value itself is quoted.  This is
476 not true for L<qv()>, however, when trailing zeros would be stripped on
477 an unquoted input, which would result in a very different version object.
478
479 In addition, in order to be compatible with earlier Perl version styles,
480 any use of versions of the form 5.006001 will be translated as v5.6.1.  
481 In other words, a version with a single decimal point will be parsed as
482 implicitly having three digits between subversions, but only for internal
483 comparison purposes.
484
485 The complicating factor is that in bare numbers (i.e. unquoted), the
486 underscore is a legal numeric character and is automatically stripped
487 by the Perl tokenizer before the version code is called.  However, if
488 a number containing one or more decimals and an underscore is quoted, i.e.
489 not bare, that is considered a L<Alpha Version> and the underscore is
490 significant.
491
492 If you use a mathematic formula that resolves to a floating point number,
493 you are dependent on Perl's conversion routines to yield the version you
494 expect.  You are pretty safe by dividing by a power of 10, for example,
495 but other operations are not likely to be what you intend.  For example:
496
497   $VERSION = version->new((qw$Revision: 1.4)[1]/10);
498   print $VERSION;          # yields 0.14
499   $V2 = version->new(100/9); # Integer overflow in decimal number
500   print $V2;               # yields something like 11.111.111.100
501
502 Perl 5.8.1 and beyond will be able to automatically quote v-strings but
503 that is not possible in earlier versions of Perl.  In other words:
504
505   $version = version->new("v2.5.4");  # legal in all versions of Perl
506   $newvers = version->new(v2.5.4);    # legal only in Perl >= 5.8.1
507
508 =head2 What about v-strings?
509
510 Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
511 of bytes was introduced, called v-strings.  They were intended to be an
512 easy way to enter, for example, Unicode strings (which contain two bytes
513 per character).  Some programs have used them to encode printer control
514 characters (e.g. CRLF).  They were also intended to be used for $VERSION,
515 but their use as such has been problematic from the start.
516
517 There are two ways to enter v-strings: a bare number with two or more
518 decimal points, or a bare number with one or more decimal points and a 
519 leading 'v' character (also bare).  For example:
520
521   $vs1 = 1.2.3; # encoded as \1\2\3
522   $vs2 = v1.2;  # encoded as \1\2 
523
524 However, the use of bare v-strings to initialize version objects is
525 B<strongly> discouraged in all circumstances (especially the leading 
526 'v' style), since the meaning will change depending on which Perl you 
527 are running.  It is better to directly use L<"Extended Versions"> to 
528 ensure the proper interpretation.
529
530 If you insist on using bare v-strings with Perl > 5.6.0, be aware of the 
531 following limitations:
532
533 1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses, 
534 based on some characteristics of v-strings.  You B<must> use a three part
535 version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful.
536
537 2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl
538 core to be magical, which means that the version.pm code can automatically
539 determine whether the v-string encoding was used.
540
541 =head2 Types of Versions Objects
542
543 There are two types of Version Objects:
544
545 =over 4
546
547 =item * Ordinary versions
548
549 These are the versions that normal modules will use.  Can contain as
550 many subversions as required.  In particular, those using RCS/CVS can
551 use the following:
552
553   $VERSION = version->new(qw$Revision: 2.7 $);
554
555 and the current RCS Revision for that file will be inserted
556 automatically.  If the file has been moved to a branch, the Revision
557 will have three or more elements; otherwise, it will have only two.
558 This allows you to automatically increment your module version by
559 using the Revision number from the primary file in a distribution, see
560 L<ExtUtils::MakeMaker/"VERSION_FROM">.
561
562 =item * Alpha Versions
563
564 For module authors using CPAN, the convention has been to note
565 unstable releases with an underscore in the version string, see
566 L<CPAN>.  Alpha releases will test as being newer than the more recent
567 stable release, and less than the next stable release.  For example:
568
569   $alphaver = version->new("12.03_01"); # must be quoted
570
571 obeys the relationship
572
573   12.03 < $alphaver < 12.04
574
575 Alpha versions with a single decimal point will be treated exactly as if
576 they were L<Numeric Versions>, for parsing purposes.  The stringification for
577 alpha versions with a single decimal point may seem surprising, since any
578 trailing zeros will visible.  For example, the above $alphaver will print as
579
580   12.03_0100
581
582 which is mathematically equivalent and ASCII sorts exactly the same as
583 without the trailing zeros.
584
585 Alpha versions with more than a single decimal point will be treated 
586 exactly as if they were L<Extended Versions>, and will display without any
587 trailing (or leading) zeros, in the L<Version Normal> form.  For example,
588
589   $newver = version->new("12.3.1_1");
590   print $newver; # v12.3.1_1
591
592 =back
593
594 =head2 Replacement UNIVERSAL::VERSION
595
596 In addition to the version objects, this modules also replaces the core
597 UNIVERSAL::VERSION function with one that uses version objects for its
598 comparisons.  The return from this operator is always the numified form,
599 and the warning message generated includes both the numified and normal
600 forms (for clarity).
601
602 For example:
603
604   package Foo;
605   $VERSION = 1.2;
606
607   package Bar;
608   $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
609
610   package main;
611   use version;
612
613   print $Foo::VERSION; # prints 1.2
614
615   print $Bar::VERSION; # prints 1.003005
616
617   eval "use CGI 10"; # some far future release
618   print $@; # prints "CGI version 10 (10.0.0) required..."
619
620 IMPORTANT NOTE: This may mean that code which searches for a specific
621 string (to determine whether a given module is available) may need to be
622 changed.
623
624 The replacement UNIVERSAL::VERSION, when used as a function, like this:
625
626   print $module->VERSION;
627
628 will also exclusively return the numified form.  Technically, the 
629 $module->VERSION function returns a string (PV) that can be converted to a 
630 number following the normal Perl rules, when used in a numeric context.
631
632 =head1 SUBCLASSING
633
634 This module is specifically designed and tested to be easily subclassed.
635 In practice, you only need to override the methods you want to change, but
636 you have to take some care when overriding new() (since that is where all
637 of the parsing takes place).  For example, this is a perfect acceptable
638 derived class:
639
640   package myversion;
641   use base version;
642   sub new { 
643       my($self,$n)=@_;
644       my $obj;
645       # perform any special input handling here
646       $obj = $self->SUPER::new($n);
647       # and/or add additional hash elements here
648       return $obj;
649   }
650
651 See also L<version::AlphaBeta> on CPAN for an alternate representation of
652 version strings.
653
654 B<NOTE:> Although the L<qv> operator is not a true class method, but rather a
655 function exported into the caller's namespace, a subclass of version will 
656 inherit an import() function which will perform the correct magic on behalf
657 of the subclass.
658
659 =head1 EXPORT
660
661 qv - Extended Version initialization operator
662
663 =head1 AUTHOR
664
665 John Peacock E<lt>jpeacock@cpan.orgE<gt>
666
667 =head1 SEE ALSO
668
669 L<perl>.
670
671 =cut