Change 17991 by [EMAIL PROTECTED] on 2002/10/10 11:20:41
new files lib/version.pm and lib/version.t for change #17990.
Affected files ...
.... //depot/perl/lib/version.pm#1 add
.... //depot/perl/lib/version.t#1 add
Differences ...
==== //depot/perl/lib/version.pm#1 (text) ====
Index: perl/lib/version.pm
--- /dev/null Tue May 5 13:32:27 1998
+++ perl/lib/version.pm Thu Oct 10 04:20:41 2002
@@ -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>[EMAIL PROTECTED]<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>[EMAIL PROTECTED]<gt>
+
+=head1 SEE ALSO
+
+L<perl>.
+
+=cut
==== //depot/perl/lib/version.t#1 (text) ====
Index: perl/lib/version.t
--- /dev/null Tue May 5 13:32:27 1998
+++ perl/lib/version.t Thu Oct 10 04:20:41 2002
@@ -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');
+
End of Patch.
