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;               # 12.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_030
  15   print $alphaver->is_alpha();  # true
  16
  17   $ver = qv(1.2);               # 1.2.0
  18   $ver = qv("1.2");             # 1.2.0
  19
  20   $perlver = version->new(5.005_03); # must not be quoted!
  21   print $perlver;               # 5.005030
  22
  23 =head1 DESCRIPTION
  24
  25 Overloaded version objects for all versions of Perl.  This module
  26 implements all of the features of version objects which will be part
  27 of Perl 5.10.0 except automatic version object creation.
  28
  29 =head2 What IS a version
  30
  31 For the purposes of this module, a version "number" is a sequence of
  32 positive integral values separated by decimal points and optionally a
  33 single underscore.  This corresponds to what Perl itself uses for a
  34 version, as well as extending the "version as number" that is discussed
  35 in the various editions of the Camel book.
  36
  37 There are actually two distinct ways to initialize versions:
  38
  39 =over 4
  40
  41 =item * Numeric Versions
  42
  43 Any initial parameter which "looks like a number", see L<Numeric
  44 Versions>.  This also covers versions with a single decimal place and
  45 a single embedded underscore, see L<Numeric Alpha Versions>, even though
  46 these must be quoted to preserve the underscore formatting.
  47
  48 =item * Quoted Versions
  49
  50 Any initial parameter which contains more than one decimal point
  51 and an optional embedded underscore, see L<Quoted Versions>.
  52
  53 =back
  54
  55 Both of these methods will produce similar version objects, in that
  56 the default stringification will yield the version L<Normal Form> only
  57 if required:
  58
  59   $v  = version->new(1.002);     # 1.002, but compares like 1.2.0
  60   $v  = version->new(1.002003);  # 1.002003
  61   $v2 = version->new( "1.2.3");  # v1.2.3
  62   $v3 = version->new(  1.2.3);   # v1.2.3 for Perl >= 5.8.1
  63
  64 In specific, version numbers initialized as L<Numeric Versions> will
  65 stringify in Numeric form.  Version numbers initialized as L<Quoted Versions>
  66 will be stringified as L<Normal Form>.
  67
  68 Please see L<Quoting> for more details on how Perl will parse various
  69 input values.
  70
  71 Any value passed to the new() operator will be parsed only so far as it
  72 contains a numeric, decimal, or underscore character.  So, for example:
  73
  74   $v1 = version->new("99 and 94/100 percent pure"); # $v1 == 99.0
  75   $v2 = version->new("something"); # $v2 == "" and $v2->numify == 0
  76
  77 However, see L<New Operator> for one case where non-numeric text is
  78 acceptable when initializing version objects.
  79
  80 =head2 What about v-strings?
  81
  82 Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
  83 of bytes was introduced, called v-strings.  They were intended to be an
  84 easy way to enter, for example, Unicode strings (which contain two bytes
  85 per character).  Some programs have used them to encode printer control
  86 characters (e.g. CRLF).  They were also intended to be used for $VERSION.
  87 Their use has been problematic from the start and they will be phased out
  88 beginning in Perl 5.10.0.
  89
  90 There are two ways to enter v-strings: a bare number with two or more
  91 decimal places, or a bare number with one or more decimal places and a
  92 leading 'v' character (also bare).  For example:
  93
  94   $vs1 = 1.2.3; # encoded as \1\2\3
  95   $vs2 = v1.2;  # encoded as \1\2
  96
  97 The first of those two syntaxes is destined to be the default way to create
  98 a version object in 5.10.0, whereas the second will issue a mandatory
  99 deprecation warning beginning at the same time.  In both cases, a v-string
 100 encoded version will always be stringified in the version L<Normal Form>.
 101
 102 Consequently, the use of v-strings to initialize version objects with
 103 this module is only possible with Perl 5.8.1 or better (which contain special
 104 code to enable it).  Their use is B<strongly> discouraged in all
 105 circumstances (especially the leading 'v' style), since the meaning will
 106 change depending on which Perl you are running.  It is better to use
 107 L<"Quoted Versions"> to ensure the proper interpretation.
 108
 109 =head2 Numeric Versions
 110
 111 These correspond to historical versions of Perl itself prior to 5.6.0,
 112 as well as all other modules which follow the Camel rules for the
 113 $VERSION scalar.  A numeric version is initialized with what looks like
 114 a floating point number.  Leading zeros B<are> significant and trailing
 115 zeros are implied so that a minimum of three places is maintained
 116 between subversions.  What this means is that any subversion (digits
 117 to the right of the decimal place) that contains less than three digits
 118 will have trailing zeros added to make up the difference, but only for
 119 purposes of comparison with other version objects.  For example:
 120
 121   $v = version->new(      1.2);    # prints 1.2, compares as 1.200.0
 122   $v = version->new(     1.02);    # prints 1.02, compares as 1.20.0
 123   $v = version->new(    1.002);    # prints 1.002, compares as 1.2.0
 124   $v = version->new(   1.0023);    # 1.2.300
 125   $v = version->new(  1.00203);    # 1.2.30
 126   $v = version->new( 1.002_03);    # 1.2.30   See "Quoting"
 127   $v = version->new( 1.002003);    # 1.2.3
 128
 129 All of the preceding examples except the second to last are true
 130 whether or not the input value is quoted.  The important feature is that
 131 the input value contains only a single decimal.
 132
 133 IMPORTANT NOTE: If your numeric version contains more than 3 significant
 134 digits after the decimal place, it will be split on each multiple of 3, so
 135 1.0003 becomes 1.0.300, due to the need to remain compatible with Perl's
 136 own 5.005_03 == 5.5.30 interpretation.
 137
 138 =head2 Quoted 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 requires that the input parameter be quoted, although Perl's after
 144 5.9.0 can use bare numbers with multiple decimal places as a special form
 145 of quoting.
 146
 147 Unlike L<Numeric Versions>, Quoted Versions may have more than
 148 a single decimal point, e.g. "5.6.1" (for all versions of Perl).  If a
 149 Quoted Version has only one decimal place (and no embedded underscore),
 150 it is interpreted exactly like a L<Numeric Version>.
 151
 152 So, for example:
 153
 154   $v = version->new( "1.002");    # 1.2
 155   $v = version->new( "1.2.3");    # 1.2.3
 156   $v = version->new("1.0003");    # 1.0.300
 157
 158 In addition to conventional versions, Quoted Versions can be
 159 used to create L<Alpha Versions>.
 160
 161 In general, Quoted Versions permit the greatest amount of freedom
 162 to specify a version, whereas Numeric Versions enforce a certain
 163 uniformity.  See also L<New Operator> for an additional method of
 164 initializing version objects.
 165
 166 =head2 Numeric Alpha Versions
 167
 168 The one time that a numeric version must be quoted is when a alpha form is
 169 used with an otherwise numeric version (i.e. a single decimal place).  This
 170 is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
 171 versions for automatic updating purposes.  Since some developers have used
 172 only two significant decimal places for their non-alpha releases, the
 173 version object will automatically take that into account if the initializer
 174 is quoted.  For example Module::Example was released to CPAN with the
 175 following sequence of $VERSION's:
 176
 177   # $VERSION    Stringified
 178   0.01          0.010
 179   0.02          0.020
 180   0.02_01       0.02_0100
 181   0.02_02       0.02_0200
 182   0.03          0.030
 183   etc.
 184
 185 As you can see, the version object created from the values in the first
 186 column may contain a trailing 0, but will otherwise be both mathematically
 187 equivalent and sorts alpha-numerically as would be expected.
 188
 189 =head2 Object Methods
 190
 191 Overloading has been used with version objects to provide a natural
 192 interface for their use.  All mathematical operations are forbidden,
 193 since they don't make any sense for base version objects.
 194
 195 =over 4
 196
 197 =item * New Operator
 198
 199 Like all OO interfaces, the new() operator is used to initialize
 200 version objects.  One way to increment versions when programming is to
 201 use the CVS variable $Revision, which is automatically incremented by
 202 CVS every time the file is committed to the repository.
 203
 204 In order to facilitate this feature, the following
 205 code can be employed:
 206
 207   $VERSION = version->new(qw$Revision: 2.7 $);
 208
 209 and the version object will be created as if the following code
 210 were used:
 211
 212   $VERSION = version->new("v2.7");
 213
 214 In other words, the version will be automatically parsed out of the
 215 string, and it will be quoted to preserve the meaning CVS normally
 216 carries for versions.  The CVS $Revision$ increments differently from
 217 numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
 218 it were a L<Quoted Version>.
 219
 220 A new version object can be created as a copy of an existing version
 221 object, either as a class method:
 222
 223   $v1 = version->new(12.3);
 224   $v2 = version->new($v1);
 225
 226 or as an object method:
 227
 228   $v1 = version->new(12.3);
 229   $v2 = $v1->new();
 230
 231 and in each case, $v1 and $v2 will be identical.
 232
 233 =back
 234
 235 =over 4
 236
 237 =item * qv()
 238
 239 An alternate way to create a new version object is through the exported
 240 qv() sub.  This is not strictly like other q? operators (like qq, qw),
 241 in that the only delimiters supported are parentheses (or spaces).  It is
 242 the best way to initialize a short version without triggering the floating
 243 point interpretation.  For example:
 244
 245   $v1 = qv(1.2);         # 1.2.0
 246   $v2 = qv("1.2");       # also 1.2.0
 247
 248 As you can see, either a bare number or a quoted string can be used, and
 249 either will yield the same version number.
 250
 251 =back
 252
 253 For the subsequent examples, the following three objects will be used:
 254
 255   $ver   = version->new("1.2.3.4"); # see "Quoting" below
 256   $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
 257   $nver  = version->new(1.002);       # see "Numeric Versions" above
 258
 259 =over 4
 260
 261 =item * Normal Form
 262
 263 For any version object which is initialized with multiple decimal
 264 places (either quoted or if possible v-string), or initialized using
 265 the L<qv()> operator, the stringified representation is returned in
 266 a normalized or reduced form (no extraneous zeros), and with a leading 'v':
 267
 268   print $ver->normal;         # prints as v1.2.3
 269   print $ver->stringify;      # ditto
 270   print $ver;                 # ditto
 271   print $nver->normal;        # prints as v1.2.0
 272   print $nver->stringify;     # prints as 1.002, see "Stringification"
 273
 274 In order to preserve the meaning of the processed version, the
 275 normalized representation will always contain at least three sub terms.
 276 In other words, the following is guaranteed to always be true:
 277
 278   my $newver = version->new($ver->stringify);
 279   if ($newver eq $ver ) # always true
 280     {...}
 281
 282 =back
 283
 284 =over 4
 285
 286 =item * Numification
 287
 288 Although all mathematical operations on version objects are forbidden
 289 by default, it is possible to retrieve a number which roughly
 290 corresponds to the version object through the use of the $obj->numify
 291 method.  For formatting purposes, when displaying a number which
 292 corresponds a version object, all sub versions are assumed to have
 293 three decimal places.  So for example:
 294
 295   print $ver->numify;         # prints 1.002003
 296   print $nver->numify;        # prints 1.002
 297
 298 Unlike the stringification operator, there is never any need to append
 299 trailing zeros to preserve the correct version value.
 300
 301 =back
 302
 303 =over 4
 304
 305 =item * Stringification
 306
 307 In order to mirror as much as possible the existing behavior of ordinary
 308 $VERSION scalars, the stringification operation will display differently,
 309 depending on whether the version was initialized as a L<Numeric Version>
 310 or L<Quoted Version>.
 311
 312 What this means in practice is that if the normal CPAN and Camel rules are
 313 followed ($VERSION is a floating point number with no more than 3 decimal
 314 places), the stringified output will be exactly the same as the numified
 315 output.  There will be no visible difference, although the internal
 316 representation will be different, and the L<Comparison operators> will
 317 function using the internal coding.
 318
 319 If a version object is initialized using a L<Quoted Version> form, or if
 320 the number of significant decimal places exceed three, then the stringified
 321 form will be the L<Normal Form>.  The $obj->normal operation can always be
 322 used to produce the L<Normal Form>, even if the version was originally a
 323 L<Numeric Version>.
 324
 325   print $ver->stringify;    # prints v1.2.3
 326   print $nver->stringify;   # prints 1.002
 327
 328 =back
 329
 330 =over 4
 331
 332 =item * Comparison operators
 333
 334 Both cmp and <=> operators perform the same comparison between terms
 335 (upgrading to a version object automatically).  Perl automatically
 336 generates all of the other comparison operators based on those two.
 337 In addition to the obvious equalities listed below, appending a single
 338 trailing 0 term does not change the value of a version for comparison
 339 purposes.  In other words "v1.2" and "1.2.0" will compare as identical.
 340
 341 For example, the following relations hold:
 342
 343   As Number       As String          Truth Value
 344   ---------       ------------       -----------
 345   $ver >  1.0     $ver gt "1.0"      true
 346   $ver <  2.5     $ver lt            true
 347   $ver != 1.3     $ver ne "1.3"      true
 348   $ver == 1.2     $ver eq "1.2"      false
 349   $ver == 1.2.3   $ver eq "1.2.3"    see discussion below
 350
 351 It is probably best to chose either the numeric notation or the string
 352 notation and stick with it, to reduce confusion.  Perl6 version objects
 353 B<may> only support numeric comparisons.  See also L<"Quoting">.
 354
 355 WARNING: Comparing version with unequal numbers of decimal places (whether
 356 explicitly or implicitly initialized), may yield unexpected results at
 357 first glance.  For example, the following inequalities hold:
 358
 359   version->new(0.96)     > version->new(0.95); # 0.960.0 > 0.950.0
 360   version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
 361
 362 For this reason, it is best to use either exclusively L<Numeric Versions> or
 363 L<Quoted Versions> with multiple decimal places.
 364
 365 =back
 366
 367 =over 4
 368
 369 =item * Logical Operators
 370
 371 If you need to test whether a version object
 372 has been initialized, you can simply test it directly:
 373
 374   $vobj = version->new($something);
 375   if ( $vobj )   # true only if $something was non-blank
 376
 377 You can also test whether a version object is an L<Alpha version>, for
 378 example to prevent the use of some feature not present in the main
 379 release:
 380
 381   $vobj = version->new("1.2_3"); # MUST QUOTE
 382   ...later...
 383   if ( $vobj->is_alpha )       # True
 384
 385 =back
 386
 387 =head2 Quoting
 388
 389 Because of the nature of the Perl parsing and tokenizing routines,
 390 certain initialization values B<must> be quoted in order to correctly
 391 parse as the intended version, and additionally, some initial values
 392 B<must not> be quoted to obtain the intended version.
 393
 394 Except for L<Alpha versions>, any version initialized with something
 395 that looks like a number (a single decimal place) will be parsed in
 396 the same way whether or not the term is quoted.  In order to be
 397 compatible with earlier Perl version styles, any use of versions of
 398 the form 5.006001 will be translated as 5.6.1.  In other words, a
 399 version with a single decimal place will be parsed as implicitly
 400 having three places between subversions.
 401
 402 The complicating factor is that in bare numbers (i.e. unquoted), the
 403 underscore is a legal numeric character and is automatically stripped
 404 by the Perl tokenizer before the version code is called.  However, if
 405 a number containing one or more decimals and an underscore is quoted, i.e.
 406 not bare, that is considered a L<Alpha Version> and the underscore is
 407 significant.
 408
 409 If you use a mathematic formula that resolves to a floating point number,
 410 you are dependent on Perl's conversion routines to yield the version you
 411 expect.  You are pretty safe by dividing by a power of 10, for example,
 412 but other operations are not likely to be what you intend.  For example:
 413
 414   $VERSION = version->new((qw$Revision: 1.4)[1]/10);
 415   print $VERSION;          # yields 0.14
 416   $V2 = version->new(100/9); # Integer overflow in decimal number
 417   print $V2;               # yields something like 11.111.111.100
 418
 419 Perl 5.8.1 and beyond will be able to automatically quote v-strings but
 420 that is not possible in earlier versions of Perl.  In other words:
 421
 422   $version = version->new("v2.5.4");  # legal in all versions of Perl
 423   $newvers = version->new(v2.5.4);    # legal only in Perl >= 5.8.1
 424
 425
 426 =head2 Types of Versions Objects
 427
 428 There are two types of Version Objects:
 429
 430 =over 4
 431
 432 =item * Ordinary versions
 433
 434 These are the versions that normal modules will use.  Can contain as
 435 many subversions as required.  In particular, those using RCS/CVS can
 436 use the following:
 437
 438   $VERSION = version->new(qw$Revision: 2.7 $);
 439
 440 and the current RCS Revision for that file will be inserted
 441 automatically.  If the file has been moved to a branch, the Revision
 442 will have three or more elements; otherwise, it will have only two.
 443 This allows you to automatically increment your module version by
 444 using the Revision number from the primary file in a distribution, see
 445 L<ExtUtils::MakeMaker/"VERSION_FROM">.
 446
 447 =item * Alpha Versions
 448
 449 For module authors using CPAN, the convention has been to note
 450 unstable releases with an underscore in the version string, see
 451 L<CPAN>.  Alpha releases will test as being newer than the more recent
 452 stable release, and less than the next stable release.  For example:
 453
 454   $alphaver = version->new("12.03_01"); # must be quoted
 455
 456 obeys the relationship
 457
 458   12.03 < $alphaver < 12.04
 459
 460 Alpha versions with a single decimal place will be treated exactly as if
 461 they were L<Numeric Versions>, for parsing purposes.  The stringification for
 462 alpha versions with a single decimal place may seem surprising, since any
 463 trailing zeros will visible.  For example, the above $alphaver will print as
 464
 465   12.03_0100
 466
 467 which is mathematically equivalent and ASCII sorts exactly the same as
 468 without the trailing zeros.
 469
 470 Alpha versions with more than a single decimal place will be treated
 471 exactly as if they were L<Quoted Versions>, and will display without any
 472 trailing (or leading) zeros, in the L<Version Normal> form.  For example,
 473
 474   $newver = version->new("12.3.1_1");
 475   print $newver; # v12.3.1_1
 476
 477 =head2 Replacement UNIVERSAL::VERSION
 478
 479 In addition to the version objects, this modules also replaces the core
 480 UNIVERSAL::VERSION function with one that uses version objects for its
 481 comparisons.  The return from this operator is always the numified form,
 482 and the warning message generated includes both the numified and normal
 483 forms (for clarity).
 484
 485 For example:
 486
 487   package Foo;
 488   $VERSION = 1.2;
 489
 490   package Bar;
 491   $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
 492
 493   package main;
 494   use version;
 495
 496   print $Foo::VERSION; # prints 1.2
 497
 498   print $Bar::VERSION; # prints 1.003005
 499
 500   eval "use CGI 10"; # some far future release
 501   print $@; # prints "CGI version 10 (10.0.0) required..."
 502
 503 IMPORTANT NOTE: This may mean that code which searches for a specific
 504 string (to determine whether a given module is available) may need to be
 505 changed.
 506
 507 The replacement UNIVERSAL::VERSION, when used as a function, like this:
 508
 509   print $module->VERSION;
 510
 511 will also exclusively return the numified form.  Technically, the
 512 $module->VERSION function returns a string (PV) that can be converted to a
 513 number following the normal Perl rules, when used in a numeric context.
 514
 515 =head1 SUBCLASSING
 516
 517 This module is specifically designed and tested to be easily subclassed.
 518 In practice, you only need to override the methods you want to change, but
 519 you have to take some care when overriding new() (since that is where all
 520 of the parsing takes place).  For example, this is a perfect acceptable
 521 derived class:
 522
 523   package myversion;
 524   use base version;
 525   sub new {
 526       my($self,$n)=@_;
 527       my $obj;
 528       # perform any special input handling here
 529       $obj = $self->SUPER::new($n);
 530       # and/or add additional hash elements here
 531       return $obj;
 532   }
 533
 534 See also L<version::AlphaBeta> on CPAN for an alternate representation of
 535 version strings.
 536
 537 =head1 EXPORT
 538
 539 qv - quoted version initialization operator
 540
 541 =head1 AUTHOR
 542
 543 John Peacock E<lt>jpeacock@cpan.orgE<gt>
 544
 545 =head1 SEE ALSO
 546
 547 L<perl>.
 548
 549 =cut
 550 =head1 NAME
 551
 552 version - Perl extension for Version Objects
 553
 554 =head1 SYNOPSIS
 555
 556   use version;
 557   $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
 558   print $version;               # 12.2.1
 559   print $version->numify;       # 12.002001
 560   if ( $version gt  "12.2" )    # true
 561
 562   $alphaver = version->new("1.02_03"); # must be quoted!
 563   print $alphaver;              # 1.02_030
 564   print $alphaver->is_alpha();  # true
 565
 566   $ver = qv(1.2);               # 1.2.0
 567   $ver = qv("1.2");             # 1.2.0
 568
 569   $perlver = version->new(5.005_03); # must not be quoted!
 570   print $perlver;               # 5.005030
 571
 572 =head1 DESCRIPTION
 573
 574 Overloaded version objects for all versions of Perl.  This module
 575 implements all of the features of version objects which will be part
 576 of Perl 5.10.0 except automatic version object creation.
 577
 578 =head2 What IS a version
 579
 580 For the purposes of this module, a version "number" is a sequence of
 581 positive integral values separated by decimal points and optionally a
 582 single underscore.  This corresponds to what Perl itself uses for a
 583 version, as well as extending the "version as number" that is discussed
 584 in the various editions of the Camel book.
 585
 586 There are actually two distinct ways to initialize versions:
 587
 588 =over 4
 589
 590 =item * Numeric Versions
 591
 592 Any initial parameter which "looks like a number", see L<Numeric
 593 Versions>.  This also covers versions with a single decimal place and
 594 a single embedded underscore, see L<Numeric Alpha Versions>, even though
 595 these must be quoted to preserve the underscore formatting.
 596
 597 =item * Quoted Versions
 598
 599 Any initial parameter which contains more than one decimal point
 600 and an optional embedded underscore, see L<Quoted Versions>.
 601
 602 =back
 603
 604 Both of these methods will produce similar version objects, in that
 605 the default stringification will yield the version L<Normal Form> only
 606 if required:
 607
 608   $v  = version->new(1.002);     # 1.002, but compares like 1.2.0
 609   $v  = version->new(1.002003);  # 1.002003
 610   $v2 = version->new( "1.2.3");  # v1.2.3
 611   $v3 = version->new(  1.2.3);   # v1.2.3 for Perl >= 5.8.1
 612
 613 In specific, version numbers initialized as L<Numeric Versions> will
 614 stringify in Numeric form.  Version numbers initialized as L<Quoted Versions>
 615 will be stringified as L<Normal Form>.
 616
 617 Please see L<Quoting> for more details on how Perl will parse various
 618 input values.
 619
 620 Any value passed to the new() operator will be parsed only so far as it
 621 contains a numeric, decimal, or underscore character.  So, for example:
 622
 623   $v1 = version->new("99 and 94/100 percent pure"); # $v1 == 99.0
 624   $v2 = version->new("something"); # $v2 == "" and $v2->numify == 0
 625
 626 However, see L<New Operator> for one case where non-numeric text is
 627 acceptable when initializing version objects.
 628
 629 =head2 What about v-strings?
 630
 631 Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
 632 of bytes was introduced, called v-strings.  They were intended to be an
 633 easy way to enter, for example, Unicode strings (which contain two bytes
 634 per character).  Some programs have used them to encode printer control
 635 characters (e.g. CRLF).  They were also intended to be used for $VERSION.
 636 Their use has been problematic from the start and they will be phased out
 637 beginning in Perl 5.10.0.
 638
 639 There are two ways to enter v-strings: a bare number with two or more
 640 decimal places, or a bare number with one or more decimal places and a
 641 leading 'v' character (also bare).  For example:
 642
 643   $vs1 = 1.2.3; # encoded as \1\2\3
 644   $vs2 = v1.2;  # encoded as \1\2
 645
 646 The first of those two syntaxes is destined to be the default way to create
 647 a version object in 5.10.0, whereas the second will issue a mandatory
 648 deprecation warning beginning at the same time.  In both cases, a v-string
 649 encoded version will always be stringified in the version L<Normal Form>.
 650
 651 Consequently, the use of v-strings to initialize version objects with
 652 this module is only possible with Perl 5.8.1 or better (which contain special
 653 code to enable it).  Their use is B<strongly> discouraged in all
 654 circumstances (especially the leading 'v' style), since the meaning will
 655 change depending on which Perl you are running.  It is better to use
 656 L<"Quoted Versions"> to ensure the proper interpretation.
 657
 658 =head2 Numeric Versions
 659
 660 These correspond to historical versions of Perl itself prior to 5.6.0,
 661 as well as all other modules which follow the Camel rules for the
 662 $VERSION scalar.  A numeric version is initialized with what looks like
 663 a floating point number.  Leading zeros B<are> significant and trailing
 664 zeros are implied so that a minimum of three places is maintained
 665 between subversions.  What this means is that any subversion (digits
 666 to the right of the decimal place) that contains less than three digits
 667 will have trailing zeros added to make up the difference, but only for
 668 purposes of comparison with other version objects.  For example:
 669
 670   $v = version->new(      1.2);    # prints 1.2, compares as 1.200.0
 671   $v = version->new(     1.02);    # prints 1.02, compares as 1.20.0
 672   $v = version->new(    1.002);    # prints 1.002, compares as 1.2.0
 673   $v = version->new(   1.0023);    # 1.2.300
 674   $v = version->new(  1.00203);    # 1.2.30
 675   $v = version->new( 1.002_03);    # 1.2.30   See "Quoting"
 676   $v = version->new( 1.002003);    # 1.2.3
 677
 678 All of the preceding examples except the second to last are true
 679 whether or not the input value is quoted.  The important feature is that
 680 the input value contains only a single decimal.
 681
 682 IMPORTANT NOTE: If your numeric version contains more than 3 significant
 683 digits after the decimal place, it will be split on each multiple of 3, so
 684 1.0003 becomes 1.0.300, due to the need to remain compatible with Perl's
 685 own 5.005_03 == 5.5.30 interpretation.
 686
 687 =head2 Quoted Versions
 688
 689 These are the newest form of versions, and correspond to Perl's own
 690 version style beginning with 5.6.0.  Starting with Perl 5.10.0,
 691 and most likely Perl 6, this is likely to be the preferred form.  This
 692 method requires that the input parameter be quoted, although Perl's after
 693 5.9.0 can use bare numbers with multiple decimal places as a special form
 694 of quoting.
 695
 696 Unlike L<Numeric Versions>, Quoted Versions may have more than
 697 a single decimal point, e.g. "5.6.1" (for all versions of Perl).  If a
 698 Quoted Version has only one decimal place (and no embedded underscore),
 699 it is interpreted exactly like a L<Numeric Version>.
 700
 701 So, for example:
 702
 703   $v = version->new( "1.002");    # 1.2
 704   $v = version->new( "1.2.3");    # 1.2.3
 705   $v = version->new("1.0003");    # 1.0.300
 706
 707 In addition to conventional versions, Quoted Versions can be
 708 used to create L<Alpha Versions>.
 709
 710 In general, Quoted Versions permit the greatest amount of freedom
 711 to specify a version, whereas Numeric Versions enforce a certain
 712 uniformity.  See also L<New Operator> for an additional method of
 713 initializing version objects.
 714
 715 =head2 Numeric Alpha Versions
 716
 717 The one time that a numeric version must be quoted is when a alpha form is
 718 used with an otherwise numeric version (i.e. a single decimal place).  This
 719 is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
 720 versions for automatic updating purposes.  Since some developers have used
 721 only two significant decimal places for their non-alpha releases, the
 722 version object will automatically take that into account if the initializer
 723 is quoted.  For example Module::Example was released to CPAN with the
 724 following sequence of $VERSION's:
 725
 726   # $VERSION    Stringified
 727   0.01          0.010
 728   0.02          0.020
 729   0.02_01       0.02_0100
 730   0.02_02       0.02_0200
 731   0.03          0.030
 732   etc.
 733
 734 As you can see, the version object created from the values in the first
 735 column may contain a trailing 0, but will otherwise be both mathematically
 736 equivalent and sorts alpha-numerically as would be expected.
 737
 738 =head2 Object Methods
 739
 740 Overloading has been used with version objects to provide a natural
 741 interface for their use.  All mathematical operations are forbidden,
 742 since they don't make any sense for base version objects.
 743
 744 =over 4
 745
 746 =item * New Operator
 747
 748 Like all OO interfaces, the new() operator is used to initialize
 749 version objects.  One way to increment versions when programming is to
 750 use the CVS variable $Revision, which is automatically incremented by
 751 CVS every time the file is committed to the repository.
 752
 753 In order to facilitate this feature, the following
 754 code can be employed:
 755
 756   $VERSION = version->new(qw$Revision: 2.7 $);
 757
 758 and the version object will be created as if the following code
 759 were used:
 760
 761   $VERSION = version->new("v2.7");
 762
 763 In other words, the version will be automatically parsed out of the
 764 string, and it will be quoted to preserve the meaning CVS normally
 765 carries for versions.  The CVS $Revision$ increments differently from
 766 numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
 767 it were a L<Quoted Version>.
 768
 769 A new version object can be created as a copy of an existing version
 770 object, either as a class method:
 771
 772   $v1 = version->new(12.3);
 773   $v2 = version->new($v1);
 774
 775 or as an object method:
 776
 777   $v1 = version->new(12.3);
 778   $v2 = $v1->new();
 779
 780 and in each case, $v1 and $v2 will be identical.
 781
 782 =back
 783
 784 =over 4
 785
 786 =item * qv()
 787
 788 An alternate way to create a new version object is through the exported
 789 qv() sub.  This is not strictly like other q? operators (like qq, qw),
 790 in that the only delimiters supported are parentheses (or spaces).  It is
 791 the best way to initialize a short version without triggering the floating
 792 point interpretation.  For example:
 793
 794   $v1 = qv(1.2);         # 1.2.0
 795   $v2 = qv("1.2");       # also 1.2.0
 796
 797 As you can see, either a bare number or a quoted string can be used, and
 798 either will yield the same version number.
 799
 800 =back
 801
 802 For the subsequent examples, the following three objects will be used:
 803
 804   $ver   = version->new("1.2.3.4"); # see "Quoting" below
 805   $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
 806   $nver  = version->new(1.002);       # see "Numeric Versions" above
 807
 808 =over 4
 809
 810 =item * Normal Form
 811
 812 For any version object which is initialized with multiple decimal
 813 places (either quoted or if possible v-string), or initialized using
 814 the L<qv()> operator, the stringified representation is returned in
 815 a normalized or reduced form (no extraneous zeros), and with a leading 'v':
 816
 817   print $ver->normal;         # prints as v1.2.3
 818   print $ver->stringify;      # ditto
 819   print $ver;                 # ditto
 820   print $nver->normal;        # prints as v1.2.0
 821   print $nver->stringify;     # prints as 1.002, see "Stringification"
 822
 823 In order to preserve the meaning of the processed version, the
 824 normalized representation will always contain at least three sub terms.
 825 In other words, the following is guaranteed to always be true:
 826
 827   my $newver = version->new($ver->stringify);
 828   if ($newver eq $ver ) # always true
 829     {...}
 830
 831 =back
 832
 833 =over 4
 834
 835 =item * Numification
 836
 837 Although all mathematical operations on version objects are forbidden
 838 by default, it is possible to retrieve a number which roughly
 839 corresponds to the version object through the use of the $obj->numify
 840 method.  For formatting purposes, when displaying a number which
 841 corresponds a version object, all sub versions are assumed to have
 842 three decimal places.  So for example:
 843
 844   print $ver->numify;         # prints 1.002003
 845   print $nver->numify;        # prints 1.002
 846
 847 Unlike the stringification operator, there is never any need to append
 848 trailing zeros to preserve the correct version value.
 849
 850 =back
 851
 852 =over 4
 853
 854 =item * Stringification
 855
 856 In order to mirror as much as possible the existing behavior of ordinary
 857 $VERSION scalars, the stringification operation will display differently,
 858 depending on whether the version was initialized as a L<Numeric Version>
 859 or L<Quoted Version>.
 860
 861 What this means in practice is that if the normal CPAN and Camel rules are
 862 followed ($VERSION is a floating point number with no more than 3 decimal
 863 places), the stringified output will be exactly the same as the numified
 864 output.  There will be no visible difference, although the internal
 865 representation will be different, and the L<Comparison operators> will
 866 function using the internal coding.
 867
 868 If a version object is initialized using a L<Quoted Version> form, or if
 869 the number of significant decimal places exceed three, then the stringified
 870 form will be the L<Normal Form>.  The $obj->normal operation can always be
 871 used to produce the L<Normal Form>, even if the version was originally a
 872 L<Numeric Version>.
 873
 874   print $ver->stringify;    # prints v1.2.3
 875   print $nver->stringify;   # prints 1.002
 876
 877 =back
 878
 879 =over 4
 880
 881 =item * Comparison operators
 882
 883 Both cmp and <=> operators perform the same comparison between terms
 884 (upgrading to a version object automatically).  Perl automatically
 885 generates all of the other comparison operators based on those two.
 886 In addition to the obvious equalities listed below, appending a single
 887 trailing 0 term does not change the value of a version for comparison
 888 purposes.  In other words "v1.2" and "1.2.0" will compare as identical.
 889
 890 For example, the following relations hold:
 891
 892   As Number       As String          Truth Value
 893   ---------       ------------       -----------
 894   $ver >  1.0     $ver gt "1.0"      true
 895   $ver <  2.5     $ver lt            true
 896   $ver != 1.3     $ver ne "1.3"      true
 897   $ver == 1.2     $ver eq "1.2"      false
 898   $ver == 1.2.3   $ver eq "1.2.3"    see discussion below
 899
 900 It is probably best to chose either the numeric notation or the string
 901 notation and stick with it, to reduce confusion.  Perl6 version objects
 902 B<may> only support numeric comparisons.  See also L<"Quoting">.
 903
 904 WARNING: Comparing version with unequal numbers of decimal places (whether
 905 explicitly or implicitly initialized), may yield unexpected results at
 906 first glance.  For example, the following inequalities hold:
 907
 908   version->new(0.96)     > version->new(0.95); # 0.960.0 > 0.950.0
 909   version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
 910
 911 For this reason, it is best to use either exclusively L<Numeric Versions> or
 912 L<Quoted Versions> with multiple decimal places.
 913
 914 =back
 915
 916 =over 4
 917
 918 =item * Logical Operators
 919
 920 If you need to test whether a version object
 921 has been initialized, you can simply test it directly:
 922
 923   $vobj = version->new($something);
 924   if ( $vobj )   # true only if $something was non-blank
 925
 926 You can also test whether a version object is an L<Alpha version>, for
 927 example to prevent the use of some feature not present in the main
 928 release:
 929
 930   $vobj = version->new("1.2_3"); # MUST QUOTE
 931   ...later...
 932   if ( $vobj->is_alpha )       # True
 933
 934 =back
 935
 936 =head2 Quoting
 937
 938 Because of the nature of the Perl parsing and tokenizing routines,
 939 certain initialization values B<must> be quoted in order to correctly
 940 parse as the intended version, and additionally, some initial values
 941 B<must not> be quoted to obtain the intended version.
 942
 943 Except for L<Alpha versions>, any version initialized with something
 944 that looks like a number (a single decimal place) will be parsed in
 945 the same way whether or not the term is quoted.  In order to be
 946 compatible with earlier Perl version styles, any use of versions of
 947 the form 5.006001 will be translated as 5.6.1.  In other words, a
 948 version with a single decimal place will be parsed as implicitly
 949 having three places between subversions.
 950
 951 The complicating factor is that in bare numbers (i.e. unquoted), the
 952 underscore is a legal numeric character and is automatically stripped
 953 by the Perl tokenizer before the version code is called.  However, if
 954 a number containing one or more decimals and an underscore is quoted, i.e.
 955 not bare, that is considered a L<Alpha Version> and the underscore is
 956 significant.
 957
 958 If you use a mathematic formula that resolves to a floating point number,
 959 you are dependent on Perl's conversion routines to yield the version you
 960 expect.  You are pretty safe by dividing by a power of 10, for example,
 961 but other operations are not likely to be what you intend.  For example:
 962
 963   $VERSION = version->new((qw$Revision: 1.4)[1]/10);
 964   print $VERSION;          # yields 0.14
 965   $V2 = version->new(100/9); # Integer overflow in decimal number
 966   print $V2;               # yields something like 11.111.111.100
 967
 968 Perl 5.8.1 and beyond will be able to automatically quote v-strings but
 969 that is not possible in earlier versions of Perl.  In other words:
 970
 971   $version = version->new("v2.5.4");  # legal in all versions of Perl
 972   $newvers = version->new(v2.5.4);    # legal only in Perl >= 5.8.1
 973
 974
 975 =head2 Types of Versions Objects
 976
 977 There are two types of Version Objects:
 978
 979 =over 4
 980
 981 =item * Ordinary versions
 982
 983 These are the versions that normal modules will use.  Can contain as
 984 many subversions as required.  In particular, those using RCS/CVS can
 985 use the following:
 986
 987   $VERSION = version->new(qw$Revision: 2.7 $);
 988
 989 and the current RCS Revision for that file will be inserted
 990 automatically.  If the file has been moved to a branch, the Revision
 991 will have three or more elements; otherwise, it will have only two.
 992 This allows you to automatically increment your module version by
 993 using the Revision number from the primary file in a distribution, see
 994 L<ExtUtils::MakeMaker/"VERSION_FROM">.
 995
 996 =item * Alpha Versions
 997
 998 For module authors using CPAN, the convention has been to note
 999 unstable releases with an underscore in the version string, see
