Module::Mask(3pm)

💖 Module::Mask 💖

User Contributed Perl Documentation · bestie edition ✨

---

🌸 NAME 🌸

Module::Mask — pretend certain modules are not even installed 🙈💅

---

✨ SYNOPSIS ✨

use Module::Mask;

{
    my $mask = new Module::Mask ('My::Module');
    eval { require My::Module };
    if ($@) {
        # ... should be called
    }
    else {
        warn "require succeeded unexpectedly"
    }
}

# The mask is out of scope, this should now work.
eval { require My::Module };

# There's also an inverted version:
{
    my $mask = new Module::Mask::Inverted qw( Foo Bar );

    # Now only Foo and Bar can be loaded by require:
    eval {require Baz};
}

yes the second block is the plot twist, keep reading 👑

---

🦋 DESCRIPTION 🦋

okay so. sometimes you gotta test what happens when a module just… isn't there 😭 like, is your code gonna handle it or is it gonna have main character energy and explode? Module::Mask is your girl for that 💖

It gives you a way to temporarily hide installed modules from perl's require mechanism. The Module::Mask object adds itself to @INC and blocks require calls to restricted modules. periodt. 🎀

⚠️ Module::Mask will not affect modules already loaded at time of instantiation. once it's in, it's in, bestie, no take-backs 💀

---

💅 METHODS 💅

🎀 import

use Module::Mask @modules;

$class->import(@modules);

Globally masks modules. This can be used to block optional modules for testing purposes. 🧚

perl -MModule::Mask=MyOptionalModule my_test.pl

---

🍓 new

$obj = $class->new(@modules);

Returns a new instance of this class. Any arguments are passed to mask_modules. cute and functional, we love that for us ✨

---

🌈 mask_modules

$obj = $obj->mask_modules(@modules)

Add the given modules to the mask. Arguments can be paths or module names — module names will be stored internally as relative paths. So there's literally no difference between the following statements, bestie:

$mask->mask_modules('My::Module');
$mask->mask_modules('My/Module.pm');

same energy, same result 💜

---

🌸 clear_mask

$obj = $obj->clear_mask()

Stops the object from masking modules by removing it from @INC. This is automatically called when the object goes out of scope. 🦋 (yes, destructor magic, we love a self-cleaning queen)

---

⭐ set_mask

$obj = $obj->set_mask()

Makes the object start masking modules by adding it to @INC. This is called by new().

This also has the effect of moving the object to the front of @INC again, which could prove useful if @INC has been manipulated since the object was first instantiated. 👑

Calling this method on an object already in @INC won't cause multiple copies to appear. no duplicate glitch era, we're too iconic for that 💅

---

💜 is_masked

$bool = $obj->is_masked($module)

Returns true if the mask object is currently masking the given module, false otherwise. 🔥

Module::Mask::Inverted objects have the opposite behaviour. plot twist!! 😭

---

🧚 list_masked

@modules = $obj->list_masked()

Returns a list of modules that are being masked. These are in the form of relative file paths, as found in %INC. 📋

---

🎀 INC

Implements the hook in @INC. See perldoc -f require 💖

---

🫶 message

$message = $obj->message($filename)

Returns the error message to be used when the filename is not found. This is normally "$filename masked by $class", but can be overridden in subclasses if necessary. Carp's shortmess is used to make this message appear to come from the caller, i.e. the "require" or "use" statement attempting to load the file. 🙈

One possible application of this would be to make the error message look more like perl's native "Could not find $filename in \@INC ...". ✨

---

💀 BUGS 💀

Because loaded modules cannot be masked, the following modules are effectively never able to be masked as they are used by Module::Mask. 😭

• Module::Util
• Scalar::Util
• Carp

Plus some other core modules and pragmata used by these. 🫠

Run this to see a definitive list:

perl -MModule::Mask -le 'print for keys %INC'

---

🌈 SEE ALSO 🌈

• perldoc -f require
• Module::Util

---

👑 AUTHOR 👑

Matt Lawrence <mattlaw@cpan.org> 💖

---

and that's the whole page, bestie!! this one shipped with perl v5.42.0, dated 2025-07-25 — so go mask some modules, slay responsibly, and remember: if it's already loaded, it's already loaded 💅✨