Blame README

Packit f40462
NAME
Packit f40462
    CPAN::Meta::Requirements - a set of version requirements for a CPAN dist
Packit f40462
Packit f40462
VERSION
Packit f40462
    version 2.140
Packit f40462
Packit f40462
SYNOPSIS
Packit f40462
      use CPAN::Meta::Requirements;
Packit f40462
Packit f40462
      my $build_requires = CPAN::Meta::Requirements->new;
Packit f40462
Packit f40462
      $build_requires->add_minimum('Library::Foo' => 1.208);
Packit f40462
Packit f40462
      $build_requires->add_minimum('Library::Foo' => 2.602);
Packit f40462
Packit f40462
      $build_requires->add_minimum('Module::Bar'  => 'v1.2.3');
Packit f40462
Packit f40462
      $METAyml->{build_requires} = $build_requires->as_string_hash;
Packit f40462
Packit f40462
DESCRIPTION
Packit f40462
    A CPAN::Meta::Requirements object models a set of version constraints
Packit f40462
    like those specified in the META.yml or META.json files in CPAN
Packit f40462
    distributions, and as defined by CPAN::Meta::Spec; It can be built up by
Packit f40462
    adding more and more constraints, and it will reduce them to the
Packit f40462
    simplest representation.
Packit f40462
Packit f40462
    Logically impossible constraints will be identified immediately by
Packit f40462
    thrown exceptions.
Packit f40462
Packit f40462
METHODS
Packit f40462
  new
Packit f40462
      my $req = CPAN::Meta::Requirements->new;
Packit f40462
Packit f40462
    This returns a new CPAN::Meta::Requirements object. It takes an optional
Packit f40462
    hash reference argument. Currently, only one key is supported:
Packit f40462
Packit f40462
    *   "bad_version_hook" -- if provided, when a version cannot be parsed
Packit f40462
        into a version object, this code reference will be called with the
Packit f40462
        invalid version string as first argument, and the module name as
Packit f40462
        second argument. It must return a valid version object.
Packit f40462
Packit f40462
    All other keys are ignored.
Packit f40462
Packit f40462
  add_minimum
Packit f40462
      $req->add_minimum( $module => $version );
Packit f40462
Packit f40462
    This adds a new minimum version requirement. If the new requirement is
Packit f40462
    redundant to the existing specification, this has no effect.
Packit f40462
Packit f40462
    Minimum requirements are inclusive. $version is required, along with any
Packit f40462
    greater version number.
Packit f40462
Packit f40462
    This method returns the requirements object.
Packit f40462
Packit f40462
  add_maximum
Packit f40462
      $req->add_maximum( $module => $version );
Packit f40462
Packit f40462
    This adds a new maximum version requirement. If the new requirement is
Packit f40462
    redundant to the existing specification, this has no effect.
Packit f40462
Packit f40462
    Maximum requirements are inclusive. No version strictly greater than the
Packit f40462
    given version is allowed.
Packit f40462
Packit f40462
    This method returns the requirements object.
Packit f40462
Packit f40462
  add_exclusion
Packit f40462
      $req->add_exclusion( $module => $version );
Packit f40462
Packit f40462
    This adds a new excluded version. For example, you might use these three
Packit f40462
    method calls:
Packit f40462
Packit f40462
      $req->add_minimum( $module => '1.00' );
Packit f40462
      $req->add_maximum( $module => '1.82' );
Packit f40462
Packit f40462
      $req->add_exclusion( $module => '1.75' );
Packit f40462
Packit f40462
    Any version between 1.00 and 1.82 inclusive would be acceptable, except
Packit f40462
    for 1.75.
Packit f40462
Packit f40462
    This method returns the requirements object.
Packit f40462
Packit f40462
  exact_version
Packit f40462
      $req->exact_version( $module => $version );
Packit f40462
Packit f40462
    This sets the version required for the given module to *exactly* the
Packit f40462
    given version. No other version would be considered acceptable.
Packit f40462
Packit f40462
    This method returns the requirements object.
Packit f40462
Packit f40462
  add_requirements
Packit f40462
      $req->add_requirements( $another_req_object );