1000 L<CPAN>.  Alpha releases will test as being newer than the more recent
1001 stable release, and less than the next stable release.  For example:
1002
1003   $alphaver = version->new("12.03_01"); # must be quoted
1004
1005 obeys the relationship
1006
1007   12.03 < $alphaver < 12.04
1008
1009 Alpha versions with a single decimal place will be treated exactly as if
1010 they were L<Numeric Versions>, for parsing purposes.  The stringification for
1011 alpha versions with a single decimal place may seem surprising, since any
1012 trailing zeros will visible.  For example, the above $alphaver will print as
1013
1014   12.03_0100
1015
1016 which is mathematically equivalent and ASCII sorts exactly the same as
1017 without the trailing zeros.
1018
1019 Alpha versions with more than a single decimal place will be treated
1020 exactly as if they were L<Quoted Versions>, and will display without any
1021 trailing (or leading) zeros, in the L<Version Normal> form.  For example,
1022
1023   $newver = version->new("12.3.1_1");
1024   print $newver; # v12.3.1_1
1025
1026 =head2 Replacement UNIVERSAL::VERSION
1027
1028 In addition to the version objects, this modules also replaces the core
1029 UNIVERSAL::VERSION function with one that uses version objects for its
1030 comparisons.  The return from this operator is always the numified form,
1031 and the warning message generated includes both the numified and normal
1032 forms (for clarity).
1033
1034 For example:
1035
1036   package Foo;
1037   $VERSION = 1.2;
1038
1039   package Bar;
1040   $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
1041
1042   package main;
1043   use version;
1044
1045   print $Foo::VERSION; # prints 1.2
1046
1047   print $Bar::VERSION; # prints 1.003005
1048
1049   eval "use CGI 10"; # some far future release
1050   print $@; # prints "CGI version 10 (10.0.0) required..."
1051
1052 IMPORTANT NOTE: This may mean that code which searches for a specific
1053 string (to determine whether a given module is available) may need to be
1054 changed.
1055
1056 The replacement UNIVERSAL::VERSION, when used as a function, like this:
1057
1058   print $module->VERSION;
1059
1060 will also exclusively return the numified form.  Technically, the
1061 $module->VERSION function returns a string (PV) that can be converted to a
1062 number following the normal Perl rules, when used in a numeric context.
1063
1064 =head1 SUBCLASSING
1065
1066 This module is specifically designed and tested to be easily subclassed.
1067 In practice, you only need to override the methods you want to change, but
1068 you have to take some care when overriding new() (since that is where all
1069 of the parsing takes place).  For example, this is a perfect acceptable
1070 derived class:
1071
1072   package myversion;
1073   use base version;
1074   sub new {
1075       my($self,$n)=@_;
1076       my $obj;
1077       # perform any special input handling here
1078       $obj = $self->SUPER::new($n);
1079       # and/or add additional hash elements here
1080       return $obj;
1081   }
1082
1083 See also L<version::AlphaBeta> on CPAN for an alternate representation of
1084 version strings.
1085
1086 =head1 EXPORT
1087
1088 qv - quoted version initialization operator
1089
1090 =head1 AUTHOR
1091
1092 John Peacock E<lt>jpeacock@cpan.orgE<gt>
1093
1094 =head1 SEE ALSO
1095
1096 L<perl>.
1097
1098 =cut