lib/version.pm

   1 #!perl -w
   2 package version;
   3
   4 use 5.005_03;
   5 use strict;
   6
   7 require Exporter;
   8 require DynaLoader;
   9 use vars qw(@ISA $VERSION $CLASS @EXPORT);
  10
  11 @ISA = qw(Exporter DynaLoader);
  12
  13 @EXPORT = qw(qv);
  14
  15 $VERSION = "0.44";
  16
  17 $CLASS = 'version';
  18
  19 local $^W; # shut up the 'redefined' warning for UNIVERSAL::VERSION
  20 bootstrap version if $] < 5.009;
  21
  22 # Preloaded methods go here.
  23
  24 1;
  25 __END__
  26
  27 =head1 NAME
  28
  29 version - Perl extension for Version Objects
  30
  31 =head1 SYNOPSIS
  32
  33   use version;
  34   $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
  35   print $version;               # 12.2.1
  36   print $version->numify;       # 12.002001
  37   if ( $version gt  "12.2" )    # true
  38
  39   $alphaver = version->new("1.02_03"); # must be quoted!
  40   print $alphaver;              # 1.02_030
  41   print $alphaver->is_alpha();  # true
  42
  43   $ver = qv(1.2);               # 1.2.0
  44   $ver = qv("1.2");             # 1.2.0
  45
  46   $perlver = version->new(5.005_03); # must not be quoted!
  47   print $perlver;               # 5.005030
  48
  49 =head1 DESCRIPTION
  50
  51 Overloaded version objects for all versions of Perl.  This module
  52 implements all of the features of version objects which will be part
  53 of Perl 5.10.0 except automatic version object creation.
  54
  55 =head2 What IS a version
  56
  57 For the purposes of this module, a version "number" is a sequence of
  58 positive integral values separated by decimal points and optionally a
  59 single underscore.  This corresponds to what Perl itself uses for a
  60 version, as well as extending the "version as number" that is discussed
  61 in the various editions of the Camel book.
  62
  63 There are actually two distinct ways to initialize versions:
  64
  65 =over 4
  66
  67 =item * Numeric Versions
  68
  69 Any initial parameter which "looks like a number", see L<Numeric
  70 Versions>.  This also covers versions with a single decimal place and
  71 a single embedded underscore, see L<Numeric Alpha Versions>, even though
  72 these must be quoted to preserve the underscore formatting.
  73
  74 =item * Quoted Versions
  75
  76 Any initial parameter which contains more than one decimal point
  77 and an optional embedded underscore, see L<Quoted Versions>.
  78
  79 =back
  80
  81 Both of these methods will produce similar version objects, in that
  82 the default stringification will yield the version L<Normal Form> only
  83 if required:
  84
  85   $v  = version->new(1.002);     # 1.002, but compares like 1.2.0
  86   $v  = version->new(1.002003);  # 1.002003
  87   $v2 = version->new( "1.2.3");  # v1.2.3
  88   $v3 = version->new(  1.2.3);   # v1.2.3 for Perl >= 5.8.1
  89
  90 In specific, version numbers initialized as L<Numeric Versions> will
  91 stringify in Numeric form.  Version numbers initialized as L<Quoted Versions>
  92 will be stringified as L<Normal Form>.
  93
  94 Please see L<Quoting> for more details on how Perl will parse various
  95 input values.
  96
  97 Any value passed to the new() operator will be parsed only so far as it
  98 contains a numeric, decimal, or underscore character.  So, for example:
  99
 100   $v1 = version->new("99 and 94/100 percent pure"); # $v1 == 99.0
 101   $v2 = version->new("something"); # $v2 == "" and $v2->numify == 0
 102
 103 However, see L<New Operator> for one case where non-numeric text is
 104 acceptable when initializing version objects.
 105
 106 =head2 What about v-strings?
 107
 108 Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
 109 of bytes was introduced, called v-strings.  They were intended to be an
 110 easy way to enter, for example, Unicode strings (which contain two bytes
 111 per character).  Some programs have used them to encode printer control
 112 characters (e.g. CRLF).  They were also intended to be used for $VERSION.
 113 Their use has been problematic from the start and they will be phased out
 114 beginning in Perl 5.10.0.
 115
 116 There are two ways to enter v-strings: a bare number with two or more
 117 decimal places, or a bare number with one or more decimal places and a
 118 leading 'v' character (also bare).  For example:
 119
 120   $vs1 = 1.2.3; # encoded as \1\2\3
 121   $vs2 = v1.2;  # encoded as \1\2
 122
 123 The first of those two syntaxes is destined to be the default way to create
 124 a version object in 5.10.0, whereas the second will issue a mandatory
 125 deprecation warning beginning at the same time.  In both cases, a v-string
 126 encoded version will always be stringified in the version L<Normal Form>.
 127
 128 Consequently, the use of v-strings to initialize version objects with
 129 this module is only possible with Perl 5.8.1 or better (which contain special
 130 code to enable it).  Their use is B<strongly> discouraged in all
 131 circumstances (especially the leading 'v' style), since the meaning will
 132 change depending on which Perl you are running.  It is better to use
 133 L<"Quoted Versions"> to ensure the proper interpretation.
 134
 135 =head2 Numeric Versions
 136
 137 These correspond to historical versions of Perl itself prior to 5.6.0,
 138 as well as all other modules which follow the Camel rules for the
 139 $VERSION scalar.  A numeric version is initialized with what looks like
 140 a floating point number.  Leading zeros B<are> significant and trailing
 141 zeros are implied so that a minimum of three places is maintained
 142 between subversions.  What this means is that any subversion (digits
 143 to the right of the decimal place) that contains less than three digits
 144 will have trailing zeros added to make up the difference, but only for
 145 purposes of comparison with other version objects.  For example:
 146
 147   $v = version->new(      1.2);    # prints 1.2, compares as 1.200.0
 148   $v = version->new(     1.02);    # prints 1.02, compares as 1.20.0
 149   $v = version->new(    1.002);    # prints 1.002, compares as 1.2.0
 150   $v = version->new(   1.0023);    # 1.2.300
 151   $v = version->new(  1.00203);    # 1.2.30
 152   $v = version->new( 1.002_03);    # 1.2.30   See "Quoting"
 153   $v = version->new( 1.002003);    # 1.2.3
 154
 155 All of the preceeding examples except the second to last are true
 156 whether or not the input value is quoted.  The important feature is that
 157 the input value contains only a single decimal.
 158
 159 IMPORTANT NOTE: If your numeric version contains more than 3 significant
 160 digits after the decimal place, it will be split on each multiple of 3, so
 161 1.0003 becomes 1.0.300, due to the need to remain compatible with Perl's
 162 own 5.005_03 == 5.5.30 interpretation.
 163
 164 =head2 Quoted Versions
 165
 166 These are the newest form of versions, and correspond to Perl's own
 167 version style beginning with 5.6.0.  Starting with Perl 5.10.0,
 168 and most likely Perl 6, this is likely to be the preferred form.  This
 169 method requires that the input parameter be quoted, although Perl's after
 170 5.9.0 can use bare numbers with multiple decimal places as a special form
 171 of quoting.
 172
 173 Unlike L<Numeric Versions>, Quoted Versions may have more than
 174 a single decimal point, e.g. "5.6.1" (for all versions of Perl).  If a
 175 Quoted Version has only one decimal place (and no embedded underscore),
 176 it is interpreted exactly like a L<Numeric Version>.
 177
 178 So, for example:
 179
 180   $v = version->new( "1.002");    # 1.2
 181   $v = version->new( "1.2.3");    # 1.2.3
 182   $v = version->new("1.0003");    # 1.0.300
 183
 184 In addition to conventional versions, Quoted Versions can be
 185 used to create L<Alpha Versions>.
 186
 187 In general, Quoted Versions permit the greatest amount of freedom
 188 to specify a version, whereas Numeric Versions enforce a certain
 189 uniformity.  See also L<New Operator> for an additional method of
 190 initializing version objects.
 191
 192 =head2 Numeric Alpha Versions
 193
 194 The one time that a numeric version must be quoted is when a alpha form is
 195 used with an otherwise numeric version (i.e. a single decimal place).  This
 196 is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
 197 versions for automatic updating purposes.  Since some developers have used
 198 only two significant decimal places for their non-alpha releases, the
 199 version object will automatically take that into account if the initializer
 200 is quoted.  For example Module::Example was released to CPAN with the
 201 following sequence of $VERSION's:
 202
 203   # $VERSION    Stringified
 204   0.01          0.010
 205   0.02          0.020
 206   0.02_01       0.02_0100
 207   0.02_02       0.02_0200
 208   0.03          0.030
 209   etc.
 210
 211 As you can see, the version object created from the values in the first
 212 column may contain a trailing 0, but will otherwise be both mathematically
 213 equivalent and sorts alpha-numerically as would be expected.
 214
 215 =head2 Object Methods
 216
 217 Overloading has been used with version objects to provide a natural
 218 interface for their use.  All mathematical operations are forbidden,
 219 since they don't make any sense for base version objects.
 220
 221 =over 4
 222
 223 =item * New Operator
 224
 225 Like all OO interfaces, the new() operator is used to initialize
 226 version objects.  One way to increment versions when programming is to
 227 use the CVS variable $Revision, which is automatically incremented by
 228 CVS every time the file is committed to the repository.
 229
 230 In order to facilitate this feature, the following
 231 code can be employed:
 232
 233   $VERSION = version->new(qw$Revision: 2.7 $);
 234
 235 and the version object will be created as if the following code
 236 were used:
 237
 238   $VERSION = version->new("v2.7");
 239
 240 In other words, the version will be automatically parsed out of the
 241 string, and it will be quoted to preserve the meaning CVS normally
 242 carries for versions.  The CVS $Revision$ increments differently from
 243 numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
 244 it were a L<Quoted Version>.
 245
 246 A new version object can be created as a copy of an existing version
 247 object, either as a class method:
 248
 249   $v1 = version->new(12.3);
 250   $v2 = version->new($v1);
 251
 252 or as an object method:
 253
 254   $v1 = version->new(12.3);
 255   $v2 = $v1->new();
 256
 257 and in each case, $v1 and $v2 will be identical.
 258
 259 =back
 260
 261 =over 4
 262
 263 =item * qv()
 264
 265 An alternate way to create a new version object is through the exported
 266 qv() sub.  This is not strictly like other q? operators (like qq, qw),
 267 in that the only delimiters supported are parentheses (or spaces).  It is
 268 the best way to initialize a short version without triggering the floating
 269 point interpretation.  For example:
 270
 271   $v1 = qv(1.2);         # 1.2.0
 272   $v2 = qv("1.2");       # also 1.2.0
 273
 274 As you can see, either a bare number or a quoted string can be used, and
 275 either will yield the same version number.
 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
 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 roughly
 316 corresponds 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.002003
 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<Quoted 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 places), 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<Quoted Version> form, or if
 346 the number of significant decimal places exceed three, then the stringified
 347 form will be the L<Normal Form>.  The $obj->normal operation can always be
 348 used to produce the L<Normal Form>, even if the version was originally a
 349 L<Numeric Version>.
 350
 351   print $ver->stringify;    # prints v1.2.3
 352   print $nver->stringify;   # prints 1.002
 353
 354 =back
 355
 356 =over 4
 357
 358 =item * Comparison operators
 359
 360 Both cmp and <=> operators perform the same comparison between terms
 361 (upgrading to a version object automatically).  Perl automatically
 362 generates all of the other comparison operators based on those two.
 363 In addition to the obvious equalities listed below, appending a single
 364 trailing 0 term does not change the value of a version for comparison
 365 purposes.  In other words "v1.2" and "1.2.0" will compare as identical.
 366
 367 For example, the following relations hold:
 368
 369   As Number       As String          Truth Value
 370   ---------       ------------       -----------
 371   $ver >  1.0     $ver gt "1.0"      true
 372   $ver <  2.5     $ver lt            true
 373   $ver != 1.3     $ver ne "1.3"      true
 374   $ver == 1.2     $ver eq "1.2"      false
 375   $ver == 1.2.3   $ver eq "1.2.3"    see discussion below
 376
 377 It is probably best to chose either the numeric notation or the string
 378 notation and stick with it, to reduce confusion.  Perl6 version objects
 379 B<may> only support numeric comparisons.  See also L<"Quoting">.
 380
 381 WARNING: Comparing version with unequal numbers of decimal places (whether
 382 explicitely or implicitely initialized), may yield unexpected results at
 383 first glance.  For example, the following inequalities hold:
 384
 385   version->new(0.96)     > version->new(0.95); # 0.960.0 > 0.950.0
 386   version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
 387
 388 For this reason, it is best to use either exclusively L<Numeric Versions> or
 389 L<Quoted Versions> with multiple decimal places.
 390
 391 =back
 392
 393 =over 4
 394
 395 =item * Logical Operators
 396
 397 If you need to test whether a version object
 398 has been initialized, you can simply test it directly:
 399
 400   $vobj = version->new($something);
 401   if ( $vobj )   # true only if $something was non-blank
 402
 403 You can also test whether a version object is an L<Alpha version>, for
 404 example to prevent the use of some feature not present in the main
 405 release:
 406
 407   $vobj = version->new("1.2_3"); # MUST QUOTE
 408   ...later...
 409   if ( $vobj->is_alpha )       # True
 410
 411 =back
 412
 413 =head2 Quoting
 414
 415 Because of the nature of the Perl parsing and tokenizing routines,
 416 certain initialization values B<must> be quoted in order to correctly
 417 parse as the intended version, and additionally, some initial values
 418 B<must not> be quoted to obtain the intended version.
 419
 420 Except for L<Alpha versions>, any version initialized with something
 421 that looks like a number (a single decimal place) will be parsed in
 422 the same way whether or not the term is quoted.  In order to be
 423 compatible with earlier Perl version styles, any use of versions of
 424 the form 5.006001 will be translated as 5.6.1.  In other words, a
 425 version with a single decimal place will be parsed as implicitly
 426 having three places between subversions.
 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
 452 =head2 Types of Versions Objects
 453
 454 There are two types of Version Objects:
 455
 456 =over 4
 457
 458 =item * Ordinary versions
 459
 460 These are the versions that normal modules will use.  Can contain as
 461 many subversions as required.  In particular, those using RCS/CVS can
 462 use the following:
 463
 464   $VERSION = version->new(qw$Revision: 2.7 $);
 465
 466 and the current RCS Revision for that file will be inserted
 467 automatically.  If the file has been moved to a branch, the Revision
 468 will have three or more elements; otherwise, it will have only two.
 469 This allows you to automatically increment your module version by
 470 using the Revision number from the primary file in a distribution, see
 471 L<ExtUtils::MakeMaker/"VERSION_FROM">.
 472
 473 =item * Alpha Versions
 474
 475 For module authors using CPAN, the convention has been to note
 476 unstable releases with an underscore in the version string, see
 477 L<CPAN>.  Alpha releases will test as being newer than the more recent
 478 stable release, and less than the next stable release.  For example:
 479
 480   $alphaver = version->new("12.03_01"); # must be quoted
 481
 482 obeys the relationship
 483
 484   12.03 < $alphaver < 12.04
 485
 486 Alpha versions with a single decimal place will be treated exactly as if
 487 they were L<Numeric Versions>, for parsing purposes.  The stringification for
 488 alpha versions with a single decimal place may seem suprising, since any
 489 trailing zeros will visible.  For example, the above $alphaver will print as
 490
 491   12.03_0100
 492
 493 which is mathematically equivalent and ASCII sorts exactly the same as
 494 without the trailing zeros.
 495
 496 Alpha versions with more than a single decimal place will be treated
 497 exactly as if they were L<Quoted Versions>, and will display without any
 498 trailing (or leading) zeros, in the L<Version Normal> form.  For example,
 499
 500   $newver = version->new("12.3.1_1");
 501   print $newver; # v12.3.1_1
 502
 503 =head2 Replacement UNIVERSAL::VERSION
 504
 505 In addition to the version objects, this modules also replaces the core
 506 UNIVERSAL::VERSION function with one that uses version objects for its
 507 comparisons.  The return from this operator is always the numified form,
 508 and the warning message generated includes both the numified and normal
 509 forms (for clarity).
 510
 511 For example:
 512
 513   package Foo;
 514   $VERSION = 1.2;
 515
 516   package Bar;
 517   $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
 518
 519   package main;
 520   use version;
 521
 522   print $Foo::VERSION; # prints 1.2
 523
 524   print $Bar::VERSION; # prints 1.003005
 525
 526   eval "use CGI 10"; # some far future release
 527   print $@; # prints "CGI version 10 (10.0.0) required..."
 528
 529 IMPORTANT NOTE: This may mean that code which searches for a specific
 530 string (to determine whether a given module is available) may need to be
 531 changed.
 532
 533 The replacement UNIVERSAL::VERSION, when used as a function, like this:
 534
 535   print $module->VERSION;
 536
 537 will also exclusively return the numified form.  Technically, the
 538 $module->VERSION function returns a string (PV) that can be converted to a
 539 number following the normal Perl rules, when used in a numeric context.
 540
 541 =head1 EXPORT
 542
 543 qv - quoted version initialization operator
 544
 545 =head1 AUTHOR
 546
 547 John Peacock E<lt>jpeacock@cpan.orgE<gt>
 548
 549 =head1 SEE ALSO
 550
 551 L<perl>.
 552
 553 =cut