diff options
| -rw-r--r-- | lib/version.pm | 472 | ||||
| -rw-r--r-- | lib/version.t | 169 |
2 files changed, 641 insertions, 0 deletions
diff --git a/lib/version.pm b/lib/version.pm new file mode 100644 index 0000000000..63d25acad7 --- /dev/null +++ b/lib/version.pm @@ -0,0 +1,472 @@ +#!/usr/local/bin/perl -w +package version; + +use 5.005_03; +use strict; + +require DynaLoader; +use vars qw(@ISA $VERSION $CLASS); + +@ISA = qw(DynaLoader); + +$VERSION = (qw$Revision: 2.1 $)[1]/10; + +$CLASS = 'version'; + +bootstrap version if $] < 5.009; + +# Preloaded methods go here. + +1; +__END__ + +=head1 NAME + +version - Perl extension for Version Objects + +=head1 SYNOPSIS + + use version; + $version = new version "12.2.1"; # must be quoted! + print $version; # 12.2.1 + print $version->numify; # 12.002001 + if ( $version > 12.2 ) # true + + $vstring = new version qw(v1.2); # must be quoted! + print $vstring; # 1.2 + + $betaver = new version "1.2_3"; # must be quoted! + print $betaver; # 1.2_3 + + $perlver = new version "5.005_03"; # must be quoted! + print $perlver; # 5.5.30 + +=head1 DESCRIPTION + +Overloaded version objects for all versions of Perl. This module +implments all of the features of version objects which will be part +of Perl 5.10.0 except automatic v-string handling. See L<"Quoting">. + +=head2 What IS a version + +For the purposes of this module, a version "number" is a sequence of +positive integral values separated by decimal points and optionally a +single underscore. This corresponds to what Perl itself uses for a +version, as well as extending the "version as number" that is discussed +in the various editions of the Camel book. + +=head2 Object Methods + +Overloading has been used with version objects to provide a natural +interface for their use. All mathematical operations are forbidden, +since they don't make any sense for versions. For the subsequent +examples, the following two objects will be used: + + $ver = new version "1.2.3"; # see "Quoting" below + $beta = new version "1.2_3"; # see "Beta versions" below + +=item * Stringification - Any time a version object is used as a string, +a stringified representation is returned in reduced form (no extraneous +zeros): + + print $ver->stringify; # prints 1.2.3 + print $ver; # same thing + +=item * Numification - although all mathematical operations on version +objects are forbidden by default, it is possible to retrieve a number +which roughly corresponds to the version object through the use of the +$obj->numify method. For formatting purposes, when displaying a number +which corresponds a version object, all sub versions are assumed to have +three decimal places. So for example: + + print $ver->numify; # prints 1.002003 + +=item * Comparison operators - Both cmp and <=> operators perform the +same comparison between terms (upgrading to a version object +automatically). Perl automatically generates all of the other comparison +operators based on those two. For example, the following relations hold: + + As Number As String Truth Value + --------- ------------ ----------- + $ver > 1.0 $ver gt "1.0" true + $ver < 2.5 $ver lt true + $ver != 1.3 $ver ne "1.3" true + $ver == 1.2 $ver eq "1.2" false + $ver == 1.2.3 $ver eq "1.2.3" see discussion below + $ver == v1.2.3 $ver eq "v1.2.3" ditto + +In versions of Perl prior to the 5.9.0 development releases, it is not +permitted to use bare v-strings in either form, due to the nature of Perl's +parsing operation. After that version (and in the stable 5.10.0 release), +v-strings can be used with version objects without problem, see L<"Quoting"> +for more discussion of this topic. In the case of the last two lines of +the table above, only the string comparison will be true; the numerical +comparison will test false. However, you can do this: + + $ver == "1.2.3" or $ver = "v.1.2.3" # both true + +even though you are doing a "numeric" comparison with a "string" value. +It is probably best to chose either the numeric notation or the string +notation and stick with it, to reduce confusion. See also L<"Quoting">. + +=head2 Quoting + +Because of the nature of the Perl parsing and tokenizing routines, +you should always quote the parameter to the new() operator/method. The +exact notation is vitally important to correctly determine the version +that is requested. You don't B<have> to quote the version parameter, +but you should be aware of what Perl is likely to do in those cases. + +If you use a mathematic formula that resolves to a floating point number, +you are dependent on Perl's conversion routines to yield the version you +expect. You are pretty safe by dividing by a power of 10, for example, +but other operations are not likely to be what you intend. For example: + + $VERSION = new version (qw$Revision: 1.4)[1]/10; + print $VERSION; # yields 0.14 + $V2 = new version 100/9; # Integer overflow in decimal number + print $V2; # yields 11_1285418553 + +You B<can> use a bare number, if you only have a major and minor version, +since this should never in practice yield a floating point notation +error. For example: + + $VERSION = new version 10.2; # almost certainly ok + $VERSION = new version "10.2"; # guaranteed ok + +Perl 5.9.0 and beyond will be able to automatically quote v-strings +(which may become the recommended notation), but that is not possible in +earlier versions of Perl. In other words: + + $version = new version "v2.5.4"; # legal in all versions of Perl + $newvers = new version v2.5.4; # legal only in Perl > 5.9.0 + + +=head2 Types of Versions Objects + +There are three basic types of Version Objects: + +=item * Ordinary versions - These are the versions that normal +modules will use. Can contain as many subversions as required. +In particular, those using RCS/CVS can use one of the following: + + $VERSION = new version (qw$Revision: 2.1 $)[1]; # all Perls + $VERSION = new version qw$Revision: 2.1 $[1]; # Perl >= 5.6.0 + +and the current RCS Revision for that file will be inserted +automatically. If the file has been moved to a branch, the +Revision will have three or more elements; otherwise, it will +have only two. This allows you to automatically increment +your module version by using the Revision number from the primary +file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">. + +In order to be compatible with earlier Perl version styles, any use +of versions of the form 5.006001 will be translated as 5.6.1, In +other words a version with a single decimal place will be parsed +as implicitely having three places between subversion. + +=item * Beta versions - For module authors using CPAN, the +convention has been to note unstable releases with an underscore +in the version string, see L<CPAN>. Beta releases will test as being +newer than the more recent stable release, and less than the next +stable release. For example: + + $betaver = new version "12.3_1"; # must quote + +obeys the relationship + + 12.3 < $betaver < 12.4 + +As a matter of fact, if is also true that + + 12.3.0 < $betaver < 12.3.1 + +where the subversion is identical but the beta release is less than +the non-beta release. + +=item * Perl-style versions - an exceptional case is versions that +were only used by Perl releases prior to 5.6.0. If a version +string contains an underscore immediately followed by a zero followed +by a non-zero number, the version is processed according to the rules +described in L<perldelta/Improved Perl version numbering system> +released with Perl 5.6.0. As an example: + + $perlver = new version "5.005_03"; + +is interpreted, not as a beta release, but as the version 5.5.30, NOTE +that the major and minor versions are unchanged but the subversion is +multiplied by 10, since the above was implicitely read as 5.005.030. +There are modules currently on CPAN which may fall under of this rule, so +module authors are urged to pay close attention to what version they are +specifying. + +=head2 Replacement UNIVERSAL::VERSION + +In addition to the version objects, this modules also replaces the core +UNIVERSAL::VERSION function with one that uses version objects for its +comparisons. So, for example, with all existing versions of Perl, +something like the following pseudocode would fail: + + package vertest; + $VERSION = 0.45; + + package main; + use vertest 0.5; + +even though those versions are meant to be read as 0.045 and 0.005 +respectively. The UNIVERSAL::VERSION replacement function included +with this module changes that behavior so that it will B<not> fail. + +=head1 EXPORT + +None by default. + +=head1 AUTHOR + +John Peacock E<lt>jpeacock@rowman.comE<gt> + +=head1 SEE ALSO + +L<perl>. + +=cut +#!/usr/local/bin/perl -w +package version; + +use 5.005_03; +use strict; + +require Exporter; +require DynaLoader; +use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK @EXPORT $VERSION $CLASS); + +@ISA = qw(Exporter DynaLoader); + +# This allows declaration use version ':all'; +# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK +# will save memory. +%EXPORT_TAGS = ( 'all' => [ qw( + +) ] ); + +@EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); + +@EXPORT = qw( +); + +$VERSION = (qw$Revision: 1.8 $)[1]/10; + +$CLASS = 'version'; + +bootstrap version if $] < 5.009; + +# Preloaded methods go here. + +1; +__END__ + +=head1 NAME + +version - Perl extension for Version Objects + +=head1 SYNOPSIS + + use version; + $version = new version "12.2.1"; # must be quoted! + print $version; # 12.2.1 + print $version->numify; # 12.002001 + if ( $version > 12.2 ) # true + + $vstring = new version qw(v1.2); # must be quoted! + print $vstring; # 1.2 + + $betaver = new version "1.2_3"; # must be quoted! + print $betaver; # 1.2_3 + + $perlver = new version "5.005_03"; # must be quoted! + print $perlver; # 5.5.30 + +=head1 DESCRIPTION + +Overloaded version objects for all versions of Perl. This module +implments all of the features of version objects which will be part +of Perl 5.10.0 except automatic v-string handling. See L<"Quoting">. + +=head2 What IS a version + +For the purposes of this module, a version "number" is a sequence of +positive integral values separated by decimal points and optionally a +single underscore. This corresponds to what Perl itself uses for a +version, as well as including the "version as number" that is discussed +in the various editions of the Camel book. + +=head2 Object Methods + +Overloading has been used with version objects to provide a natural +interface for their use. All mathematical operations are forbidden, +since they don't make any sense for versions. For the subsequent +examples, the following two objects will be used: + + $ver = new version "1.2.3"; # see "Quoting" below + $beta = new version "1.2_3"; # see "Beta versions" below + +=item * Stringification - Any time a version object is used as a string, +a stringified representation is returned in reduced form (no extraneous +zeros): + + print $ver->stringify; # prints 1.2.3 + print $ver; # same thing + +=item * Numification - although all mathematical operations on version +objects are forbidden by default, it is possible to retrieve a number +which roughly corresponds to the version object through the use of the +$obj->numify method. For formatting purposes, when displaying a number +which corresponds a version object, all sub versions are assumed to have +three decimal places. So for example: + + print $ver->numify; # prints 1.002003 + +=item * Comparison operators - Both cmp and <=> operators perform the +same comparison between terms (upgrading to a version object +automatically). Perl automatically generates all of the other comparison +operators based on those two. For example, the following relations hold: + + As Number As String Truth Value + --------- ------------ ----------- + $ver > 1.0 $ver gt "1.0" true + $ver < 2.5 $ver lt true + $ver != 1.3 $ver ne "1.3" true + $ver == 1.2 $ver eq "1.2" false + $ver == 1.2.3 $ver eq "1.2.3" see discussion below + $ver == v1.2.3 $ver eq "v1.2.3" ditto + +In versions of Perl prior to the 5.9.0 development releases, it is not +permitted to use bare v-strings in either form, due to the nature of Perl's +parsing operation. After that version (and in the stable 5.10.0 release), +v-strings can be used with version objects without problem, see L<"Quoting"> +for more discussion of this topic. In the case of the last two lines of +the table above, only the string comparison will be true; the numerical +comparison will test false. However, you can do this: + + $ver == "1.2.3" or $ver = "v.1.2.3" # both true + +even though you are doing a "numeric" comparison with a "string" value. +It is probably best to chose either the numeric notation or the string +notation and stick with it, to reduce confusion. See also L<"Quoting">. + +=head2 Quoting + +Because of the nature of the Perl parsing and tokenizing routines, +you should always quote the parameter to the new() operator/method. The +exact notation is vitally important to correctly determine the version +that is requested. You don't B<have> to quote the version parameter, +but you should be aware of what Perl is likely to do in those cases. + +If you use a mathematic formula that resolves to a floating point number, +you are dependent on Perl's conversion routines to yield the version you +expect. You are pretty safe by dividing by a power of 10, for example, +but other operations are not likely to be what you intend. For example: + + $VERSION = new version (qw$Revision: 1.4)[1]/10; + print $VERSION; # yields 0.14 + $V2 = new version 100/9; # Integer overflow in decimal number + print $V2; # yields 11_1285418553 + +You B<can> use a bare number, if you only have a major and minor version, +since this should never in practice yield a floating point notation +error. For example: + + $VERSION = new version 10.2; # almost certainly ok + $VERSION = new version "10.2"; # guaranteed ok + +Perl 5.9.0 and beyond will be able to automatically quote v-strings +(which may become the recommended notation), but that is not possible in +earlier versions of Perl. In other words: + + $version = new version "v2.5.4"; # legal in all versions of Perl + $newvers = new version v2.5.4; # legal only in Perl > 5.9.0 + + +=head2 Types of Versions Objects + +There are three basic types of Version Objects: + +=item * Ordinary versions - These are the versions that normal +modules will use. Can contain as many subversions as required. +In particular, those using RCS/CVS can use one of the following: + + $VERSION = new version (qw$Revision: 1.8 $)[1]; # all Perls + $VERSION = new version qw$Revision: 1.8 $[1]; # Perl >= 5.6.0 + +and the current RCS Revision for that file will be inserted +automatically. If the file has been moved to a branch, the +Revision will have three or more elements; otherwise, it will +have only two. This allows you to automatically increment +your module version by using the Revision number from the primary +file in a distribution, see L<ExtUtils::MakeMaker/"VERSION_FROM">. + +=item * Beta versions - For module authors using CPAN, the +convention has been to note unstable releases with an underscore +in the version string, see L<CPAN>. Beta releases will test as being +newer than the more recent stable release, and less than the next +stable release. For example: + + $betaver = new version "12.3_1"; # must quote + +obeys the relationship + + 12.3 < $betaver < 12.4 + +As a matter of fact, if is also true that + + 12.3.0 < $betaver < 12.3.1 + +where the subversion is identical but the beta release is less than +the non-beta release. + +=item * Perl-style versions - an exceptional case is versions that +were only used by Perl releases prior to 5.6.0. If a version +string contains an underscore immediately followed by a zero followed +by a non-zero number, the version is processed according to the rules +described in L<perldelta/Improved Perl version numbering system> +released with Perl 5.6.0. As an example: + + $perlver = new version "5.005_03"; + +is interpreted, not as a beta release, but as the version 5.5.30, NOTE +that the major and minor versions are unchanged but the subversion is +multiplied by 10, since the above was implicitely read as 5.005.030. +There are modules currently on CPAN which may fall under of this rule, so +module authors are urged to pay close attention to what version they are +specifying. + +=head2 Replacement UNIVERSAL::VERSION + +In addition to the version objects, this modules also replaces the core +UNIVERSAL::VERSION function with one that uses version objects for its +comparisons. So, for example, with all existing versions of Perl, +something like the following pseudocode would fail: + + package vertest; + $VERSION = 0.45; + + package main; + use vertest 0.5; + +even though those versions are meant to be read as 0.045 and 0.005 +respectively. The UNIVERSAL::VERSION replacement function included +with this module changes that behavior so that it will B<not> fail. + +=head1 EXPORT + +None by default. + +=head1 AUTHOR + +John Peacock E<lt>jpeacock@rowman.comE<gt> + +=head1 SEE ALSO + +L<perl>. + +=cut diff --git a/lib/version.t b/lib/version.t new file mode 100644 index 0000000000..4d4a791628 --- /dev/null +++ b/lib/version.t @@ -0,0 +1,169 @@ +# Before `make install' is performed this script should be runnable with +# `make test'. After `make install' it should work as `perl test.pl' +# $Revision: 2.0 $ + +######################### + +use Test::More tests => 60; +use_ok(version); # If we made it this far, we are ok. + +my ($version, $new_version); +######################### + +# Insert your test code below, the Test module is use()ed here so read +# its man page ( perldoc Test ) for help writing this test script. + +# Test stringify operator +diag "tests with stringify" unless $ENV{PERL_CORE}; +$version = new version "5.005"; +is ( "$version" , "5.5" , '5.005 eq 5.5' ); +$version = new version "5.005_03"; +is ( "$version" , "5.5.30" , 'perl version 5.005_03 eq 5.5.30' ); +$version = new version "5.006.001"; +is ( "$version" , "5.6.1" , '5.006.001 eq 5.6.1' ); +$version = new version "1.2.3_4"; +is ( "$version" , "1.2.3_4" , 'beta version 1.2.3_4 eq 1.2.3_4' ); + +# test illegal formats +diag "test illegal formats" unless $ENV{PERL_CORE}; +eval {my $version = new version "1.2_3_4";}; +like($@, qr/multiple underscores/, + "Invalid version format (multiple underscores)"); + +eval {my $version = new version "1.2_3.4";}; +like($@, qr/underscores before decimal/, + "Invalid version format (underscores before decimal)"); + +# Test boolean operator +ok ($version, 'boolean'); + +# Test ref operator +ok (ref($version) eq 'version','ref operator'); + +# Test comparison operators with self +diag "tests with self" unless $ENV{PERL_CORE}; +ok ( $version eq $version, '$version eq $version' ); +is ( $version cmp $version, 0, '$version cmp $version == 0' ); +ok ( $version == $version, '$version == $version' ); + +# test first with non-object +$version = new version "5.006.001"; +$new_version = "5.8.0"; +diag "tests with non-objects" unless $ENV{PERL_CORE}; +ok ( $version ne $new_version, '$version ne $new_version' ); +ok ( $version lt $new_version, '$version lt $new_version' ); +ok ( $new_version gt $version, '$new_version gt $version' ); +ok ( ref(\$new_version) eq 'SCALAR', 'no auto-upgrade'); +$new_version = "$version"; +ok ( $version eq $new_version, '$version eq $new_version' ); +ok ( $new_version eq $version, '$new_version eq $version' ); + +# now test with existing object +$new_version = new version "5.8.0"; +diag "tests with objects" unless $ENV{PERL_CORE}; +ok ( $version ne $new_version, '$version ne $new_version' ); +ok ( $version lt $new_version, '$version lt $new_version' ); +ok ( $new_version gt $version, '$new_version gt $version' ); +$new_version = new version "$version"; +ok ( $version eq $new_version, '$version eq $new_version' ); + +# Test Numeric Comparison operators +# test first with non-object +$new_version = "5.8.0"; +diag "numeric tests with non-objects" unless $ENV{PERL_CORE}; +ok ( $version == $version, '$version == $version' ); +ok ( $version < $new_version, '$version < $new_version' ); +ok ( $new_version > $version, '$new_version > $version' ); +ok ( $version != $new_version, '$version != $new_version' ); + +# now test with existing object +$new_version = new version $new_version; +diag "numeric tests with objects" unless $ENV{PERL_CORE}; +ok ( $version < $new_version, '$version < $new_version' ); +ok ( $new_version > $version, '$new_version > $version' ); +ok ( $version != $new_version, '$version != $new_version' ); + +# now test with actual numbers +diag "numeric tests with numbers" unless $ENV{PERL_CORE}; +ok ( $version->numify() == 5.006001, '$version->numify() == 5.006001' ); +ok ( $version->numify() <= 5.006001, '$version->numify() <= 5.006001' ); +ok ( $version->numify() < 5.008, '$version->numify() < 5.008' ); +#ok ( $version->numify() > v5.005_02, '$version->numify() > 5.005_02' ); + +# test with long decimals +diag "Tests with extended decimal versions" unless $ENV{PERL_CORE}; +$version = new version 1.002003; +ok ( $version eq "1.2.3", '$version eq "1.2.3"'); +ok ( $version->numify == 1.002003, '$version->numify == 1.002003'); +$version = new version "2002.09.30.1"; +ok ( $version eq "2002.9.30.1",'$version eq 2002.9.30.1'); +ok ( $version->numify == 2002.009030001, + '$version->numify == 2002.009030001'); + +# now test with Beta version form with string +$version = new version "1.2.3"; +$new_version = "1.2.3_4"; +diag "tests with beta-style non-objects" unless $ENV{PERL_CORE}; +ok ( $version lt $new_version, '$version lt $new_version' ); +ok ( $new_version gt $version, '$new_version gt $version' ); +ok ( $version ne $new_version, '$version ne $new_version' ); + +$version = new version "1.2.4"; +diag "numeric tests with beta-style non-objects" unless $ENV{PERL_CORE}; +ok ( $version > $new_version, '$version > $new_version' ); +ok ( $new_version < $version, '$new_version < $version' ); +ok ( $version != $new_version, '$version != $new_version' ); + +# now test with Beta version form with object +$version = new version "1.2.3"; +$new_version = new version "1.2.3_4"; +diag "tests with beta-style objects" unless $ENV{PERL_CORE}; +ok ( $version < $new_version, '$version < $new_version' ); +ok ( $new_version > $version, '$new_version > $version' ); +ok ( $version != $new_version, '$version != $new_version' ); + +$version = new version "1.2.4"; +diag "tests with beta-style objects" unless $ENV{PERL_CORE}; +ok ( $version > $new_version, '$version > $new_version' ); +ok ( $new_version < $version, '$new_version < $version' ); +ok ( $version != $new_version, '$version != $new_version' ); + +$version = new version "1.2.4"; +$new_version = new version "1.2_4"; +diag "tests with beta-style objects with same subversion" unless $ENV{PERL_CORE}; +ok ( $version > $new_version, '$version > $new_version' ); +ok ( $new_version < $version, '$new_version < $version' ); +ok ( $version != $new_version, '$version != $new_version' ); + +# that which is not expressly permitted is forbidden +diag "forbidden operations" unless $ENV{PERL_CORE}; +ok ( !eval { $version++ }, "noop ++" ); +ok ( !eval { $version-- }, "noop --" ); +ok ( !eval { $version/1 }, "noop /" ); +ok ( !eval { $version*3 }, "noop *" ); +ok ( !eval { abs($version) }, "noop abs" ); + +# test reformed UNIVERSAL::VERSION +diag "Replacement UNIVERSAL::VERSION tests" unless $ENV{PERL_CORE}; + +# we know this file is here since we require it ourselves +$version = $Test::More::VERSION; +eval "use Test::More $version"; +unlike($@, qr/Test::More version $version required/, + 'Replacement eval works with exact version'); + +$version += 0.01; # this should fail even with old UNIVERSAL::VERSION +eval "use Test::More $version"; +like($@, qr/Test::More version $version required/, + 'Replacement eval works with incremented version'); + +chop($version); # shorten by 1 digit, should still succeed +eval "use Test::More $version"; +unlike($@, qr/Test::More version $version required/, + 'Replacement eval works with single digit'); + +$version += 0.1; # this would fail with old UNIVERSAL::VERSION +eval "use Test::More $version"; +unlike($@, qr/Test::More version $version required/, + 'Replacement eval works with incremented digit'); + |