Packit f40462
Packit f40462
    This method adds all the requirements in the given
Packit f40462
    CPAN::Meta::Requirements object to the requirements object on which it
Packit f40462
    was called. If there are any conflicts, an exception is thrown.
Packit f40462
Packit f40462
    This method returns the requirements object.
Packit f40462
Packit f40462
  accepts_module
Packit f40462
      my $bool = $req->accepts_module($module => $version);
Packit f40462
Packit f40462
    Given an module and version, this method returns true if the version
Packit f40462
    specification for the module accepts the provided version. In other
Packit f40462
    words, given:
Packit f40462
Packit f40462
      Module => '>= 1.00, < 2.00'
Packit f40462
Packit f40462
    We will accept 1.00 and 1.75 but not 0.50 or 2.00.
Packit f40462
Packit f40462
    For modules that do not appear in the requirements, this method will
Packit f40462
    return true.
Packit f40462
Packit f40462
  clear_requirement
Packit f40462
      $req->clear_requirement( $module );
Packit f40462
Packit f40462
    This removes the requirement for a given module from the object.
Packit f40462
Packit f40462
    This method returns the requirements object.
Packit f40462
Packit f40462
  requirements_for_module
Packit f40462
      $req->requirements_for_module( $module );
Packit f40462
Packit f40462
    This returns a string containing the version requirements for a given
Packit f40462
    module in the format described in CPAN::Meta::Spec or undef if the given
Packit f40462
    module has no requirements. This should only be used for informational
Packit f40462
    purposes such as error messages and should not be interpreted or used
Packit f40462
    for comparison (see "accepts_module" instead).
Packit f40462
Packit f40462
  structured_requirements_for_module
Packit f40462
      $req->structured_requirements_for_module( $module );
Packit f40462
Packit f40462
    This returns a data structure containing the version requirements for a
Packit f40462
    given module or undef if the given module has no requirements. This
Packit f40462
    should not be used for version checks (see "accepts_module" instead).
Packit f40462
Packit f40462
    Added in version 2.134.
Packit f40462
Packit f40462
  required_modules
Packit f40462
    This method returns a list of all the modules for which requirements
Packit f40462
    have been specified.
Packit f40462
Packit f40462
  clone
Packit f40462
      $req->clone;
Packit f40462
Packit f40462
    This method returns a clone of the invocant. The clone and the original
Packit f40462
    object can then be changed independent of one another.
Packit f40462
Packit f40462
  is_simple
Packit f40462
    This method returns true if and only if all requirements are inclusive
Packit f40462
    minimums -- that is, if their string expression is just the version
Packit f40462
    number.
Packit f40462
Packit f40462
  is_finalized
Packit f40462
    This method returns true if the requirements have been finalized by
Packit f40462
    having the "finalize" method called on them.
Packit f40462
Packit f40462
  finalize
Packit f40462
    This method marks the requirements finalized. Subsequent attempts to
Packit f40462
    change the requirements will be fatal, *if* they would result in a
Packit f40462
    change. If they would not alter the requirements, they have no effect.
Packit f40462
Packit f40462
    If a finalized set of requirements is cloned, the cloned requirements
Packit f40462
    are not also finalized.
Packit f40462
Packit f40462
  as_string_hash
Packit f40462
    This returns a reference to a hash describing the requirements using the
Packit f40462
    strings in the CPAN::Meta::Spec specification.
Packit f40462
Packit f40462
    For example after the following program:
Packit f40462
Packit f40462
      my $req = CPAN::Meta::Requirements->new;
Packit f40462
Packit f40462
      $req->add_minimum('CPAN::Meta::Requirements' => 0.102);
Packit f40462
Packit f40462
      $req->add_minimum('Library::Foo' => 1.208);
Packit f40462
Packit f40462
      $req->add_maximum('Library::Foo' => 2.602);
Packit f40462
Packit f40462
      $req->add_minimum('Module::Bar'  => 'v1.2.3');
Packit f40462
Packit f40462
      $req->add_exclusion('Module::Bar'  => 'v1.2.8');
