view release on metacpan or  search on metacpan

lib/Version/Requirements.pm  view on Meta::CPAN

use strict;
use warnings;
package Version::Requirements;
# ABSTRACT: a set of version requirements for a CPAN dist
$Version::Requirements::VERSION = '0.101023';
#pod =head1 SYNOPSIS
#pod
#pod   use Version::Requirements;
#pod
#pod   my $build_requires = Version::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 Version::Requirements object models a set of version constraints like those
#pod specified in the F<META.yml> or F<META.json> files in CPAN distributions.  It
#pod can be built up by adding more and more constraints, and it will reduce them to
#pod 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

# We silence this warning during core tests, because this is only in core
# because it has to be, and nobody wants to see this stupid warning.
# -- rjbs, 2012-01-20
Carp::cluck(
  "Version::Requirements is deprecated; replace with CPAN::Meta::Requirements"
) unless $ENV{PERL_CORE};

#pod =method new
#pod
#pod   my $req = Version::Requirements->new;
#pod
#pod This returns a new Version::Requirements object.  It ignores any arguments
#pod given.
#pod
#pod =cut

sub new {
  my ($class) = @_;
  return bless {} => $class;
}

sub _version_object {
  my ($self, $version) = @_;

  $version = (! defined $version)                ? version->parse(0)
           : (! Scalar::Util::blessed($version)) ? version->parse($version)
           :                                       $version;

  return $version;
}

#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