=head1 DESCRIPTION
-Overloaded version objects for all versions of Perl. This module
+Overloaded version objects for all modern versions of Perl. This module
implements all of the features of version objects which will be part
of Perl 5.10.0.
include full support for version objects; there are no current plans
to patch ExtUtils::MakeMaker to support version objects.
+=back
+
+=head2 Using modules that use version.pm
+
+As much as possible, the version.pm module remains compatible with all
+current code. However, if your module is using a module that has defined
+C<$VERSION> using the version class, there are a couple of things to be
+aware of. For purposes of discussion, we will assume that we have the
+following module installed:
+
+ package Example;
+ use version; $VERSION = qv('1.2.2');
+ ...module code here...
+ 1;
+
+=over 4
+
+=item Numeric versions always work
+
+Code of the form:
+
+ use Example 1.002003;
+
+will always work correctly. The C<use> will perform an automatic
+C<$VERSION> comparison using the floating point number given as the first
+term after the module name (e.g. above 1.002.003). In this case, the
+installed module is too old for the requested line, so you would see an
+error like:
+
+ Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
+
+=item Extended version work sometimes
+
+With Perl >= 5.6.2, you can also use a line like this:
+
+ use Example 1.2.3;
+
+and it will again work (i.e. give the error message as above), even with
+releases of Perl which do not normally support v-strings (see L<What about
+v-strings> below). This has to do with that fact that C<use> only checks
+to see if the second term I<looks like a number> and passes that to the
+replacement L<UNIVERSAL::VERSION>. This is not true in Perl 5.005_04,
+however, so you are B<strongly encouraged> to always use a numeric version
+in your code, even for those versions of Perl which support the extended
+version.
+
+=back
+
=head2 What IS a version
For the purposes of this module, a version "number" is a sequence of
$v = version->new(1.002); # 1.002, but compares like 1.2.0
$v = version->new(1.002003); # 1.002003
- $v2 = version->new( "1.2.3"); # v1.2.3
+ $v2 = version->new("1.2.3"); # v1.2.3
In specific, version numbers initialized as L<Numeric Versions> will
stringify in Numeric form. Version numbers initialized as L<Extended Versions>
# Prints
$v = version->new( "v1.200"); # v1.200.0
$v = version->new("v1.20.0"); # v1.20.0
- $v = qv("v1.2.3); # v1.2.3
+ $v = qv("v1.2.3"); # v1.2.3
$v = qv("1.2.3"); # v1.2.3
$v = qv("1.20"); # v1.20.0
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.
+since they don't make any sense for base version objects. Consequently,
+there is no overloaded numification available. If you want to use a
+version object in a numeric context for some reason, see the L<numify>
+object method.
=over 4
or as an object method:
$v1 = version->new(12.3);
+ $v2 = $v1->new(12.3);
+
+and in each case, $v1 and $v2 will be identical. NOTE: if you create
+a new object using an existing object like this:
+
$v2 = $v1->new();
-and in each case, $v1 and $v2 will be identical.
+the new object B<will not> be a clone of the existing object. In the
+example case, $v2 will be an empty object of the same type as $v1.
=back
$vs1 = 1.2.3; # encoded as \1\2\3
$vs2 = v1.2; # encoded as \1\2
-However, 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 directly
-use L<"Extended Versions"> to ensure the proper interpretation.
+However, the use of bare v-strings to initialize version objects 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 directly use L<"Extended Versions"> to
+ensure the proper interpretation.
+
+If you insist on using bare v-strings with Perl > 5.6.0, be aware of the
+following limitations:
+1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses,
+based on some characteristics of v-strings. You B<must> use a three part
+version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful.
+
+2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl
+core to be magical, which means that the version.pm code can automatically
+determine whether the v-string encoding was used.
=head2 Types of Versions Objects
$newver = version->new("12.3.1_1");
print $newver; # v12.3.1_1
+=back
+
=head2 Replacement UNIVERSAL::VERSION
In addition to the version objects, this modules also replaces the core
projects / p5sagit/p5-mst-13.2.git / blobdiff