This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
version objects final(?) patch
authorJohn Peacock <jpeacock@rowman.com>
Sun, 5 Jan 2003 21:28:41 +0000 (16:28 -0500)
committerhv <hv@crypt.org>
Mon, 10 Feb 2003 00:26:50 +0000 (00:26 +0000)
Message-ID: <3E18E9D9.2040908@rowman.com>

p4raw-id: //depot/perl@18682

lib/version.pm
lib/version.t
universal.c
util.c

index 5fd3b31..15cf81b 100644 (file)
@@ -1,4 +1,4 @@
-#!/usr/local/bin/perl -w
+#!/usr/bin/perl -w
 package version;
 
 use 5.005_03;
@@ -9,7 +9,7 @@ use vars qw(@ISA $VERSION $CLASS);
 
 @ISA = qw(DynaLoader);
 
-$VERSION = (qw$Revision: 2.3 $)[1]/10;
+$VERSION = (qw$Revision: 2.7 $)[1]/10;
 
 $CLASS = 'version';
 
@@ -31,7 +31,7 @@ version - Perl extension for Version Objects
   $version = new version "12.2.1"; # must be quoted!
   print $version;              # 12.2.1
   print $version->numify;      # 12.002001
-  if ( $version > 12.2 )       # true
+  if ( $version gt  "v12.2" )  # true
 
   $vstring = new version qw(v1.2); # must be quoted!
   print $vstring;              # 1.2
@@ -39,7 +39,7 @@ version - Perl extension for Version Objects
   $betaver = new version "1.2_3"; # must be quoted!
   print $betaver;              # 1.2_3
 
-  $perlver = new version "5.005_03"; # must be quoted!
+  $perlver = new version 5.005_03; # must not be quoted!
   print $perlver;              # 5.5.30
 
 =head1 DESCRIPTION
@@ -56,10 +56,29 @@ 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.
 
-However, 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 implicitly having three places between subversion.
+There are actually two distinct ways to initialize versions:
+
+=over 4
+
+=item * Numeric Versions - any initial parameter which "looks like
+a number", see L<Numeric Versions>.
+
+=item * V-String Versions - any initial parameter which contains more
+than one decimal point, contains an embedded underscore, or has a
+leading 'v' see L<V-String Versions>.
+
+=back
+
+Both of these methods will produce similar version objects, in that
+the default stringification will always be in a reduced form, i.e.:
+
+  $v  = new version 1.002003;  # 1.2.3
+  $v2 = new version  "1.2.3";  # 1.2.3
+  $v3 = new version   v1.2.3;  # 1.2.3 for Perl > v5.8.0
+  $v4 = new version    1.2.3;  # 1.2.3 for Perl > v5.8.0
+
+Please see L<Quoting> for more details on how Perl will parse various
+input values.
 
 Any value passed to the new() operator will be parsed only so far as it
 contains a numeric, decimal, or underscore character.  So, for example:
@@ -67,28 +86,113 @@ contains a numeric, decimal, or underscore character.  So, for example:
   $v1 = new version "99 and 94/100 percent pure"; # $v1 == 99.0
   $v2 = new version "something"; # $v2 == "" and $v2->numify == 0
 
