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.37; # stop using CVS and switch to subversion
  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.2_3"); # must be quoted!
  40   print $alphaver;              # 1.2_3
  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.5.30
  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>.
  71
  72 =item * Quoted Versions
  73
  74 Any initial parameter which contains more than one decimal point
  75 or contains an embedded underscore, see L<Quoted Versions>.  The
  76 most recent development version of Perl (5.9.x) and the next major
  77 release (5.10.0) will automatically create version objects for bare
  78 numbers containing more than one decimal point in the appropriate
  79 context.
  80
  81 =back
  82
  83 Both of these methods will produce similar version objects, in that
  84 the default stringification will yield the version L<Normal Form> only
  85 if required:
  86
  87   $v  = version->new(1.002);     # 1.002, but compares like 1.2.0
  88   $v  = version->new(1.002003);  # 1.2.3
  89   $v2 = version->new( "1.2.3");  # 1.2.3
  90   $v3 = version->new(  1.2.3);   # 1.2.3 for Perl >= 5.8.1
  91
  92 Please see L<"Quoting"> for more details on how Perl will parse various
  93 input values.
  94
  95 Any value passed to the new() operator will be parsed only so far as it
  96 contains a numeric, decimal, or underscore character.  So, for example:
  97
  98   $v1 = version->new("99 and 94/100 percent pure"); # $v1 == 99.0
  99   $v2 = version->new("something"); # $v2 == "" and $v2->numify == 0
 100
 101 However, see L<New Operator> for one case where non-numeric text is
 102 acceptable when initializing version objects.
 103
 104 =head2 What about v-strings?
 105
 106 Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
 107 of bytes was introduced, called v-strings.  They were intended to be an
 108 easy way to enter, for example, Unicode strings (which contain two bytes
 109 per character).  Some programs have used them to encode printer control
 110 characters (e.g. CRLF).  They were also intended to be used for $VERSION.
 111 Their use has been problematic from the start and they will be phased out
 112 beginning in Perl 5.10.0.
 113
 114 There are two ways to enter v-strings: a bare number with two or more
 115 decimal places, or a bare number with one or more decimal places and a
 116 leading 'v' character (also bare).  For example:
 117
 118   $vs1 = 1.2.3; # encoded as \1\2\3
 119   $vs2 = v1.2;  # encoded as \1\2
 120
 121 The first of those two syntaxes is destined to be the default way to create
 122 a version object in 5.10.0, whereas the second will issue a mandatory
 123 deprecation warning beginning at the same time.  In both cases, a v-string
 124 encoded version will always be stringified in the version L<Normal Form>.
 125
 126 Consequently, the use of v-strings to initialize version objects with
 127 this module is only possible with Perl 5.8.1 or better (which contain special
 128 code to enable it).  Their use is B<strongly> discouraged in all
 129 circumstances (especially the leading 'v' style), since the meaning will
 130 change depending on which Perl you are running.  It is better to use
 131 L<"Quoted Versions"> to ensure the proper interpretation.
 132
 133 =head2 Numeric Versions
 134
 135 These correspond to historical versions of Perl itself prior to 5.6.0,
 136 as well as all other modules which follow the Camel rules for the
 137 $VERSION scalar.  A numeric version is initialized with what looks like
 138 a floating point number.  Leading zeros B<are> significant and trailing
 139 zeros are implied so that a minimum of three places is maintained
 140 between subversions.  What this means is that any subversion (digits
 141 to the right of the decimal place) that contains less than three digits
 142 will have trailing zeros added to make up the difference, but only for
 143 purposes of comparison with other version objects.  For example:
 144
 145   $v = version->new(      1.2);    # prints 1.2, compares as 1.200.0
 146   $v = version->new(     1.02);    # prints 1.02, compares as 1.20.0
 147   $v = version->new(    1.002);    # prints 1.002, compares as 1.2.0
 148   $v = version->new(   1.0023);    # 1.2.300
 149   $v = version->new(  1.00203);    # 1.2.30
 150   $v = version->new( 1.002_03);    # 1.2.30   See "Quoting"
 151   $v = version->new( 1.002003);    # 1.2.3
 152
 153 All of the preceeding examples except the second to last are true
 154 whether or not the input value is quoted.  The important feature is that
 155 the input value contains only a single decimal.
 156
 157 IMPORTANT NOTE: If your numeric version contains more than 3 significant
 158 digits after the decimal place, it will be split on each multiple of 3, so
 159 1.0003 becomes 1.0.300, due to the need to remain compatible with Perl's
 160 own 5.005_03 == 5.5.30 interpretation.
 161
 162 =head2 Quoted Versions
 163
 164 These are the newest form of versions, and correspond to Perl's own
 165 version style beginning with 5.6.0.  Starting with Perl 5.10.0,
 166 and most likely Perl 6, this is likely to be the preferred form.  This
 167 method requires that the input parameter be quoted, although Perl's after
 168 5.9.0 can use bare numbers with multiple decimal places as a special form
 169 of quoting.
 170
 171 Unlike L<Numeric Versions>, Quoted Versions may have more than
 172 a single decimal point, e.g. "5.6.1" (for all versions of Perl).  If a
 173 Quoted Version has only one decimal place (and no embedded underscore),
 174 it is interpreted exactly like a L<Numeric Version>.
 175
 176 So, for example:
 177
 178   $v = version->new( "1.002");    # 1.2
 179   $v = version->new( "1.2.3");    # 1.2.3
 180   $v = version->new("1.0003");    # 1.0.300
 181
 182 In addition to conventional versions, Quoted Versions can be
 183 used to create L<Alpha Versions>.
 184
 185 In general, Quoted Versions permit the greatest amount of freedom
 186 to specify a version, whereas Numeric Versions enforce a certain
 187 uniformity.  See also L<New Operator> for an additional method of
 188 initializing version objects.
 189
 190 =head2 Object Methods
 191
 192 Overloading has been used with version objects to provide a natural
 193 interface for their use.  All mathematical operations are forbidden,
 194 since they don't make any sense for base version objects.
 195
 196 =over 4
 197
 198 =item * New Operator
 199
 200 Like all OO interfaces, the new() operator is used to initialize
 201 version objects.  One way to increment versions when programming is to
 202 use the CVS variable $Revision, which is automatically incremented by
 203 CVS every time the file is committed to the repository.
 204
 205 In order to facilitate this feature, the following
 206 code can be employed:
 207
 208   $VERSION = version->new(qw$Revision: 2.7 $);
 209
 210 and the version object will be created as if the following code
 211 were used:
 212
 213   $VERSION = version->new("v2.7");
 214
 215 In other words, the version will be automatically parsed out of the
 216 string, and it will be quoted to preserve the meaning CVS normally
 217 carries for versions.
 218
 219 =back
 220
 221 =over 4
 222
 223 =item * qv()
 224
 225 An alternate way to create a new version object is through the exported
 226 qv() sub.  This is not strictly like other q? operators (like qq, qw),
 227 in that the only delimiters supported are parentheses (or spaces).  It is
 228 the best way to initialize a short version without triggering the floating
 229 point interpretation.  For example:
 230
 231   $v1 = qv(1.2);         # 1.2.0
 232   $v2 = qv("1.2");       # also 1.2.0
 233
 234 As you can see, either a bare number or a quoted string can be used, and
 235 either will yield the same version number.
 236
 237 =back
 238
 239 For the subsequent examples, the following two objects will be used:
 240
 241   $ver   = version->new("1.2.3"); # see "Quoting" below
 242   $alpha = version->new("1.2_3"); # see "Alpha versions" below
 243   $nver  = version->new(1.2);     # see "Numeric Versions" above
 244
 245 =over 4
 246
 247 =item * Normal Form
 248
 249 For any version object which is initialized with multiple decimal
 250 places (either quoted or if possible v-string), or initialized using
 251 the L<qv()> operator, the stringified representation is returned in
 252 a normalized or reduced form (no extraneous zeros):
 253
 254   print $ver->normal;         # prints as 1.2.3
 255   print $ver->stringify;      # ditto
 256   print $ver;                 # ditto
 257   print $nver->normal;        # prints as 1.2.0
 258   print $nver->stringify;     # prints as 1.2, see "Stringification"
 259
 260 In order to preserve the meaning of the processed version, the
 261 normalized representation will always contain at least three sub terms.
 262 In other words, the following is guaranteed to always be true:
 263
 264   my $newver = version->new($ver->stringify);
 265   if ($newver eq $ver ) # always true
 266     {...}
 267
 268 =back
 269
 270 =over 4
 271
 272 =item * Numification
 273
 274 Although all mathematical operations on version objects are forbidden
 275 by default, it is possible to retrieve a number which roughly
 276 corresponds to the version object through the use of the $obj->numify
 277 method.  For formatting purposes, when displaying a number which
 278 corresponds a version object, all sub versions are assumed to have
 279 three decimal places.  So for example:
 280
 281   print $ver->numify;         # prints 1.002003
 282   print $nver->numify;        # prints 1.2
 283
 284 Unlike the stringification operator, there is never any need to append
 285 trailing zeros to preserve the correct version value.
 286
 287 =back
 288
 289 =over 4
 290
 291 =item * Stringification
 292
 293 In order to mirror as much as possible the existing behavior of ordinary
 294 $VERSION scalars, the stringification operation will display differently,
 295 depending on whether the version was initialized as a L<Numeric Version>
 296 or L<Quoted Version>.
 297
 298 What this means in practice is that if the normal CPAN and Camel rules are
 299 followed ($VERSION is a floating point number with no more than 3 decimal
 300 places), the stringified output will be exactly the same as the numified
 301 output.  There will be no visible difference, although the internal
 302 representation will be different, and the L<Comparison operators> will
 303 function using the internal coding.
 304
 305 If a version object is initialized using a L<Quoted Version> form, or if
 306 the number of significant decimal places exceed three, then the stringified
 307 form will be the L<Normal Form>.  The $obj->normal operation can always be
 308 used to produce the L<Normal Form>, even if the version was originally a
 309 L<Numeric Version>.
 310
 311   print $ver->stringify;    # prints 1.2.3
 312   print $nver->stringify;   # prints 1.2
 313
 314 =back
 315
 316 =over 4
 317
 318 =item * Comparison operators
 319
 320 Both cmp and <=> operators perform the same comparison between terms
 321 (upgrading to a version object automatically).  Perl automatically
 322 generates all of the other comparison operators based on those two.
 323 In addition to the obvious equalities listed below, appending a single
 324 trailing 0 term does not change the value of a version for comparison
 325 purposes.  In other words "v1.2" and "1.2.0" will compare as identical.
 326
 327 For example, the following relations hold:
 328
 329   As Number       As String          Truth Value
 330   ---------       ------------       -----------
 331   $ver >  1.0     $ver gt "1.0"      true
 332   $ver <  2.5     $ver lt            true
 333   $ver != 1.3     $ver ne "1.3"      true
 334   $ver == 1.2     $ver eq "1.2"      false
 335   $ver == 1.2.3   $ver eq "1.2.3"    see discussion below
 336
 337 It is probably best to chose either the numeric notation or the string
 338 notation and stick with it, to reduce confusion.  Perl6 version objects
 339 B<may> only support numeric comparisons.  See also L<"Quoting">.
 340
 341 WARNING: Comparing version with unequal numbers of decimal places (whether
 342 explicitely or implicitely initialized), may yield unexpected results at
 343 first glance.  For example, the following inequalities hold:
 344
 345   version->new(0.96)     > version->new(0.95); # 0.960.0 > 0.950.0
 346   version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
 347
 348 For this reason, it is best to use either exclusively L<Numeric Versions> or
 349 L<Quoted Versions> with multiple decimal places.
 350
 351 =back
 352
 353 =over 4
 354
 355 =item * Logical Operators
 356
 357 If you need to test whether a version object
 358 has been initialized, you can simply test it directly:
 359
 360   $vobj = version->new($something);
 361   if ( $vobj )   # true only if $something was non-blank
 362
 363 You can also test whether a version object is an L<Alpha version>, for
 364 example to prevent the use of some feature not present in the main
 365 release:
 366
 367   $vobj = version->new("1.2_3"); # MUST QUOTE
 368   ...later...
 369   if ( $vobj->is_alpha )       # True
 370
 371 =back
 372
 373 =head2 Quoting
 374
 375 Because of the nature of the Perl parsing and tokenizing routines,
 376 certain initialization values B<must> be quoted in order to correctly
 377 parse as the intended version, and additionally, some initial values
 378 B<must not> be quoted to obtain the intended version.
 379
 380 Except for L<Alpha versions>, any version initialized with something
 381 that looks like a number (a single decimal place) will be parsed in
 382 the same way whether or not the term is quoted.  In order to be
 383 compatible with earlier Perl version styles, any use of versions of
 384 the form 5.006001 will be translated as 5.6.1.  In other words, a
 385 version with a single decimal place will be parsed as implicitly
 386 having three places between subversions.
 387
 388 The complicating factor is that in bare numbers (i.e. unquoted), the
 389 underscore is a legal numeric character and is automatically stripped
 390 by the Perl tokenizer before the version code is called.  However, if
 391 a number containing a single decimal and an underscore is quoted, i.e.
 392 not bare, that is considered a L<Alpha Version> and the underscore is
 393 significant.
 394
 395 If you use a mathematic formula that resolves to a floating point number,
 396 you are dependent on Perl's conversion routines to yield the version you
 397 expect.  You are pretty safe by dividing by a power of 10, for example,
 398 but other operations are not likely to be what you intend.  For example:
 399
 400   $VERSION = version->new((qw$Revision: 1.4)[1]/10);
 401   print $VERSION;          # yields 0.14
 402   $V2 = version->new(100/9); # Integer overflow in decimal number
 403   print $V2;               # yields something like 11.111.111.100
 404
 405 Perl 5.8.1 and beyond will be able to automatically quote v-strings
 406 (although a warning may be issued under 5.9.x and 5.10.0), but that
 407 is not possible in earlier versions of Perl.  In other words:
 408
 409   $version = version->new("v2.5.4");  # legal in all versions of Perl
 410   $newvers = version->new(v2.5.4);    # legal only in Perl >= 5.8.1
 411
 412
 413 =head2 Types of Versions Objects
 414
 415 There are two types of Version Objects:
 416
 417 =over 4
 418
 419 =item * Ordinary versions
 420
 421 These are the versions that normal modules will use.  Can contain as
 422 many subversions as required.  In particular, those using RCS/CVS can
 423 use the following:
 424
 425   $VERSION = version->new(qw$Revision: 2.7 $);
 426
 427 and the current RCS Revision for that file will be inserted
 428 automatically.  If the file has been moved to a branch, the Revision
 429 will have three or more elements; otherwise, it will have only two.
 430 This allows you to automatically increment your module version by
 431 using the Revision number from the primary file in a distribution, see
 432 L<ExtUtils::MakeMaker/"VERSION_FROM">.
 433
 434 =item * Alpha versions
 435
 436 For module authors using CPAN, the convention has been to note
 437 unstable releases with an underscore in the version string, see
 438 L<CPAN>.  Alpha releases will test as being newer than the more recent
 439 stable release, and less than the next stable release.  For example:
 440
 441   $alphaver = version->new("12.3_1"); # must quote
 442
 443 obeys the relationship
 444
 445   12.3 < $alphaver < 12.4
 446
 447 As a matter of fact, if is also true that
 448
 449   12.3.0 < $alphaver < 12.3.1
 450
 451 where the subversion is identical but the alpha release is less than
 452 the non-alpha release.
 453
 454 =head2 Replacement UNIVERSAL::VERSION
 455
 456 In addition to the version objects, this modules also replaces the core
 457 UNIVERSAL::VERSION function with one that uses version objects for its
 458 comparisons.  The return from this operator is always the numified form,
 459 and the warning message generated includes both the numified and normal
 460 forms (for clarity).
 461
 462 For example:
 463
 464   package Foo;
 465   $VERSION = 1.2;
 466
 467   package Bar;
 468   $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
 469
 470   package main;
 471   use version;
 472
 473   print $Foo::VERSION; # prints 1.2
 474
 475   print $Bar::VERSION; # prints 1.003005
 476
 477   eval "use CGI 10"; # some far future release
 478   print $@; # prints "CGI version 10 (10.0.0) required..."
 479
 480 IMPORTANT NOTE: This may mean that code which searches for a specific
 481 string (to determine whether a given module is available) may need to be
 482 changed.
 483
 484 =head1 EXPORT
 485
 486 qv - quoted version initialization operator
 487
 488 =head1 AUTHOR
 489
 490 John Peacock E<lt>jpeacock@rowman.comE<gt>
 491
 492 =head1 SEE ALSO
 493
 494 L<perl>.
 495
 496 =cut