=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.
=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
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:
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