-NOTE: it is strongly recommended that version objects only be created
-with numeric values based on the different types of versions in this
-documentation, see L<"Types of Versions Objects">.  That way, there is
-no confusion about what constitutes the version.
+However, see L<New Operator> for one case where non-numeric text is
+acceptable when initializing version objects.
+
+=head2 Numeric Versions
+
+These correspond to historical versions of Perl itself prior to v5.6.0,
+as well as all other modules which follow the Camel rules for the
+$VERSION scalar.  A numeric version is initialized with what looks like
+a floating point number.  Leading zeros B<are> significant and trailing
+zeros are implied so that a minimum of three places is maintained
+between subversions.  What this means is that any subversion (digits
+to the right of the decimal place) that contains less than three digits
+will have trailing zeros added to make up the difference.  For example:
+
+  $v = new version       1.2;    # 1.200
+  $v = new version      1.02;    # 1.20
+  $v = new version     1.002;    # 1.2
+  $v = new version    1.0023;    # 1.2.300
+  $v = new version   1.00203;    # 1.2.30
+  $v = new version  1.002_03;    # 1.2.30   See L<Quoting>
+  $v = new version  1.002003;    # 1.2.3
+
+All of the preceeding examples except the second to last are true 
+whether or not the input value is quoted.  The important feature is that
+the input value contains only a single decimal.
+
+=head2 V-String Versions
+
+These are the newest form of versions, and correspond to Perl's own
+version style beginning with v5.6.0.  Starting with Perl v5.10.0,
+this is likely to be the preferred form.  This method requires that
+the input parameter be quoted, although Perl > v5.9.0 can use bare 
+v-strings as a special form of quoting.
+
+Unlike L<Numeric Versions>, V-String Versions must either have more than
+a single decimal point, e.g. "5.6.1" B<or> must be prefaced by a "v"
+like this "v5.6" (much like v-string notation).  In fact, with the
+newest Perl v-strings themselves can be used to initialize version
+objects.  Also unlike L<Numeric Versions>, leading zeros are B<not>
+significant, and trailing zeros must be explicitely specified (i.e.
+will not be automatically added).  In addition, the subversions are 
+not enforced to be three decimal places.
+
+So, for example:
+
+  $v = new version    "v1.2";    # 1.2
+  $v = new version  "v1.002";    # 1.2
+  $v = new version   "1.2.3";    # 1.2.3
+  $v = new version  "v1.2.3";    # 1.2.3
+  $v = new version "v1.0003";    # 1.3
+
+In additional to conventional versions, V-String Versions can be
+used to create L<Beta Versions>.
+
+In general, V-String Versions permit the greatest amount of freedom
+to specify a version, whereas Numeric Versions enforce a certain 
+uniformity.  See also L<New Operator> for an additional method of
+initializing version objects.
 
 =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:
+since they don't make any sense for versions.
+
+=over 4
+
+=item * New Operator - Like all OO interfaces, the new() operator is
+used to initialize version objects.  One way to increment versions
+when programming is to use the CVS variable $Revision, which is
+automatically incremented by CVS every time the file is committed to
+the repository.
+
+=back 
+
+In order to facilitate this feature, the following
+code can be employed:
+
+  $VERSION = new version qw$Revision: 2.7 $;
+
+and the version object will be created as if the following code
+were used:
+
+  $VERSION = new version "v2.6";
+
+In other words, the version will be automatically parsed out of the
+string, and it will be quoted to preserve the meaning CVS normally
+carries 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
 
+=over 4
+
 =item * Stringification - Any time a version object is used as a string,
 a stringified representation is returned in reduced form (no extraneous
 zeros): 
 
+=back
+
   print $ver->stringify;      # prints 1.2.3
   print $ver;                 # same thing
 
+=over 4
+
 =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
@@ -96,15 +200,26 @@ $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:
 
+=back
+
   print $ver->numify;         # prints 1.002003
 
+=over 4
+
 =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:
+operators based on those two.  In addition to the obvious equalities
+listed below, appending a single trailing 0 term does not change the
+value of a version for comparison purposes.  In other words "v1.2" and
+"v1.2.0" are identical versions.
+
+=back
+
+For example, the following relations hold:
 
-  As Number       As String       Truth Value
-  ---------       ------------    -----------
+  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
@@ -129,10 +244,24 @@ 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.
+certain initialization values B<must> be quoted in order to correctly
+parse as the intended version, and additionally, some initial values
+B<must not> be quoted to obtain the intended version.
+
+Except for L<Beta versions>, any version initialized with something
+that looks like a number (a single decimal place) will be parsed in
+the same way whether or not the term is quoted.  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 implicitly
+having three places between subversions.
+
+The complicating factor is that in bare numbers (i.e. unquoted), the
+underscore is a legal numeric character and is automatically stripped
+by the Perl tokenizer before the version code is called.  However, if
+a number containing a single decimal and an underscore is quoted, i.e.
+not bare, that is considered a L<Beta Version> and the underscore is
+significant.
 
 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
@@ -144,13 +273,6 @@ but other operations are not likely to be what you intend.  For example:
   $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:
@@ -161,14 +283,17 @@ earlier versions of Perl.  In other words:
 
 =head2 Types of Versions Objects
 
-There are three basic types of Version Objects:
+There are two types of Version Objects:
+
+=over 4
 
 =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.3 $)[1]; # all Perls
