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