-#!/usr/local/bin/perl -w
+#!perl -w
package version;
use 5.005_03;
use strict;
+require Exporter;
require DynaLoader;
-use vars qw(@ISA $VERSION $CLASS);
+use vars qw(@ISA $VERSION $CLASS @EXPORT);
+
+@ISA = qw(Exporter DynaLoader);
-@ISA = qw(DynaLoader);
+@EXPORT = qw(qv);
-$VERSION = (qw$Revision: 2.1 $)[1]/10;
+$VERSION = 0.42; # stop using CVS and switch to subversion
$CLASS = 'version';
+local $^W; # shut up the 'redefined' warning for UNIVERSAL::VERSION
bootstrap version if $] < 5.009;
# Preloaded methods go here.
=head1 SYNOPSIS
use version;
- $version = new version "12.2.1"; # must be quoted!
+ $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
print $version; # 12.2.1
print $version->numify; # 12.002001
- if ( $version > 12.2 ) # true
+ if ( $version gt "12.2" ) # true
- $vstring = new version qw(v1.2); # must be quoted!
- print $vstring; # 1.2
+ $alphaver = version->new("1.2_3"); # must be quoted!
+ print $alphaver; # 1.2_3
+ print $alphaver->is_alpha(); # true
+
+ $ver = qv(1.2); # 1.2.0
+ $ver = qv("1.2"); # 1.2.0
- $betaver = new version "1.2_3"; # must be quoted!
- print $betaver; # 1.2_3
-
- $perlver = new version "5.005_03"; # must be quoted!
+ $perlver = version->new(5.005_03); # must not 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">.
+implements all of the features of version objects which will be part
+of Perl 5.10.0 except automatic version object creation.
=head2 What IS a version
version, as well as extending the "version as number" that is discussed
in the various editions of the Camel book.
-=head2 Object Methods
+There are actually two distinct ways to initialize versions:
-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:
+=over 4
- $ver = new version "1.2.3"; # see "Quoting" below
- $beta = new version "1.2_3"; # see "Beta versions" below
+=item * Numeric Versions
-=item * Stringification - Any time a version object is used as a string,
-a stringified representation is returned in reduced form (no extraneous
-zeros):
+Any initial parameter which "looks like a number", see L<Numeric
+Versions>.
- print $ver->stringify; # prints 1.2.3
- print $ver; # same thing
+=item * Quoted Versions
+
+Any initial parameter which contains more than one decimal point
+or contains an embedded underscore, see L<Quoted Versions>. The
+most recent development version of Perl (5.9.x) and the next major
+release (5.10.0) will automatically create version objects for bare
+numbers containing more than one decimal point in the appropriate
+context.
-=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:
+=back
- print $ver->numify; # prints 1.002003
+Both of these methods will produce similar version objects, in that
+the default stringification will yield the version L<Normal Form> only
+if required:
-=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:
+ $v = version->new(1.002); # 1.002, but compares like 1.2.0
+ $v = version->new(1.002003); # 1.2.3
+ $v2 = version->new( "1.2.3"); # 1.2.3
+ $v3 = version->new( 1.2.3); # 1.2.3 for Perl >= 5.8.1
- 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
+Please see L<"Quoting"> for more details on how Perl will parse various
+input values.
-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:
+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:
- $ver == "1.2.3" or $ver = "v.1.2.3" # both true
+ $v1 = version->new("99 and 94/100 percent pure"); # $v1 == 99.0
+ $v2 = version->new("something"); # $v2 == "" and $v2->numify == 0
-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">.
+However, see L<New Operator> for one case where non-numeric text is
+acceptable when initializing version objects.
-=head2 Quoting
+=head2 What about v-strings?
-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.
+Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
+of bytes was introduced, called v-strings. They were intended to be an
+easy way to enter, for example, Unicode strings (which contain two bytes
+per character). Some programs have used them to encode printer control
+characters (e.g. CRLF). They were also intended to be used for $VERSION.
+Their use has been problematic from the start and they will be phased out
+beginning in Perl 5.10.0.
-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:
+There are two ways to enter v-strings: a bare number with two or more
+decimal places, or a bare number with one or more decimal places and a
+leading 'v' character (also bare). 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
+ $vs1 = 1.2.3; # encoded as \1\2\3
+ $vs2 = v1.2; # encoded as \1\2
-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:
+The first of those two syntaxes is destined to be the default way to create
+a version object in 5.10.0, whereas the second will issue a mandatory
+deprecation warning beginning at the same time. In both cases, a v-string
+encoded version will always be stringified in the version L<Normal Form>.
- $VERSION = new version 10.2; # almost certainly ok
- $VERSION = new version "10.2"; # guaranteed ok
+Consequently, the use of v-strings to initialize version objects with
+this module is only possible with Perl 5.8.1 or better (which contain special
+code to enable it). Their use is B<strongly> discouraged in all
+circumstances (especially the leading 'v' style), since the meaning will
+change depending on which Perl you are running. It is better to use
+L<"Quoted Versions"> to ensure the proper interpretation.
-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:
+=head2 Numeric Versions
- $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
+These correspond to historical versions of Perl itself prior to 5.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, but only for
+purposes of comparison with other version objects. For example:
+ $v = version->new( 1.2); # prints 1.2, compares as 1.200.0
+ $v = version->new( 1.02); # prints 1.02, compares as 1.20.0
+ $v = version->new( 1.002); # prints 1.002, compares as 1.2.0
+ $v = version->new( 1.0023); # 1.2.300
+ $v = version->new( 1.00203); # 1.2.30
+ $v = version->new( 1.002_03); # 1.2.30 See "Quoting"
+ $v = version->new( 1.002003); # 1.2.3
-=head2 Types of Versions Objects
+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.
-There are three basic types of Version Objects:
+IMPORTANT NOTE: If your numeric version contains more than 3 significant
+digits after the decimal place, it will be split on each multiple of 3, so
+1.0003 becomes 1.0.300, due to the need to remain compatible with Perl's
+own 5.005_03 == 5.5.30 interpretation.
-=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:
+=head2 Quoted Versions
- $VERSION = new version (qw$Revision: 2.1 $)[1]; # all Perls
- $VERSION = new version qw$Revision: 2.1 $[1]; # Perl >= 5.6.0
+These are the newest form of versions, and correspond to Perl's own
+version style beginning with 5.6.0. Starting with Perl 5.10.0,
+and most likely Perl 6, this is likely to be the preferred form. This
+method requires that the input parameter be quoted, although Perl's after
+5.9.0 can use bare numbers with multiple decimal places as a special form
+of quoting.
+
+Unlike L<Numeric Versions>, Quoted Versions may have more than
+a single decimal point, e.g. "5.6.1" (for all versions of Perl). If a
+Quoted Version has only one decimal place (and no embedded underscore),
+it is interpreted exactly like a L<Numeric Version>.
+
+So, for example:
+
+ $v = version->new( "1.002"); # 1.2
+ $v = version->new( "1.2.3"); # 1.2.3
+ $v = version->new("1.0003"); # 1.0.300
+
+In addition to conventional versions, Quoted Versions can be
+used to create L<Alpha Versions>.
+
+In general, Quoted 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.
-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">.
+=head2 Object Methods
-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.
+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 base version objects.
-=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:
+=over 4
- $betaver = new version "12.3_1"; # must quote
+=item * New Operator
-obeys the relationship
+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.
- 12.3 < $betaver < 12.4
+In order to facilitate this feature, the following
+code can be employed:
-As a matter of fact, if is also true that
+ $VERSION = version->new(qw$Revision: 2.7 $);
- 12.3.0 < $betaver < 12.3.1
+and the version object will be created as if the following code
+were used:
-where the subversion is identical but the beta release is less than
-the non-beta release.
+ $VERSION = version->new("v2.7");
-=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:
+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. The CVS $Revision$ increments differently from
+numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
+it were a L<Quoted Version>.
- $perlver = new version "5.005_03";
+New in 0.38, a new version object can be created as a copy of an existing
+version object:
-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.
+ $v1 = version->new(12.3);
+ $v2 = version->new($v1);
-=head2 Replacement UNIVERSAL::VERSION
+and $v1 and $v2 will be identical.
-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:
+=back
- package vertest;
- $VERSION = 0.45;
+=over 4
- package main;
- use vertest 0.5;
+=item * qv()
-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.
+An alternate way to create a new version object is through the exported
+qv() sub. This is not strictly like other q? operators (like qq, qw),
+in that the only delimiters supported are parentheses (or spaces). It is
+the best way to initialize a short version without triggering the floating
+point interpretation. For example:
-=head1 EXPORT
+ $v1 = qv(1.2); # 1.2.0
+ $v2 = qv("1.2"); # also 1.2.0
-None by default.
+As you can see, either a bare number or a quoted string can be used, and
+either will yield the same version number.
-=head1 AUTHOR
+=back
-John Peacock E<lt>jpeacock@rowman.comE<gt>
+For the subsequent examples, the following three objects will be used:
-=head1 SEE ALSO
+ $ver = version->new("1.2.3.4"); # see "Quoting" below
+ $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
+ $nver = version->new(1.2); # see "Numeric Versions" above
-L<perl>.
+=over 4
-=cut
-#!/usr/local/bin/perl -w
-package version;
+=item * Normal Form
-use 5.005_03;
-use strict;
+For any version object which is initialized with multiple decimal
+places (either quoted or if possible v-string), or initialized using
+the L<qv()> operator, the stringified representation is returned in
+a normalized or reduced form (no extraneous zeros):
-require Exporter;
-require DynaLoader;
-use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK @EXPORT $VERSION $CLASS);
+ print $ver->normal; # prints as 1.2.3
+ print $ver->stringify; # ditto
+ print $ver; # ditto
+ print $nver->normal; # prints as 1.2.0
+ print $nver->stringify; # prints as 1.2, see "Stringification"
-@ISA = qw(Exporter DynaLoader);
+In order to preserve the meaning of the processed version, the
+normalized representation will always contain at least three sub terms.
+In other words, the following is guaranteed to always be true:
-# 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(
+ my $newver = version->new($ver->stringify);
+ if ($newver eq $ver ) # always true
+ {...}
-) ] );
+=back
-@EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
+=over 4
-@EXPORT = qw(
-);
+=item * Numification
-$VERSION = (qw$Revision: 1.8 $)[1]/10;
+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:
-$CLASS = 'version';
+ print $ver->numify; # prints 1.002003
+ print $nver->numify; # prints 1.2
-bootstrap version if $] < 5.009;
+Unlike the stringification operator, there is never any need to append
+trailing zeros to preserve the correct version value.
-# Preloaded methods go here.
+=back
-1;
-__END__
+=over 4
-=head1 NAME
+=item * Stringification
-version - Perl extension for Version Objects
+In order to mirror as much as possible the existing behavior of ordinary
+$VERSION scalars, the stringification operation will display differently,
+depending on whether the version was initialized as a L<Numeric Version>
+or L<Quoted Version>.
-=head1 SYNOPSIS
+What this means in practice is that if the normal CPAN and Camel rules are
+followed ($VERSION is a floating point number with no more than 3 decimal
+places), the stringified output will be exactly the same as the numified
+output. There will be no visible difference, although the internal
+representation will be different, and the L<Comparison operators> will
+function using the internal coding.
- 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
+If a version object is initialized using a L<Quoted Version> form, or if
+the number of significant decimal places exceed three, then the stringified
+form will be the L<Normal Form>. The $obj->normal operation can always be
+used to produce the L<Normal Form>, even if the version was originally a
+L<Numeric Version>.
- $vstring = new version qw(v1.2); # must be quoted!
- print $vstring; # 1.2
+ print $ver->stringify; # prints 1.2.3
+ print $nver->stringify; # prints 1.2
- $betaver = new version "1.2_3"; # must be quoted!
- print $betaver; # 1.2_3
+=back
- $perlver = new version "5.005_03"; # must be quoted!
- print $perlver; # 5.5.30
+=over 4
-=head1 DESCRIPTION
+=item * Comparison operators
-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">.
+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.
+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 "1.2.0" will compare as identical.
-=head2 What IS a version
+For example, the following relations hold:
-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.
+ 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
-=head2 Object Methods
+It is probably best to chose either the numeric notation or the string
+notation and stick with it, to reduce confusion. Perl6 version objects
+B<may> only support numeric comparisons. See also L<"Quoting">.
-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:
+WARNING: Comparing version with unequal numbers of decimal places (whether
+explicitely or implicitely initialized), may yield unexpected results at
+first glance. For example, the following inequalities hold:
- $ver = new version "1.2.3"; # see "Quoting" below
- $beta = new version "1.2_3"; # see "Beta versions" below
+ version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0
+ version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
-=item * Stringification - Any time a version object is used as a string,
-a stringified representation is returned in reduced form (no extraneous
-zeros):
+For this reason, it is best to use either exclusively L<Numeric Versions> or
+L<Quoted Versions> with multiple decimal places.
- print $ver->stringify; # prints 1.2.3
- print $ver; # same thing
+=back
-=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:
+=over 4
- print $ver->numify; # prints 1.002003
+=item * Logical Operators
-=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:
+If you need to test whether a version object
+has been initialized, you can simply test it directly:
- 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
+ $vobj = version->new($something);
+ if ( $vobj ) # true only if $something was non-blank
-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:
+You can also test whether a version object is an L<Alpha version>, for
+example to prevent the use of some feature not present in the main
+release:
- $ver == "1.2.3" or $ver = "v.1.2.3" # both true
+ $vobj = version->new("1.2_3"); # MUST QUOTE
+ ...later...
+ if ( $vobj->is_alpha ) # 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">.
+=back
=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.
+Because of the nature of the Perl parsing and tokenizing routines,
+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<Alpha 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 one or more decimals and an underscore is quoted, i.e.
+not bare, that is considered a L<Alpha 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
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;
+ $VERSION = version->new((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
+ $V2 = version->new(100/9); # Integer overflow in decimal number
+ print $V2; # yields something like 11.111.111.100
-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:
+Perl 5.8.1 and beyond will be able to automatically quote v-strings
+(although a warning may be issued under 5.9.x and 5.10.0), but that
+is not possible in earlier versions of Perl. In other words:
- $VERSION = new version 10.2; # almost certainly ok
- $VERSION = new version "10.2"; # guaranteed ok
+ $version = version->new("v2.5.4"); # legal in all versions of Perl
+ $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1
-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 two types of Version Objects:
-=head2 Types of Versions Objects
+=over 4
+
+=item * Ordinary versions
-There are three basic types of Version Objects:
+These are the versions that normal modules will use. Can contain as
+many subversions as required. In particular, those using RCS/CVS can
+use the following:
-=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 = version->new(qw$Revision: 2.7 $);
- $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">.
-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 * Alpha versions
-=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:
+For module authors using CPAN, the convention has been to note
+unstable releases with an underscore in the version string, see
+L<CPAN>. Alpha 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
+ $alphaver = version->new("12.3_1"); # must quote
obeys the relationship
- 12.3 < $betaver < 12.4
+ 12.3 < $alphaver < 12.4
As a matter of fact, if is also true that
- 12.3.0 < $betaver < 12.3.1
+ 12.3.0 < $alphaver < 12.3.1
-where the subversion is identical but the beta release is less than
-the non-beta release.
+where the subversion is identical but the alpha release is less than
+the non-alpha 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:
+Alpha versions with a single decimal place will be treated exactly as if
+they were L<Numeric Versions>, for parsing purposes. The stringification for
+alpha versions with a single decimal place may seem suprising, since any
+trailing zeros will visible. For example, the above $alphaver will print as
- $perlver = new version "5.005_03";
+ 12.300_100
-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.
+Alpha versions with more than a single decimal place will be treated
+exactly as if they were L<Quoted Versions>, and will display without any
+trailing (or leading) zeros, in the L<Version Normal> form. For example,
+
+ $newver = version->new("12.3.1_1");
+ print $newver; # 12.3.1_1
=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:
+comparisons. The return from this operator is always the numified form,
+and the warning message generated includes both the numified and normal
+forms (for clarity).
+
+For example:
+
+ package Foo;
+ $VERSION = 1.2;
+
+ package Bar;
+ $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
+
+ package main;
+ use version;
+
+ print $Foo::VERSION; # prints 1.2
+
+ print $Bar::VERSION; # prints 1.003005
+
+ eval "use CGI 10"; # some far future release
+ print $@; # prints "CGI version 10 (10.0.0) required..."
+
+IMPORTANT NOTE: This may mean that code which searches for a specific
+string (to determine whether a given module is available) may need to be
+changed.
+
+The replacement UNIVERSAL::VERSION, when used as a function, like this:
- package vertest;
- $VERSION = 0.45;
+ print $module->VERSION;
- package main;
- use vertest 0.5;
+will follow the stringification rules; i.e. Numeric versions will be displayed
+with the numified format, and the rest will be displayed with the Normal
+format. Technically, the $module->VERSION function returns a string (PV) that
+can be converted to a number following the normal Perl rules, when used in a
+numeric context.
-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.
+qv - quoted version initialization operator
=head1 AUTHOR
https://perl5.git.perl.org / perl5.git / blobdiff