=head1 DESCRIPTION
-Overloaded version objects for all versions of Perl. This module
-implements all of the features of version objects which will be part
-of Perl 5.10.0.
+Overloaded version objects for all modern versions of Perl. This module
+implements all of the features of version objects which are part
+of Perl 5.10.0. All previous releases (i.e. before 0.74) are deprecated
+and should not be used due to incompatible API changes. If you 'use
+version' in your code, you are strongly urged to set a minimum, e.g.
+
+ use version 0.74; # to remain compatible with Perl v5.10.0
=head2 BEST PRACTICES
=item * Be careful
If you are using Module::Build or ExtUtils::MakeMaker, so that you can
-release your module to CPAN, you have to recognize that none of those
-programs currently handles version objects natively (yet). That also
-goes for the CPAN indexer (PAUSE). Although there are modules on CPAN
-that employ the version module internally, the support for assigning a
-module $VERSION scalar is still lacking. Both Module::Build and the
-PAUSE indexer will [hopefully soon] include support for version
-objects.
+release your module to CPAN, you have to recognize that neither of those
+programs completely handles version objects natively (yet). If you use
+version objects with Module::Build, you should add an explicit dependency
+to the release of version.pm in your Build.PL:
+
+ my $builder = Module::Build->new(
+ ...
+ requires => {
+ ... ,
+ 'version' => 0.50,
+ ...,
+ },
+ ...
+ );
+
+and it should Just Work(TM). Module::Build will [hopefully soon]
+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
$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>
+stringify as they were originally created (i.e. the same string that was
+passed to C<new()>. Version numbers initialized as L<Extended Versions>
will be stringified as L<Normal Form>.
=head2 Numeric Versions
purposes of comparison with other version objects. For example:
# Prints Equivalent to
- $v = version->new( 1.2); # 1.200 v1.200.0
- $v = version->new( 1.02); # 1.020 v1.20.0
+ $v = version->new( 1.2); # 1.2 v1.200.0
+ $v = version->new( 1.02); # 1.02 v1.20.0
$v = version->new( 1.002); # 1.002 v1.2.0
- $v = version->new( 1.0023); # 1.002300 v1.2.300
- $v = version->new( 1.00203); # 1.002030 v1.2.30
+ $v = version->new( 1.0023); # 1.0023 v1.2.300
+ $v = version->new( 1.00203); # 1.00203 v1.2.30
$v = version->new( 1.002003); # 1.002003 v1.2.3
All of the preceding examples are true whether or not the input value is
# 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
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
+ 0.01 0.01
+ 0.02 0.02
+ 0.02_01 0.02_01
+ 0.02_02 0.02_02
+ 0.03 0.03
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.
+The stringified form of numeric versions will always be the same string
+that was used to initialize the version object.
=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 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
recommended that all initializers to qv() be quoted strings instead of
bare numbers.
+To prevent the C<qv()> function from being exported to the caller's namespace,
+either use version with a null parameter:
+
+ use version ();
+
+or just require version, like this:
+
+ require version;
+
+Both methods will prevent the import() method from firing and exporting the
+C<qv()> sub. This is true of subclasses of version as well, see
+L<SUBCLASSING> for details.
+
=back
For the subsequent examples, the following three objects will be used:
=item * Stringification
-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<Extended Version>.
+The default stringification for version objects returns exactly the same
+string as was used to create it, whether you used C<new()> or C<qv()>,
+with one exception. The sole exception is if the object was created using
+C<qv()> and the initializer did not have two decimal places or a leading
+'v' (both optional), then the stringified form will have a leading 'v'
+prepended, in order to support round-trip processing.
+
+For example:
+
+ Initialized as Stringifies to
+ ============== ==============
+ version->new("1.2") 1.2
+ version->new("v1.2") v1.2
+ qv("1.2.3") 1.2.3
+ qv("v1.3.5") v1.3.5
+ qv("1.2") v1.2 ### exceptional case
+
+See also L<UNIVERSAL::VERSION>, as this also returns the stringified form
+when used as a class method.
+
+IMPORTANT NOTE: There is one exceptional cases shown in the above table
+where the "initializer" is not stringwise equivalent to the stringified
+representation. If you use the C<qv()> operator on a version without a
+leading 'v' B<and> with only a single decimal place, the stringified output
+will have a leading 'v', to preserve the sense. See the L<qv()> operator
+for more details.
+
+IMPORTANT NOTE 2: Attempting to bypass the normal stringification rules by
+manually applying L<numify()> and L<normal()> will sometimes yield
+surprising results:
+
+ print version->new(version->new("v1.0")->numify)->normal; # v1.0.0
+
+The reason for this is that the L<numify()> operator will turn "v1.0"
+into the equivalent string "1.000000". Forcing the outer version object
+to L<normal()> form will display the mathematically equivalent "v1.0.0".
-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
-points), 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.
+As the example in L<new()> shows, you can always create a copy of an
+existing version object with the same value by the very compact:
-If a version object is initialized using a L<Extended Version> form, 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>.
+ $v2 = $v1->new($v1);
- print $ver->stringify; # prints v1.2.3.4
- print $nver->stringify; # prints 1.002
+and be assured that both C<$v1> and C<$v2> will be completely equivalent,
+down to the same internal representation as well as stringification.
=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.
+
+3) In all cases, a version created using v-strings will have a stringified
+form that has a leading 'v' character, for the simple reason that sometimes
+it is impossible to tell whether one was present initially.
=head2 Types of Versions Objects
12.03 < $alphaver < 12.04
Alpha versions with a single decimal point will be treated exactly as if
-they were L<Numeric Versions>, for parsing purposes. The stringification for
-alpha versions with a single decimal point may seem surprising, since any
-trailing zeros will visible. For example, the above $alphaver will print as
-
- 12.03_0100
-
-which is mathematically equivalent and ASCII sorts exactly the same as
-without the trailing zeros.
+they were L<Numeric Versions>, for parsing and output purposes. The
+underscore will be output when an alpha version is stringified, in the same
+place as it was when input.
Alpha versions with more than a single decimal point will be treated
exactly as if they were L<Extended Versions>, and will display without any
$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
UNIVERSAL::VERSION function with one that uses version objects for its
-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).
+comparisons. The return from this operator is always the stringified form,
+but the warning message generated includes either the stringified form or
+the normal form, depending on how it was called.
For example:
print $Bar::VERSION; # prints 1.003005
- eval "use CGI 10"; # some far future release
- print $@; # prints "CGI version 10 (10.0.0) required..."
+ eval "use foo 10";
+ print $@; # prints "foo version 10 required..."
+ eval "use foo 1.3.5; # work in Perl 5.6.1 or better
+ print $@; # prints "foo version 1.3.5 required..."
+
+ eval "use bar 1.3.6";
+ print $@; # prints "bar version 1.3.6 required..."
+ eval "use bar 1.004"; # note numeric version
+ print $@; # prints "bar version 1.004 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.
+changed. It is always better to use the built-in comparison implicit in
+C<use> or C<require>, rather than manually poking at C<class->VERSION>
+and then doing a comparison yourself.
The replacement UNIVERSAL::VERSION, when used as a function, like this:
print $module->VERSION;
-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.
+will also exclusively return the stringified form. See L<Stringification>
+for more details.
=head1 SUBCLASSING
See also L<version::AlphaBeta> on CPAN for an alternate representation of
version strings.
-B<NOTE:> the L<qv> operator is not a class method and will not be inherited
-in the same way as the other methods. L<qv> will always return an object of
-type L<version> and not an object in the derived class. If you need to
-have L<qv> return an object in your derived class, add something like this:
-
- *::qv = sub { return bless version::qv(shift), __PACKAGE__ };
-
-as seen in the test file F<t/02derived.t>.
+B<NOTE:> Although the L<qv> operator is not a true class method, but rather a
+function exported into the caller's namespace, a subclass of version will
+inherit an import() function which will perform the correct magic on behalf
+of the subclass.
=head1 EXPORT
projects / p5sagit/p5-mst-13.2.git / blobdiff