Update CPAN-Meta-Requirements to CPAN version 2.126

  [DELTA]

2.126     2014-07-30 16:26:29-04:00 America/New_York

    [FIXED]

    - Fixed compatibility with version.pm 0.77

    [DOCUMENTED]

    - Minor documentation fixes

    [CHANGED]

    - Modernized distribution meta files

1 files changed, 273 insertions, 11 deletions

diff --git a/cpan/CPAN-Meta-Requirements/lib/CPAN/Meta/Requirements.pm b/cpan/CPAN-Meta-Requirements/lib/CPAN/Meta/Requirements.pm
index 621550cef6..c1193a00cb 100644
--- a/cpan/CPAN-Meta-Requirements/lib/CPAN/Meta/Requirements.pm
+++ b/cpan/CPAN-Meta-Requirements/lib/CPAN/Meta/Requirements.pm
@@ -1,14 +1,55 @@
 use strict;
 use warnings;
 package CPAN::Meta::Requirements;
-our $VERSION = '2.125'; # VERSION
+our $VERSION = '2.126'; # VERSION
 # ABSTRACT: a set of version requirements for a CPAN dist
 
+#pod =head1 SYNOPSIS
+#pod
+#pod   use CPAN::Meta::Requirements;
+#pod
+#pod   my $build_requires = CPAN::Meta::Requirements->new;
+#pod
+#pod   $build_requires->add_minimum('Library::Foo' => 1.208);
+#pod
+#pod   $build_requires->add_minimum('Library::Foo' => 2.602);
+#pod
+#pod   $build_requires->add_minimum('Module::Bar'  => 'v1.2.3');
+#pod
+#pod   $METAyml->{build_requires} = $build_requires->as_string_hash;
+#pod
+#pod =head1 DESCRIPTION
+#pod
+#pod A CPAN::Meta::Requirements object models a set of version constraints like
+#pod those specified in the F<META.yml> or F<META.json> files in CPAN distributions,
+#pod and as defined by L<CPAN::Meta::Spec>;
+#pod It can be built up by adding more and more constraints, and it will reduce them
+#pod to the simplest representation.
+#pod
+#pod Logically impossible constraints will be identified immediately by thrown
+#pod exceptions.
+#pod
+#pod =cut
 
 use Carp ();
 use Scalar::Util ();
 use version 0.77 (); # the ->parse method
 
+#pod =method new
+#pod
+#pod   my $req = CPAN::Meta::Requirements->new;
+#pod
+#pod This returns a new CPAN::Meta::Requirements object.  It takes an optional
+#pod hash reference argument.  Currently, only one key is supported:
+#pod
+#pod =for :list
+#pod * C<bad_version_hook> -- if provided, when a version cannot be parsed into
+#pod   a version object, this code reference will be called with the invalid version
+#pod   string as an argument.  It must return a valid version object.
+#pod
+#pod All other keys are ignored.
+#pod
+#pod =cut
 
 my @valid_options = qw( bad_version_hook );
 
