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