lib/version.pm

   1 #!/usr/local/bin/perl -w
   2 package version;
   3
   4 use 5.005_03;
   5 use strict;
   6
   7 require DynaLoader;
   8 use vars qw(@ISA $VERSION $CLASS);
   9
  10 @ISA = qw(DynaLoader);
  11
  12 $VERSION = (qw$Revision: 2.2 $)[1]/10;
  13
  14 $CLASS = 'version';
  15
  16 bootstrap version if $] < 5.009;
  17
  18 # Preloaded methods go here.
  19
  20 1;
  21 __END__
  22
  23 =head1 NAME
  24
  25 version - Perl extension for Version Objects
  26
  27 =head1 SYNOPSIS
  28
  29   use version;
  30   $version = new version "12.2.1"; # must be quoted!
  31   print $version;               # 12.2.1
  32   print $version->numify;       # 12.002001
  33   if ( $version > 12.2 )        # true
  34
  35   $vstring = new version qw(v1.2); # must be quoted!
  36   print $vstring;               # 1.2
  37
  38   $betaver = new version "1.2_3"; # must be quoted!
  39   print $betaver;               # 1.2_3
  40
  41   $perlver = new version "5.005_03"; # must be quoted!
  42   print $perlver;               # 5.5.30
  43
  44 =head1 DESCRIPTION
  45
  46 Overloaded version objects for all versions of Perl.  This module
  47 implments all of the features of version objects which will be part
  48 of Perl 5.10.0 except automatic v-string handling.  See L<"Quoting">.
  49
  50 =head2 What IS a version
  51
  52 For the purposes of this module, a version "number" is a sequence of
  53 positive integral values separated by decimal points and optionally a
  54 single underscore.  This corresponds to what Perl itself uses for a
  55 version, as well as extending the "version as number" that is discussed
  56 in the various editions of the Camel book.
  57
  58 However, in order to be compatible with earlier Perl version styles,
  59 any use of versions of the form 5.006001 will be translated as 5.6.1,
  60 In other words a version with a single decimal place will be parsed
  61 as implicitely having three places between subversion.
  62
  63 Any value passed to the new() operator will be parsed only so far as it
  64 contains a numeric, decimal, or underscore character.  So, for example:
  65
  66   $v1 = new version "99 and 94/100 percent pure"; # $v1 == 99.0
  67   $v2 = new version "something"; # $v2 == "" and $v2->numify == 0
  68
  69 NOTE: it is strongly recommended that version objects only be created
  70 with numeric values based on the different types of versions in this
  71 documentation, see L<"Types of Versions Objects">.  That way, there is
  72 no confusion about what constitutes the version.
  73
  74 =head2 Object Methods
  75
  76 Overloading has been used with version objects to provide a natural
  77 interface for their use.  All mathematical operations are forbidden,
  78 since they don't make any sense for versions.  For the subsequent
  79 examples, the following two objects will be used:
  80
  81   $ver  = new version "1.2.3"; # see "Quoting" below
  82   $beta = new version "1.2_3"; # see "Beta versions" below
  83
  84 =item * Stringification - Any time a version object is used as a string,
  85 a stringified representation is returned in reduced form (no extraneous
  86 zeros):
  87
  88   print $ver->stringify;      # prints 1.2.3
  89   print $ver;                 # same thing
  90
  91 =item * Numification - although all mathematical operations on version
  92 objects are forbidden by default, it is possible to retrieve a number
  93 which roughly corresponds to the version object through the use of the
  94 $obj->numify method.  For formatting purposes, when displaying a number
  95 which corresponds a version object, all sub versions are assumed to have
  96 three decimal places.  So for example:
  97
  98   print $ver->numify;         # prints 1.002003
  99
 100 =item * Comparison operators - Both cmp and <=> operators perform the
 101 same comparison between terms (upgrading to a version object
 102 automatically).  Perl automatically generates all of the other comparison
 103 operators based on those two.  For example, the following relations hold:
 104
 105   As Number       As String       Truth Value
 106   ---------       ------------    -----------
 107   $ver >  1.0     $ver gt "1.0"      true
 108   $ver <  2.5     $ver lt            true
 109   $ver != 1.3     $ver ne "1.3"      true
 110   $ver == 1.2     $ver eq "1.2"      false
 111   $ver == 1.2.3   $ver eq "1.2.3"    see discussion below
 112   $ver == v1.2.3  $ver eq "v1.2.3"   ditto
 113
 114 In versions of Perl prior to the 5.9.0 development releases, it is not
 115 permitted to use bare v-strings in either form, due to the nature of Perl's
 116 parsing operation.  After that version (and in the stable 5.10.0 release),
 117 v-strings can be used with version objects without problem, see L<"Quoting">
 118 for more discussion of this topic.  In the case of the last two lines of
 119 the table above, only the string comparison will be true; the numerical
 120 comparison will test false.  However, you can do this:
 121
 122   $ver == "1.2.3" or $ver = "v.1.2.3"   # both true
 123
 124 even though you are doing a "numeric" comparison with a "string" value.
 125 It is probably best to chose either the numeric notation or the string
 126 notation and stick with it, to reduce confusion.  See also L<"Quoting">.
 127
 128 =head2 Quoting
 129
 130 Because of the nature of the Perl parsing and tokenizing routines,
 131 you should always quote the parameter to the new() operator/method.  The
 132 exact notation is vitally important to correctly determine the version
 133 that is requested.  You don't B<have> to quote the version parameter,
 134 but you should be aware of what Perl is likely to do in those cases.
 135
 136 If you use a mathematic formula that resolves to a floating point number,
 137 you are dependent on Perl's conversion routines to yield the version you
 138 expect.  You are pretty safe by dividing by a power of 10, for example,
 139 but other operations are not likely to be what you intend.  For example:
 140
 141   $VERSION = new version (qw$Revision: 1.4)[1]/10;
 142   print $VERSION;          # yields 0.14
 143   $V2 = new version 100/9; # Integer overflow in decimal number
 144   print $V2;               # yields 11_1285418553
 145
 146 You B<can> use a bare number, if you only have a major and minor version,
 147 since this should never in practice yield a floating point notation
 148 error.  For example:
 149
 150   $VERSION = new version  10.2;  # almost certainly ok
 151   $VERSION = new version "10.2"; # guaranteed ok
 152
 153 Perl 5.9.0 and beyond will be able to automatically quote v-strings
 154 (which may become the recommended notation), but that is not possible in
 155 earlier versions of Perl.  In other words:
 156
 157   $version = new version "v2.5.4";  # legal in all versions of Perl
 158   $newvers = new version v2.5.4;    # legal only in Perl > 5.9.0
 159
 160
 161 =head2 Types of Versions Objects
 162
 163 There are three basic types of Version Objects:
 164
 165 =item * Ordinary versions - These are the versions that normal
 166 modules will use.  Can contain as many subversions as required.
 167 In particular, those using RCS/CVS can use one of the following:
 168
 169   $VERSION = new version (qw$Revision: 2.1 $)[1]; # all Perls
 170   $VERSION = new version qw$Revision: 2.1 $[1];   # Perl >= 5.6.0
 171
 172 and the current RCS Revision for that file will be inserted
 173 automatically.  If the file has been moved to a branch, the
 174 Revision will have three or more elements; otherwise, it will
 175 have only two.  This allows you to automatically increment
 176 your module version by using the Revision number from the primary
 177 file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">.
 178
 179 =item * Beta versions - For module authors using CPAN, the
 180 convention has been to note unstable releases with an underscore
 181 in the version string, see L<CPAN>.  Beta releases will test as being
 182 newer than the more recent stable release, and less than the next
 183 stable release.  For example:
 184
 185   $betaver = new version "12.3_1"; # must quote
 186
 187 obeys the relationship
 188
 189   12.3 < $betaver < 12.4
 190
 191 As a matter of fact, if is also true that
 192
 193   12.3.0 < $betaver < 12.3.1
 194
 195 where the subversion is identical but the beta release is less than
 196 the non-beta release.
 197
 198 =item * Perl-style versions - an exceptional case is versions that
 199 were only used by Perl releases prior to 5.6.0.  If a version
 200 string contains an underscore immediately followed by a zero followed
 201 by a non-zero number, the version is processed according to the rules
 202 described in L<perldelta/Improved Perl version numbering system>
 203 released with Perl 5.6.0.  As an example:
 204
 205   $perlver = new version "5.005_03";
 206
 207 is interpreted, not as a beta release, but as the version 5.5.30,  NOTE
 208 that the major and minor versions are unchanged but the subversion is
 209 multiplied by 10, since the above was implicitely read as 5.005.030.
 210 There are modules currently on CPAN which may fall under of this rule, so
 211 module authors are urged to pay close attention to what version they are
 212 specifying.
 213
 214 =head2 Replacement UNIVERSAL::VERSION
 215
 216 In addition to the version objects, this modules also replaces the core
 217 UNIVERSAL::VERSION function with one that uses version objects for its
 218 comparisons.  So, for example, with all existing versions of Perl,
 219 something like the following pseudocode would fail:
 220
 221         package vertest;
 222         $VERSION = 0.45;
 223
 224         package main;
 225         use vertest 0.5;
 226
 227 even though those versions are meant to be read as 0.045 and 0.005
 228 respectively.  The UNIVERSAL::VERSION replacement function included
 229 with this module changes that behavior so that it will B<not> fail.
 230
 231 =head1 EXPORT
 232
 233 None by default.
 234
 235 =head1 AUTHOR
 236
 237 John Peacock E<lt>jpeacock@rowman.comE<gt>
 238
 239 =head1 SEE ALSO
 240
 241 L<perl>.
 242
 243 =cut
 244 #!/usr/local/bin/perl -w
 245 package version;
 246
 247 use 5.005_03;
 248 use strict;
 249
 250 require Exporter;
 251 require DynaLoader;
 252 use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK @EXPORT $VERSION $CLASS);
 253
 254 @ISA = qw(Exporter DynaLoader);
 255
 256 # This allows declaration       use version ':all';
 257 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
 258 # will save memory.
 259 %EXPORT_TAGS = ( 'all' => [ qw(
 260
 261 ) ] );
 262
 263 @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
 264
 265 @EXPORT = qw(
 266 );
 267
 268 $VERSION = (qw$Revision: 1.8 $)[1]/10;
 269
 270 $CLASS = 'version';
 271
 272 bootstrap version if $] < 5.009;
 273
 274 # Preloaded methods go here.
 275
 276 1;
 277 __END__
 278
 279 =head1 NAME
 280
 281 version - Perl extension for Version Objects
 282
 283 =head1 SYNOPSIS
 284
 285   use version;
 286   $version = new version "12.2.1"; # must be quoted!
 287   print $version;               # 12.2.1
 288   print $version->numify;       # 12.002001
 289   if ( $version > 12.2 )        # true
 290
 291   $vstring = new version qw(v1.2); # must be quoted!
 292   print $vstring;               # 1.2
 293
 294   $betaver = new version "1.2_3"; # must be quoted!
 295   print $betaver;               # 1.2_3
 296
 297   $perlver = new version "5.005_03"; # must be quoted!
 298   print $perlver;               # 5.5.30
 299
 300 =head1 DESCRIPTION
 301
 302 Overloaded version objects for all versions of Perl.  This module
 303 implments all of the features of version objects which will be part
 304 of Perl 5.10.0 except automatic v-string handling.  See L<"Quoting">.
 305
 306 =head2 What IS a version
 307
 308 For the purposes of this module, a version "number" is a sequence of
 309 positive integral values separated by decimal points and optionally a
 310 single underscore.  This corresponds to what Perl itself uses for a
 311 version, as well as including the "version as number" that is discussed
 312 in the various editions of the Camel book.
 313
 314 =head2 Object Methods
 315
 316 Overloading has been used with version objects to provide a natural
 317 interface for their use.  All mathematical operations are forbidden,
 318 since they don't make any sense for versions.  For the subsequent
 319 examples, the following two objects will be used:
 320
 321   $ver  = new version "1.2.3"; # see "Quoting" below
 322   $beta = new version "1.2_3"; # see "Beta versions" below
 323
 324 =item * Stringification - Any time a version object is used as a string,
 325 a stringified representation is returned in reduced form (no extraneous
 326 zeros):
 327
 328   print $ver->stringify;      # prints 1.2.3
 329   print $ver;                 # same thing
 330
 331 =item * Numification - although all mathematical operations on version
 332 objects are forbidden by default, it is possible to retrieve a number
 333 which roughly corresponds to the version object through the use of the
 334 $obj->numify method.  For formatting purposes, when displaying a number
 335 which corresponds a version object, all sub versions are assumed to have
 336 three decimal places.  So for example:
 337
 338   print $ver->numify;         # prints 1.002003
 339
 340 =item * Comparison operators - Both cmp and <=> operators perform the
 341 same comparison between terms (upgrading to a version object
 342 automatically).  Perl automatically generates all of the other comparison
 343 operators based on those two.  For example, the following relations hold:
 344
 345   As Number       As String       Truth Value
 346   ---------       ------------    -----------
 347   $ver >  1.0     $ver gt "1.0"      true
 348   $ver <  2.5     $ver lt            true
 349   $ver != 1.3     $ver ne "1.3"      true
 350   $ver == 1.2     $ver eq "1.2"      false
 351   $ver == 1.2.3   $ver eq "1.2.3"    see discussion below
 352   $ver == v1.2.3  $ver eq "v1.2.3"   ditto
 353
 354 In versions of Perl prior to the 5.9.0 development releases, it is not
 355 permitted to use bare v-strings in either form, due to the nature of Perl's
 356 parsing operation.  After that version (and in the stable 5.10.0 release),
 357 v-strings can be used with version objects without problem, see L<"Quoting">
 358 for more discussion of this topic.  In the case of the last two lines of
 359 the table above, only the string comparison will be true; the numerical
 360 comparison will test false.  However, you can do this:
 361
 362   $ver == "1.2.3" or $ver = "v.1.2.3"   # both true
 363
 364 even though you are doing a "numeric" comparison with a "string" value.
 365 It is probably best to chose either the numeric notation or the string
 366 notation and stick with it, to reduce confusion.  See also L<"Quoting">.
 367
 368 =head2 Quoting
 369
 370 Because of the nature of the Perl parsing and tokenizing routines,
 371 you should always quote the parameter to the new() operator/method.  The
 372 exact notation is vitally important to correctly determine the version
 373 that is requested.  You don't B<have> to quote the version parameter,
 374 but you should be aware of what Perl is likely to do in those cases.
 375
 376 If you use a mathematic formula that resolves to a floating point number,
 377 you are dependent on Perl's conversion routines to yield the version you
 378 expect.  You are pretty safe by dividing by a power of 10, for example,
 379 but other operations are not likely to be what you intend.  For example:
 380
 381   $VERSION = new version (qw$Revision: 1.4)[1]/10;
 382   print $VERSION;          # yields 0.14
 383   $V2 = new version 100/9; # Integer overflow in decimal number
 384   print $V2;               # yields 11_1285418553
 385
 386 You B<can> use a bare number, if you only have a major and minor version,
 387 since this should never in practice yield a floating point notation
 388 error.  For example:
 389
 390   $VERSION = new version  10.2;  # almost certainly ok
 391   $VERSION = new version "10.2"; # guaranteed ok
 392
 393 Perl 5.9.0 and beyond will be able to automatically quote v-strings
 394 (which may become the recommended notation), but that is not possible in
 395 earlier versions of Perl.  In other words:
 396
 397   $version = new version "v2.5.4";  # legal in all versions of Perl
 398   $newvers = new version v2.5.4;    # legal only in Perl > 5.9.0
 399
 400
 401 =head2 Types of Versions Objects
 402
 403 There are three basic types of Version Objects:
 404
 405 =item * Ordinary versions - These are the versions that normal
 406 modules will use.  Can contain as many subversions as required.
 407 In particular, those using RCS/CVS can use one of the following:
 408
 409   $VERSION = new version (qw$Revision: 1.8 $)[1]; # all Perls
 410   $VERSION = new version qw$Revision: 1.8 $[1];   # Perl >= 5.6.0
 411
 412 and the current RCS Revision for that file will be inserted
 413 automatically.  If the file has been moved to a branch, the
 414 Revision will have three or more elements; otherwise, it will
 415 have only two.  This allows you to automatically increment
 416 your module version by using the Revision number from the primary
 417 file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">.
 418
 419 =item * Beta versions - For module authors using CPAN, the
 420 convention has been to note unstable releases with an underscore
 421 in the version string, see L<CPAN>.  Beta releases will test as being
 422 newer than the more recent stable release, and less than the next
 423 stable release.  For example:
 424
 425   $betaver = new version "12.3_1"; # must quote
 426
 427 obeys the relationship
 428
 429   12.3 < $betaver < 12.4
 430
 431 As a matter of fact, if is also true that
 432
 433   12.3.0 < $betaver < 12.3.1
 434
 435 where the subversion is identical but the beta release is less than
 436 the non-beta release.
 437
 438 =item * Perl-style versions - an exceptional case is versions that
 439 were only used by Perl releases prior to 5.6.0.  If a version
 440 string contains an underscore immediately followed by a zero followed
 441 by a non-zero number, the version is processed according to the rules
 442 described in L<perldelta/Improved Perl version numbering system>
 443 released with Perl 5.6.0.  As an example:
 444
 445   $perlver = new version "5.005_03";
 446
 447 is interpreted, not as a beta release, but as the version 5.5.30,  NOTE
 448 that the major and minor versions are unchanged but the subversion is
 449 multiplied by 10, since the above was implicitely read as 5.005.030.
 450 There are modules currently on CPAN which may fall under of this rule, so
 451 module authors are urged to pay close attention to what version they are
 452 specifying.
 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.  So, for example, with all existing versions of Perl,
 459 something like the following pseudocode would fail:
 460
 461         package vertest;
 462         $VERSION = 0.45;
 463
 464         package main;
 465         use vertest 0.5;
 466
 467 even though those versions are meant to be read as 0.045 and 0.005
 468 respectively.  The UNIVERSAL::VERSION replacement function included
 469 with this module changes that behavior so that it will B<not> fail.
 470
 471 =head1 EXPORT
 472
 473 None by default.
 474
 475 =head1 AUTHOR
 476
 477 John Peacock E<lt>jpeacock@rowman.comE<gt>
 478
 479 =head1 SEE ALSO
 480
 481 L<perl>.
 482
 483 =cut