@@ -28,6 +69,7 @@ sub _version_object {
   my $vobj;
 
   eval {
+    local $SIG{__WARN__} = sub { die "Invalid version: $_[0]" };
     $vobj  = (! defined $version)                ? version->parse(0)
            : (! Scalar::Util::blessed($version)) ? version->parse($version)
            :                                       $version;
@@ -56,6 +98,57 @@ sub _version_object {
   return $vobj;
 }
 
+#pod =method add_minimum
+#pod
+#pod   $req->add_minimum( $module => $version );
+#pod
+#pod This adds a new minimum version requirement.  If the new requirement is
+#pod redundant to the existing specification, this has no effect.
+#pod
+#pod Minimum requirements are inclusive.  C<$version> is required, along with any
+#pod greater version number.
+#pod
+#pod This method returns the requirements object.
+#pod
+#pod =method add_maximum
+#pod
+#pod   $req->add_maximum( $module => $version );
+#pod
+#pod This adds a new maximum version requirement.  If the new requirement is
+#pod redundant to the existing specification, this has no effect.
+#pod
+#pod Maximum requirements are inclusive.  No version strictly greater than the given
+#pod version is allowed.
+#pod
+#pod This method returns the requirements object.
+#pod
+#pod =method add_exclusion
+#pod
+#pod   $req->add_exclusion( $module => $version );
+#pod
+#pod This adds a new excluded version.  For example, you might use these three
+#pod method calls:
+#pod
+#pod   $req->add_minimum( $module => '1.00' );
+#pod   $req->add_maximum( $module => '1.82' );
+#pod
+#pod   $req->add_exclusion( $module => '1.75' );
+#pod
+#pod Any version between 1.00 and 1.82 inclusive would be acceptable, except for
+#pod 1.75.
+#pod
+#pod This method returns the requirements object.
+#pod
+#pod =method exact_version
+#pod
+#pod   $req->exact_version( $module => $version );
+#pod
+#pod This sets the version required for the given module to I<exactly> the given
+#pod version.  No other version would be considered acceptable.
+#pod
+#pod This method returns the requirements object.
+#pod
+#pod =cut
 
 BEGIN {
   for my $type (qw(minimum maximum exclusion exact_version)) {
@@ -77,6 +170,17 @@ BEGIN {
   }
 }
 
+#pod =method add_requirements
+#pod
+#pod   $req->add_requirements( $another_req_object );
+#pod
+#pod This method adds all the requirements in the given CPAN::Meta::Requirements object
+#pod to the requirements object on which it was called.  If there are any conflicts,
+#pod an exception is thrown.
+#pod
+#pod This method returns the requirements object.
+#pod
+#pod =cut
 
 sub add_requirements {
   my ($self, $req) = @_;
@@ -92,6 +196,22 @@ sub add_requirements {
   return $self;
 }
 
+#pod =method accepts_module
+#pod
+#pod   my $bool = $req->accepts_module($module => $version);
+#pod
+#pod Given an module and version, this method returns true if the version
+#pod specification for the module accepts the provided version.  In other words,
+#pod given:
+#pod
+#pod   Module => '>= 1.00, < 2.00'
+#pod
+#pod We will accept 1.00 and 1.75 but not 0.50 or 2.00.
+#pod
+#pod For modules that do not appear in the requirements, this method will return
+#pod true.
+#pod
+#pod =cut
 
 sub accepts_module {
   my ($self, $module, $version) = @_;
@@ -102,6 +222,15 @@ sub accepts_module {
   return $range->_accepts($version);
 }
 
+#pod =method clear_requirement
+#pod
+#pod   $req->clear_requirement( $module );
+#pod
+#pod This removes the requirement for a given module from the object.
+#pod
+#pod This method returns the requirements object.
+#pod
+#pod =cut
 
 sub clear_requirement {
   my ($self, $module) = @_;
@@ -116,6 +245,17 @@ sub clear_requirement {
   return $self;
 }
 
+#pod =method requirements_for_module
+#pod
+#pod   $req->requirements_for_module( $module );
+#pod
+#pod This returns a string containing the version requirements for a given module in
+#pod the format described in L<CPAN::Meta::Spec> or undef if the given module has no
+#pod requirements. This should only be used for informational purposes such as error
+#pod messages and should not be interpreted or used for comparison (see
+#pod L</accepts_module> instead.)
+#pod
+#pod =cut
 
 sub requirements_for_module {
   my ($self, $module) = @_;
@@ -124,9 +264,23 @@ sub requirements_for_module {
   return $entry->as_string;
 }
 
+#pod =method required_modules
+#pod
+#pod This method returns a list of all the modules for which requirements have been
+#pod specified.
+#pod
+#pod =cut
 
 sub required_modules { keys %{ $_[0]{requirements} } }
 
+#pod =method clone
+#pod
+#pod   $req->clone;
+#pod
+#pod This method returns a clone of the invocant.  The clone and the original object
+#pod can then be changed independent of one another.
+#pod
+#pod =cut
 
 sub clone {
   my ($self) = @_;
@@ -155,6 +309,12 @@ sub __modify_entry_for {
   $self->{requirements}{ $name } = $new;
 }
 
+#pod =method is_simple
+#pod
+#pod This method returns true if and only if all requirements are inclusive minimums
+#pod -- that is, if their string expression is just the version number.
+#pod
+#pod =cut
 
 sub is_simple {
   my ($self) = @_;
@@ -166,12 +326,61 @@ sub is_simple {
   return 1;
 }
 
+#pod =method is_finalized
+#pod
+#pod This method returns true if the requirements have been finalized by having the
+#pod C<finalize> method called on them.
+#pod
+#pod =cut
 
 sub is_finalized { $_[0]{finalized} }
 
+#pod =method finalize
+#pod
+#pod This method marks the requirements finalized.  Subsequent attempts to change
+#pod the requirements will be fatal, I<if> they would result in a change.  If they
+#pod would not alter the requirements, they have no effect.
+#pod
+#pod If a finalized set of requirements is cloned, the cloned requirements are not
+#pod also finalized.
+#pod
+#pod =cut
 
 sub finalize { $_[0]{finalized} = 1 }
 
+#pod =method as_string_hash
+#pod
+#pod This returns a reference to a hash describing the requirements using the
+#pod strings in the L<CPAN::Meta::Spec> specification.
+#pod
+#pod For example after the following program:
+#pod
+#pod   my $req = CPAN::Meta::Requirements->new;
+#pod
+#pod   $req->add_minimum('CPAN::Meta::Requirements' => 0.102);
+#pod
+#pod   $req->add_minimum('Library::Foo' => 1.208);
+#pod
+#pod   $req->add_maximum('Library::Foo' => 2.602);
+#pod
+#pod   $req->add_minimum('Module::Bar'  => 'v1.2.3');
+#pod
+#pod   $req->add_exclusion('Module::Bar'  => 'v1.2.8');
+#pod
+#pod   $req->exact_version('Xyzzy'  => '6.01');
+#pod
+#pod   my $hashref = $req->as_string_hash;
+#pod
+#pod C<$hashref> would contain:
+#pod
+#pod   {
+#pod     'CPAN::Meta::Requirements' => '0.102',
+#pod     'Library::Foo' => '>= 1.208, <= 2.206',
+#pod     'Module::Bar'  => '>= v1.2.3, != v1.2.8',
+#pod     'Xyzzy'        => '== 6.01',
+#pod   }
+#pod
+#pod =cut
 
 sub as_string_hash {
   my ($self) = @_;
@@ -182,6 +391,38 @@ sub as_string_hash {
   return \%hash;
 }
 
+#pod =method add_string_requirement
+#pod
+#pod   $req->add_string_requirement('Library::Foo' => '>= 1.208, <= 2.206');
+#pod
+#pod This method parses the passed in string and adds the appropriate requirement
+#pod for the given module.  It understands version ranges as described in the
+#pod L<CPAN::Meta::Spec/Version Ranges>. For example:
+#pod
+#pod =over 4
+#pod
+#pod =item 1.3
+#pod
+#pod =item >= 1.3
+#pod
+#pod =item <= 1.3
+#pod
+#pod =item == 1.3
+#pod
+#pod =item != 1.3
+#pod
+#pod =item > 1.3
+#pod
+#pod =item < 1.3
+#pod
+#pod =item >= 1.3, != 1.5, <= 2.0
+#pod
+#pod A version number without an operator is equivalent to specifying a minimum
+#pod (C<E<gt>=>).  Extra whitespace is allowed.
+#pod
+#pod =back
+#pod
+#pod =cut
 
 my %methods_for_op = (
   '==' => [ qw(exact_version) ],
@@ -215,6 +456,15 @@ sub add_string_requirement {
   }
 }
 
+#pod =method from_string_hash
+#pod
+#pod   my $req = CPAN::Meta::Requirements->from_string_hash( \%hash );
+#pod
+#pod This is an alternate constructor for a CPAN::Meta::Requirements object.  It takes
+#pod a hash of module names and version requirement strings and returns a new
+#pod CPAN::Meta::Requirements object.
+#pod
+#pod =cut
 
 sub from_string_hash {
   my ($class, $hash) = @_;
@@ -436,7 +686,7 @@ __END__
 
 =pod
 
-=encoding utf-8
+=encoding UTF-8
 
 =head1 NAME
 
@@ -444,7 +694,7 @@ CPAN::Meta::Requirements - a set of version requirements for a CPAN dist
 
 =head1 VERSION
 
-version 2.125
+version 2.126
 
 =head1 SYNOPSIS
 
@@ -463,7 +713,8 @@ version 2.125
 =head1 DESCRIPTION
 
 A CPAN::Meta::Requirements object models a set of version constraints like
-those specified in the F<META.yml> or F<META.json> files in CPAN distributions.
+those specified in the F<META.yml> or F<META.json> files in CPAN distributions,
+and as defined by L<CPAN::Meta::Spec>;
 It can be built up by adding more and more constraints, and it will reduce them
 to the simplest representation.
 
@@ -477,16 +728,13 @@ exceptions.
   my $req = CPAN::Meta::Requirements->new;
 
 This returns a new CPAN::Meta::Requirements object.  It takes an optional
-hash reference argument.  The following keys are supported:
+hash reference argument.  Currently, only one key is supported:
 
 =over 4
 
 =item *
 
-<bad_version_hook> -- if provided, when a version cannot be parsed into
-
-a version object, this code reference will be called with the invalid version
-string as an argument.  It must return a valid version object.
+C<bad_version_hook> -- if provided, when a version cannot be parsed into a version object, this code reference will be called with the invalid version string as an argument.  It must return a valid version object.
 
 =back
 
@@ -554,7 +802,7 @@ This method returns the requirements object.
 
 =head2 accepts_module
 
-  my $bool = $req->accepts_modules($module => $version);
+  my $bool = $req->accepts_module($module => $version);
 
 Given an module and version, this method returns true if the version
 specification for the module accepts the provided version.  In other words,
@@ -619,7 +867,7 @@ also finalized.
 =head2 as_string_hash
 
 This returns a reference to a hash describing the requirements using the
-strings in the F<META.yml> specification.
+strings in the L<CPAN::Meta::Spec> specification.
 
 For example after the following program:
 
@@ -720,6 +968,20 @@ Ricardo Signes <rjbs@cpan.org>
 
 =back
 
+=head1 CONTRIBUTORS
+
+=over 4
+
+=item *
+
+Karen Etheridge <ether@cpan.org>
+
+=item *
+
+robario <webmaster@robario.com>
+
+=back
+
 =head1 COPYRIGHT AND LICENSE
 
 This software is copyright (c) 2010 by David Golden and Ricardo Signes.