Packit f40462
Packit f40462
      $req->exact_version('Xyzzy'  => '6.01');
Packit f40462
Packit f40462
      my $hashref = $req->as_string_hash;
Packit f40462
Packit f40462
    $hashref would contain:
Packit f40462
Packit f40462
      {
Packit f40462
        'CPAN::Meta::Requirements' => '0.102',
Packit f40462
        'Library::Foo' => '>= 1.208, <= 2.206',
Packit f40462
        'Module::Bar'  => '>= v1.2.3, != v1.2.8',
Packit f40462
        'Xyzzy'        => '== 6.01',
Packit f40462
      }
Packit f40462
Packit f40462
  add_string_requirement
Packit f40462
      $req->add_string_requirement('Library::Foo' => '>= 1.208, <= 2.206');
Packit f40462
      $req->add_string_requirement('Library::Foo' => v1.208);
Packit f40462
Packit f40462
    This method parses the passed in string and adds the appropriate
Packit f40462
    requirement for the given module. A version can be a Perl "v-string". It
Packit f40462
    understands version ranges as described in the "Version Ranges" in
Packit f40462
    CPAN::Meta::Spec. For example:
Packit f40462
Packit f40462
    1.3
Packit f40462
    >= 1.3
Packit f40462
    <= 1.3
Packit f40462
    == 1.3
Packit f40462
    != 1.3
Packit f40462
    > 1.3
Packit f40462
    < 1.3
Packit f40462
    >= 1.3, != 1.5, <= 2.0
Packit f40462
        A version number without an operator is equivalent to specifying a
Packit f40462
        minimum (">="). Extra whitespace is allowed.
Packit f40462
Packit f40462
  from_string_hash
Packit f40462
      my $req = CPAN::Meta::Requirements->from_string_hash( \%hash );
Packit f40462
      my $req = CPAN::Meta::Requirements->from_string_hash( \%hash, \%opts );
Packit f40462
Packit f40462
    This is an alternate constructor for a CPAN::Meta::Requirements object.
Packit f40462
    It takes a hash of module names and version requirement strings and
Packit f40462
    returns a new CPAN::Meta::Requirements object. As with
Packit f40462
    add_string_requirement, a version can be a Perl "v-string". Optionally,
Packit f40462
    you can supply a hash-reference of options, exactly as with the "new"
Packit f40462
    method.
Packit f40462
Packit f40462
SUPPORT
Packit f40462
  Bugs / Feature Requests
Packit f40462
    Please report any bugs or feature requests through the issue tracker at
Packit f40462
    <https://github.com/Perl-Toolchain-Gang/CPAN-Meta-Requirements/issues>.
Packit f40462
    You will be notified automatically of any progress on your issue.
Packit f40462
Packit f40462
  Source Code
Packit f40462
    This is open source software. The code repository is available for
Packit f40462
    public review and contribution under the terms of the license.
Packit f40462
Packit f40462
    <https://github.com/Perl-Toolchain-Gang/CPAN-Meta-Requirements>
Packit f40462
Packit f40462
      git clone https://github.com/Perl-Toolchain-Gang/CPAN-Meta-Requirements.git
Packit f40462
Packit f40462
AUTHORS
Packit f40462
    *   David Golden <dagolden@cpan.org>
Packit f40462
Packit f40462
    *   Ricardo Signes <rjbs@cpan.org>
Packit f40462
Packit f40462
CONTRIBUTORS
Packit f40462
    *   Ed J <mohawk2@users.noreply.github.com>
Packit f40462
Packit f40462
    *   Karen Etheridge <ether@cpan.org>
Packit f40462
Packit f40462
    *   Leon Timmermans <fawaka@gmail.com>
Packit f40462
Packit f40462
    *   robario <webmaster@robario.com>
Packit f40462
Packit f40462
COPYRIGHT AND LICENSE
Packit f40462
    This software is copyright (c) 2010 by David Golden and Ricardo Signes.
Packit f40462
Packit f40462
    This is free software; you can redistribute it and/or modify it under
Packit f40462
    the same terms as the Perl 5 programming language system itself.
Packit f40462