@EXPORT = qw(qv);
-$VERSION = 0.41; # stop using CVS and switch to subversion
+$VERSION = "0.43";
$CLASS = 'version';
print $version->numify; # 12.002001
if ( $version gt "12.2" ) # true
- $alphaver = version->new("1.2_3"); # must be quoted!
- print $alphaver; # 1.2_3
+ $alphaver = version->new("1.02_03"); # must be quoted!
+ print $alphaver; # 1.02_030
print $alphaver->is_alpha(); # true
$ver = qv(1.2); # 1.2.0
$ver = qv("1.2"); # 1.2.0
$perlver = version->new(5.005_03); # must not be quoted!
- print $perlver; # 5.5.30
+ print $perlver; # 5.005030
=head1 DESCRIPTION
=item * Numeric Versions
Any initial parameter which "looks like a number", see L<Numeric
-Versions>.
+Versions>. This also covers versions with a single decimal place and
+a single embedded underscore, see L<Numeric Alpha Versions>, even though
+these must be quoted to preserve the underscore formatting.
=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.
+and an optional embedded underscore, see L<Quoted Versions>.
=back
if required:
$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
+ $v = version->new(1.002003); # 1.002003
+ $v2 = version->new( "1.2.3"); # v1.2.3
+ $v3 = version->new( 1.2.3); # v1.2.3 for Perl >= 5.8.1
-Please see L<"Quoting"> for more details on how Perl will parse various
+In specific, version numbers initialized as L<Numeric Versions> will
+stringify in Numeric form. Version numbers initialized as L<Quoted Versions>
+will be stringified as L<Normal Form>.
+
+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
uniformity. See also L<New Operator> for an additional method of
initializing version objects.
+=head2 Numeric Alpha Versions
+
+The one time that a numeric version must be quoted is when a alpha form is
+used with an otherwise numeric version (i.e. a single decimal place). This
+is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
+versions for automatic updating purposes. Since some developers have used
+only two significant decimal places for their non-alpha releases, the
+version object will automatically take that into account if the initializer
+is quoted. For example Module::Example was released to CPAN with the
+following sequence of $VERSION's:
+
+ # $VERSION Stringified
+ 0.01 0.010
+ 0.02 0.020
+ 0.02_01 0.02_0100
+ 0.02_02 0.02_0200
+ 0.03 0.030
+ etc.
+
+As you can see, the version object created from the values in the first
+column may contain a trailing 0, but will otherwise be both mathematically
+equivalent and sorts alpha-numerically as would be expected.
+
=head2 Object Methods
Overloading has been used with version objects to provide a natural
numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
it were a L<Quoted Version>.
-New in 0.38, a new version object can be created as a copy of an existing
-version object:
+A new version object can be created as a copy of an existing version
+object, either as a class method:
$v1 = version->new(12.3);
$v2 = version->new($v1);
-and $v1 and $v2 will be identical.
+or as an object method:
+
+ $v1 = version->new(12.3);
+ $v2 = $v1->new();
+
+and in each case, $v1 and $v2 will be identical.
=back
$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
+ $nver = version->new(1.002); # see "Numeric Versions" above
=over 4
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):
+a normalized or reduced form (no extraneous zeros), and with a leading 'v':
- print $ver->normal; # prints as 1.2.3
+ print $ver->normal; # prints as v1.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"
+ print $nver->normal; # prints as v1.2.0
+ print $nver->stringify; # prints as 1.002, see "Stringification"
In order to preserve the meaning of the processed version, the
normalized representation will always contain at least three sub terms.
three decimal places. So for example:
print $ver->numify; # prints 1.002003
- print $nver->numify; # prints 1.2
+ print $nver->numify; # prints 1.002
Unlike the stringification operator, there is never any need to append
trailing zeros to preserve the correct version value.
used to produce the L<Normal Form>, even if the version was originally a
L<Numeric Version>.
- print $ver->stringify; # prints 1.2.3
- print $nver->stringify; # prints 1.2
+ print $ver->stringify; # prints v1.2.3
+ print $nver->stringify; # prints 1.002
=back
$V2 = version->new(100/9); # Integer overflow in decimal number
print $V2; # yields something like 11.111.111.100
-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:
+Perl 5.8.1 and beyond will be able to automatically quote v-strings but
+that is not possible in earlier versions of Perl. In other words:
$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
using the Revision number from the primary file in a distribution, see
L<ExtUtils::MakeMaker/"VERSION_FROM">.
-=item * Alpha versions
+=item * Alpha Versions
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:
- $alphaver = version->new("12.3_1"); # must quote
+ $alphaver = version->new("12.03_01"); # must be quoted
obeys the relationship
- 12.3 < $alphaver < 12.4
-
-As a matter of fact, if is also true that
-
- 12.3.0 < $alphaver < 12.3.1
-
-where the subversion is identical but the alpha release is less than
-the non-alpha release.
+ 12.03 < $alphaver < 12.04
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
- 12.300_100
+ 12.03_0100
+
+which is mathematically equivalent and ASCII sorts exactly the same as
+without the trailing zeros.
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
+ print $newver; # v12.3.1_1
=head2 Replacement UNIVERSAL::VERSION
print $module->VERSION;
-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.
-
+will also exclusively return the numified form. 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.
=head1 EXPORT
=head1 AUTHOR
-John Peacock E<lt>jpeacock@rowman.comE<gt>
+John Peacock E<lt>jpeacock@cpan.orgE<gt>
=head1 SEE ALSO
projects / p5sagit/p5-mst-13.2.git / blobdiff