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