-  $VERSION = new version qw$Revision: 2.3 $[1];   # Perl >= 5.6.0
+=back
+
+  $VERSION = new version qw$Revision: 2.7 $; 
 
 and the current RCS Revision for that file will be inserted 
 automatically.  If the file has been moved to a branch, the
@@ -177,12 +302,16 @@ 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">.
 
+=over 4
+
 =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:
 
+=back
+
   $betaver = new version "12.3_1"; # must quote
 
 obeys the relationship
@@ -196,38 +325,11 @@ As a matter of fact, if is also true that
 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 implicitly 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.
+comparisons.
 
 =head1 EXPORT
 
index 8823f23..4e34e56 100644 (file)
@@ -1,11 +1,12 @@
+#! /usr/local/perl -w
 # 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.1 $
+# $Revision: 2.3 $
 
 #########################
 
-use Test::More tests => 64;
-use_ok(version); # If we made it this far, we are ok.
+use Test::More tests => 71;
+use_ok("version"); # If we made it this far, we are ok.
 
 my ($version, $new_version);
 #########################
@@ -13,12 +14,24 @@ 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 bare number processing
+diag "tests with bare numbers" unless $ENV{PERL_CORE};
+$version = new version 5.005_03;
+is ( "$version" , "5.5.30" , '5.005_03 eq 5.5.30' );
+$version = new version 1.23;
+is ( "$version" , "1.230" , '1.23 eq "1.230"' );
+
+# Test quoted number processing
+diag "tests with quoted numbers" unless $ENV{PERL_CORE};
+$version = new version "5.005_03";
+is ( "$version" , "5.5_3" , '"5.005_03" eq "5.5_3"' );
+$version = new version "v1.23";
+is ( "$version" , "1.23" , '"v1.23" eq "1.23"' );
+
 # 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";
@@ -39,8 +52,10 @@ ok ("$version" eq "99.0", '$version eq "99.0"');
 ok ($version->numify == 99.0, '$version->numify == 99.0');
 
 $version = new version "something";
-ok ("$version" eq "", '$version eq ""');
-ok ($version->numify == 0, '$version->numify == 99.0');
+ok (defined $version, 'defined $version');
+
+# reset the test object to something reasonable
+$version = new version "1.2.3";
 
 # Test boolean operator
 ok ($version, 'boolean');
@@ -143,6 +158,19 @@ ok ( $version > $new_version, '$version > $new_version' );
 ok ( $new_version < $version, '$new_version < $version' );
 ok ( $version != $new_version, '$version != $new_version' );
 
+diag "test implicit [in]equality" unless $ENV{PERL_CORE};
+$version = new version "v1.2";
+$new_version = new version "1.2.0";
+ok ( $version == $new_version, '$version == $new_version' );
+$new_version = new version "1.2_0";
+ok ( $version == $new_version, '$version == $new_version' );
+$new_version = new version "1.2.1";
+ok ( $version < $new_version, '$version < $new_version' );
+$new_version = new version "1.2_1";
+ok ( $version < $new_version, '$version < $new_version' );
+$new_version = new version "1.1.999";
+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 ++" );
@@ -155,12 +183,12 @@ ok ( !eval { abs($version) }, "noop abs" );
 diag "Replacement UNIVERSAL::VERSION tests" unless $ENV{PERL_CORE};
 
 # we know this file is here since we require it ourselves
