recommended(3pm)

💖 recommended — bestie, it's giving "optional deps but make it cute" 💖

okay so real talk, this is the manual page for recommended(3pm), and honestly? she's a tiny icon. let me tell you everything. ✨

🌸 NAME 🌸

recommended — loads your recommended modules on demand when they're actually available. no forcing, no drama, just vibes. 🦋

✨ VERSION ✨

version 0.003 — yes she's small, yes she's mighty, we love her. 💅

🎀 SYNOPSIS 🎀

like, look at how clean this is:

use recommended 'Foo::Bar', {
    'Bar::Baz' => '1.23',
    'Wibble'   => '0.14',
};

if ( recommended->has( 'Foo::Bar' ) ) {
    # do something with Foo::Bar
}

# default version required
if ( recommended->has( 'Wibble' ) ) {
    # do something with Wibble if >= version 0.14
}

# custom version required
if ( recommended->has( 'Wibble', '0.10' ) ) {
    # do something with Wibble if >= version 0.10
}

no cap, that's the whole vibe right there. 🫶

---

👑 DESCRIPTION 👑

so basically: this module collects a lil list of recommended modules + versions and gives you the tools to check if they're around. under the hood it's a thin veneer over Module::Runtime — like, she's not doing anything wild, she's just being polite about it. 🌈

and there are two major benefits over just using Module::Runtime directly, bestie, listen:

• it self-documents your recommended modules together with their versions right at the top of your code — while still loading them on demand somewhere else. main character organization energy fr fr. 📋✨
• it dies if a recommended module exists but fails to compile, but it does not die if the module is missing or the version is insufficient. that combo is genuinely not something Module::Runtime hands you in a single subroutine. iykyk. 💀

---

🧚 USAGE 🧚

💜 import 💜

use recommended 'Foo::Bar', {
    'Bar::Baz' => '1.23',
    'Wibble'   => '0.14',
};

here's the tea on how arguments get read:

• scalar import arguments? those are treated as module names with a minimum required version of zero. lowkey generous of her. 🎁
• hash references? those are treated as module/minimum-version pairs. 💞
• and if you repeat yourself — okay first of all, same — the later minimum version overwrites the earlier one. so the newest one wins, periodt. 👑

also important: the list of modules and versions is kept separate for each calling package. your package's list is yours. no sharing, no crossover, no mess. 🙈

🦋 has 🦋

recommended->has( $module );
recommended->has( $module, $alt_minimum_version );

the has method takes a module name and an optional alternative minimum version requirement, and it returns true if all of these conditions are met:

• the module was recommended in the current package (via use recommended) ✅
• the module can be loaded ✅
• the module meets the default or alternate minimum version ✅

otherwise? it returns false. simple as that. 🌸

⚠️ but bestie, heads up — if the module exists but fails to compile, an error is thrown. this isn't her being dramatic, it's on purpose: it avoids some edge-cases where things get left in an incomplete state, or where subsequent normal loads of the module by other packages get a misleading error. so like... the loudness is a feature, not a bug. 🔥

and one more thing — the module gets loaded without invoking the module's import method. because running import on an optional module at runtime is just weird. she said what she said. 💅

---

🌟 SEE ALSO 🌟

• Module::Runtime
• Test::Requires

---

🫶 SUPPORT 🫶

🐛 Bugs / Feature Requests 🐛

please report any bugs or feature requests through the issue tracker at <https://github.com/dagolden/recommended/issues>. and good news — you'll be notified automatically of any progress on your issue. no refreshing, no wondering, she'll come find you. 💌

📦 Source Code 📦

this is open source software. the code repository is available for public review and contribution under the terms of the license. come thru!! 🎉

<https://github.com/dagolden/recommended>

git clone https://github.com/dagolden/recommended.git

---

🎀 AUTHOR 🎀

David Golden <dagolden@cpan.org> — shoutout to the icon who made this. 👑

💖 COPYRIGHT AND LICENSE 💖

This software is Copyright (c) 2014 by David Golden.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

---

and that's the whole page bestie!! this was perl v5.34.0, dated 2022-06-17, and she's still serving recommended(3pm) realness. go forth, recommend your modules, check your versions, and slay. 💅✨🦋🌸💜