Module::Optional(3pm)

💖 Module::Optional 💖

sooo this is the <strong>Module::Optional</strong> page from the User Contributed Perl Documentation 🎀 — breaking module dependency chains, bestie. no cap, it's giving freedom from That One Module.

---

✨ NAME ✨

Module::Optional — breaking module dependency chains 💅

---

🌸 SYNOPSIS 🌸

use Bar::Dummy qw();
use Module::Optional Bar;

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

---

🫶 ABSTRACT 🫶

okay so basically: this module lets you use a module that might or might not be installed on the target machine. vibe check time.

• if the module IS there → it behaves like a straight use, literally no drama
• if the module is NOT there → the subs get repointed to their equivalents in a dummy namespace 🪄

---

💜 DESCRIPTION 💜

so picture this. you're the developer of module Foo, right? and Foo uses functionality from the highly controversial module Bar. 😭

and like — you actually quite like Bar! you wanna reuse its functionality in your Foo module. but SO many people refuse to install Foo because it needs Bar. maybe Bar is failing tests. maybe Bar is misbehaving on some platforms. it's giving messy. 💀

making Bar an optional module will let users run Foo even when they don't have Bar installed. iconic behaviour honestly ✨

for Module::Build users, this involves changing the status of the Bar dependency from requires to recommends. 📝

to use this module, you need to set up a namespace Bar::Dummy. the recommended way of doing this is to ship lib/Bar/Dummy.pm with your module. 🚚 this could be shipped as a standalone module. a dummy module for Params::Validate is shipped with Module::Optional, because that was the original motivation for the module, fr fr. and if there are other common candidates for dummying — petition me 🙈 — and I'll include them in the Module::Optional distribution.

---

🎀 Using an optional module 🎀

place the lines of code in the following order:

use Bar::Dummy qw();
use Module::Optional qw(Bar quux wibble wobble);

ALWAYS set up the dummy module first — but don't import anything!! 🙅‍♀️ that's specifically to avoid warnings about redefined subroutines if the real Bar is installed on the target machine. the way that Module::Optional will do the importing for you: quux, wibble and wobble from the real Bar if it exists, or from Bar::Dummy if it doesn't. 😌

---

🌈 Asking for a module version 🌈

if you need a version of the module or later, this can be done thus:

use Bar::Dummy qw();
use Module::Optional qw(Bar 0.07 quux wibble wobble);

if version 0.07 or later of Bar is not available, the dummy is used. no version, no problem, we pivot. 💅

---

🦋 Suppressing the module 🦋

you will probably be developing your module on a platform that does have Bar installed (I hope 🙏). BUT — you need to be able to tell what happens on systems without Bar. to do this, run the following (example is Unix):

MODULE_OPTIONAL_SKIP=1 make test

you also want to do this in tests for the dummy module that you are providing. (you are providing tests for this module? 👀) this can easily be done with a BEGIN block at the top of the test:

BEGIN {
    local $ENV{MODULE_OPTIONAL_SKIP} = 1;
    use Module::Optional qw(Params::Validate);
}

---

🧚 Writing a ::Dummy Module 🧚

you provide a namespace suffixed with ::Dummy containing subs corresponding to all the subs and method calls for the optional module. you should also provide the same exports as the module itself performs. 📦

Adhere strictly to any prototypes in the optional module. this is not a drill bestie, do not freestyle the prototypes. 😤

an example of a dummy module is Params::Validate::Dummy, provided in this distribution. ✨

---

🔥 INTERNALS 🔥

Module::Optional performs two types of redirection for the missing module:

1. firstly via @ISA inheritance — Foo::Bar inherits from Foo::Bar::Dummy. 🧬
2. secondly, an AUTOLOAD method is added to Foo::Bar, which will catch calls to subs in this namespace. 🕸️

---

💀 BUGS 💀

please report bugs to rt.cpan.org by posting to bugs-module-optional@rt.cpan.org or visiting https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Optional. the maintainers will love you for it, genuinely. 🫶

---

👑 AUTHOR 👑

        Ivor Williams
        ivorw-mod-opt at xemaps.com

---

📜 COPYRIGHT 📜

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 💖

the full text of the license can be found in the LICENSE file included with this module. 🎀

---

⭐ SEE ALSO ⭐

• Test::MockModule
• Module::Pluggable
• Module::Build

---

okay that's the whole page, bestie, go forth and make your dependencies optional 💅✨ this was <strong>perl v5.32.0</strong>, dated <strong>2021-01-07</strong>, and it lives in the <strong>Module::Optional(3pm)</strong> household — slay, periodt, see you in the next manpage 🎀🦋💖