-$version = $Test::More::VERSION;
+$version = new 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
+$version = new version $Test::More::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');
index 3e8d8b1..a198fe6 100644 (file)
@@ -352,17 +352,19 @@ XS(XS_UNIVERSAL_VERSION)
 XS(XS_version_new)
 {
     dXSARGS;
-    if (items != 2)
+    if (items > 3)
        Perl_croak(aTHX_ "Usage: version::new(class, version)");
     SP -= items;
     {
 /*     char *  class = (char *)SvPV_nolen(ST(0)); */
-       SV *    version = ST(1);
-
-{
-    PUSHs(new_version(version));
-}
+        SV *version = ST(1);
+       if (items == 3 )
+       {
+           char *vs = savepvn(SvPVX(ST(2)),SvCUR(ST(2)));
+           version = newSVpvf("v%s",vs);
+       }
 
+       PUSHs(new_version(version));
        PUTBACK;
        return;
     }
diff --git a/util.c b/util.c
index 7f32acb..7664f60 100644 (file)
--- a/util.c
+++ b/util.c
@@ -3763,26 +3763,40 @@ Perl_scan_version(pTHX_ char *s, SV *rv)
        for (;;) {
            rev = 0;
            {
-               /* this is atoi() that delimits on underscores */
-               char *end = pos;
-               I32 mult = 1;
-               if ( s < pos && s > start && *(s-1) == '_' ) {
-                   if ( *s == '0' && *(s+1) != '0')
-                       mult = 10;      /* perl-style */
-                   else
-                       mult = -1;      /* beta version */
-               }
-               while (--end >= s) {
-                   I32 orev;
-                   orev = rev;
-                   rev += (*end - '0') * mult;
-                   mult *= 10;
-                   if ( abs(orev) > abs(rev) )
-                       Perl_croak(aTHX_ "Integer overflow in version");
-               }
-           }
-
-           /* Append revision */
+               /* this is atoi() that delimits on underscores */
+               char *end = pos;
+               I32 mult = 1;
+               I32 orev;
+               if ( s < pos && s > start && *(s-1) == '_' ) {
+                       mult *= -1;     /* beta version */
+               }
+               /* the following if() will only be true after the decimal
+                * point of a version originally created with a bare
+                * floating point number, i.e. not quoted in any way
+                */
+               if ( s > start+1 && saw_period == 1 && !saw_under ) {
+                   mult = 100;
+                   while ( s < end ) {
+                       orev = rev;
+                       rev += (*s - '0') * mult;
+                       mult /= 10;
+                       if ( abs(orev) > abs(rev) )
+                           Perl_croak(aTHX_ "Integer overflow in version");
+                       s++;
+                   }
+               }
+               else {
+                   while (--end >= s) {
+                       orev = rev;
+                       rev += (*end - '0') * mult;
+                       mult *= 10;
+                       if ( abs(orev) > abs(rev) )
+                           Perl_croak(aTHX_ "Integer overflow in version");
+                   }
+               } 
+           }
+  
+           /* Append revision */
            av_push((AV *)sv, newSViv(rev));
            if ( (*pos == '.' || *pos == '_') && isDIGIT(pos[1]))
                s = ++pos;
@@ -3818,7 +3832,7 @@ want to upgrade the SV.
 SV *
 Perl_new_version(pTHX_ SV *ver)
 {
-    SV *rv = NEWSV(92,5);
+    SV *rv = newSV(0);
     char *version;
     if ( SvNOK(ver) ) /* may get too much accuracy */ 
     {
@@ -3832,7 +3846,7 @@ Perl_new_version(pTHX_ SV *ver)
        version = savepvn( (const char*)mg->mg_ptr,mg->mg_len );
     }
 #endif
-    else
+    else /* must be a string or something like a string */
     {
        version = (char *)SvPV(ver,PL_na);
     }
@@ -3903,6 +3917,7 @@ Perl_vnumify(pTHX_ SV *vs)
     }
     if ( len == 0 )
         Perl_sv_catpv(aTHX_ sv,"000");
+    sv_setnv(sv, SvNV(sv));
     return sv;
 }
 
@@ -3946,7 +3961,7 @@ Perl_vstringify(pTHX_ SV *vs)
     if ( len == 0 )
         Perl_sv_catpv(aTHX_ sv,".0");
     return sv;
-}
+} 
 
 /*
 =for apidoc vcmp
@@ -3985,8 +4000,14 @@ Perl_vcmp(pTHX_ SV *lsv, SV *rsv)
        i++;
     }
 
-    if ( l != r && retval == 0 )
-       retval = l < r ? -1 : +1;
+    if ( l != r && retval == 0 ) /* possible match except for trailing 0 */
+    {
+       if ( !( l < r && r-l == 1 && SvIV(*av_fetch((AV *)rsv,r,0)) == 0 ) &&
+            !( l-r == 1 && SvIV(*av_fetch((AV *)lsv,l,0)) == 0 ) )
+       {
+           retval = l < r ? -1 : +1; /* not a match after all */
+       }
+    }
     return retval;
 }