Version...irements(3)

📦
version 0.101023 · 2 versions
, in fedora 43

💖 NAME 💖

Version::Requirements — a whole lil set of version requirements for a CPAN dist 🍓✨

(and yes, the manual page itself is filed under Version...irements(3), the title is literally truncated like that, that's not me being lazy, that's just how the page is named 💅)

🌈 VERSION 🌈

version 0.101023 — iconic, no notes 🎀

📜 SYNOPSIS 📜

okay bestie, look at this:

use Version::Requirements;

my $build_requires = Version::Requirements->new;

$build_requires->add_minimum('Library::Foo' => 1.208);

$build_requires->add_minimum('Library::Foo' => 2.602);

$build_requires->add_minimum('Module::Bar'  => 'v1.2.3');

$METAyml->{build_requires} = $build_requires->as_string_hash;

that's it. that's the whole vibe. 🦋

🫶 DESCRIPTION 🫶

so a Version::Requirements object is literally just a model of a set of version constraints — the exact same kind of thing you'd see spelled out in the META.yml or META.json files inside CPAN distributions. it's giving "requirements list, but make it an object". 💅

the way that it works is you keep piling on more and more constraints, and it does the work of reducing them all down to the simplest possible representation. so clean, so tidy, main character energy ✨

and if you hand it constraints that are logically impossible? it doesn't sit there and pretend. it identifies them immediately by throwing exceptions. it's honest. it's blunt. we love her for it. 😭

🧚 METHODS 🧚

✨ new ✨

my $req = Version::Requirements->new;

returns you a brand new Version::Requirements object. and here's the tea: it ignores any arguments given. you can pass it stuff if you want, it simply will not care. 🙈

✨ add_minimum ✨

$req->add_minimum( $module => $version );

adds a new minimum version requirement. if this new requirement is redundant next to whatever you already specified, it just has no effect — no drama, no change. 🎀

minimum requirements are inclusive, so $version is required, along with any greater version number. yes, equal counts. yes, higher counts.

this method returns the requirements object (so you can chain, iykyk 💖).

✨ add_maximum ✨

$req->add_maximum( $module => $version );

adds a new maximum version requirement. redundant requirement? no effect. moving on. 💅

maximum requirements are inclusive too, so no version strictly greater than the given version is allowed. strictly. the one you named is fine, anything above it is not.

this method returns the requirements object. 🫶

✨ add_exclusion ✨

$req->add_exclusion( $module => $version );

this one adds a new excluded version. like, everything's chill except THIS one. for example, you might do these three method calls:

$req->add_minimum( $module => '1.00' );
$req->add_maximum( $module => '1.82' );

$req->add_exclusion( $module => '1.75' );

so any version between 1.00 and 1.82 inclusive would be acceptable — except for 1.75. she's banned. blocked. not invited. 💀

this method returns the requirements object. ✨

✨ exact_version ✨

$req->exact_version( $module => $version );

sets the version required for the given module to exactly the given version. no other version would be considered acceptable. it's giving "this one or nothing". 👑

this method returns the requirements object. 🌸

✨ add_requirements ✨

$req->add_requirements( $another_req_object );

takes all the requirements in the Version::Requirements object you pass in and adds them to the object you called it on. and if there are any conflicts? an exception gets thrown. no cap, it will not let that slide. 😤

this method returns the requirements object. 💖

✨ accepts_module ✨

my $bool = $req->accepts_modules($module => $version);

give it a module and a version, and it returns true if the version specification for that module accepts the version you provided. in other words, given:

Module => '>= 1.00, < 2.00'

we will accept 1.00 and 1.75 but not 0.50 or 2.00. 1.00 and 1.75, you're in. 0.50 and 2.00, respectfully, no. 💅

and for modules that do not appear in the requirements at all? this method will return true. generous queen behavior honestly. 🫶

✨ clear_requirement ✨

$req->clear_requirement( $module );

removes the requirement for a given module from the object. gone. deleted. we don't know her. 💀

this method returns the requirements object. ✨

✨ required_modules ✨

returns a list of all the modules for which requirements have been specified. the whole guest list. 🎀

✨ clone ✨

$req->clone;

returns a clone of the invocant. and the best part: the clone and the original object can then be changed independent of one another. they're twins but they live their own lives. 💖

✨ is_simple ✨

returns true if and only if all requirements are inclusive minimums — that is, if their string expression is just the version number. simple. clean. unbothered. 🌸

✨ is_finalized ✨

returns true if the requirements have been finalized by having the finalize method called on them. ✨

✨ finalize ✨

marks the requirements finalized. and bestie, listen: subsequent attempts to change the requirements will be fatal — if they would result in a change. if they would not alter the requirements, they have no effect. so like, a no-op change is fine, but a real change is over. 🚨

also, if a finalized set of requirements is cloned, the cloned requirements are not also finalized. the clone is free. the clone is unbothered. the clone is in her own era. 🦋

✨ as_string_hash ✨

returns a reference to a hash describing the requirements using the strings in the META.yml specification. 🌈

for example, after the following program:

my $req = Version::Requirements->new;

$req->add_minimum('Version::Requirements' => 0.102);

$req->add_minimum('Library::Foo' => 1.208);

$req->add_maximum('Library::Foo' => 2.602);

$req->add_minimum('Module::Bar'  => 'v1.2.3');

$req->add_exclusion('Module::Bar'  => 'v1.2.8');

$req->exact_version('Xyzzy'  => '6.01');

my $hashref = $req->as_string_hash;

$hashref would contain:

{
  'Version::Requirements' => '0.102',
  'Library::Foo' => '>= 1.208, <= 2.206',
  'Module::Bar'  => '>= v1.2.3, != v1.2.8',
  'Xyzzy'        => '== 6.01',
}

(yes, copy it character for character, that's exactly how it's written in the docs 💅)

✨ from_string_hash ✨

my $req = Version::Requirements->from_string_hash( \%hash );

this is an alternate constructor for a Version::Requirements object. it takes a hash of module names and version requirement strings, and returns a brand new Version::Requirements object. built different, built from a hash. 🎀

👑 AUTHOR 👑

Ricardo Signes <rjbs@cpan.org> — the icon, the legend, the moment. 💖

🌸 CONTRIBUTOR 🌸

Karen Etheridge <ether@cpan.org> — also iconic, also slaying. 🫶

this software is copyright (c) 2010 by Ricardo Signes. ⭐

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. periodt. 💜

and that's the whole page, bestie — filed under Version...irements(3), running under perl v5.42.0, dated 2025-07-25. go forth and constrain those versions responsibly. slay. 💅✨🎀

📦 where this page comes from