The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-VariousBits-3
River stage zero No dependents
1 ++
/ Module::Util::Masked

NAME

Module::Util::Masked - mangle Module::Util to recognise module masking

SYNOPSIS

 perl -MModule::Util::Masked \
      -MTest::Without::Module=Some::Thing \
      myprog.pl ...

 perl -MModule::Util::Masked \
      -MModule::Mask::Deps \
      myprog.pl ...

 # or within a script
 use Module::Util::Masked;
 use Module::Mask;
 my $mask = Module::Mask->new ('Some::Thing');

DESCRIPTION

This module mangles Module::Util functions

    find_installed()
    all_installed()
    find_in_namespace()

to have them not return modules which are "masked" by any of

    Module::Mask
    Module::Mask::Deps
    Test::Without::Module

This is meant for testing, like those masking modules are meant for testing, to pretend some modules are not available. Making the "find" functions in Module::Util reflect the masking helps code which checks module availability by a find rather than just an eval{require...} or similar.

Load Order

Module::Util::Masked should be loaded before anything which might import the Module::Util functions, so they don't grab them before the mangling.

Usually this means loading Module::Util::Masked first, or early enough, though there's no attempt to detect or enforce that currently. A -M on the command line is good

    perl -MModule::Util::Masked myprog.pl ...

Or from the ExtUtils::MakeMaker harness the same in the usual HARNESS_PERL_SWITCHES environment variable,

    HARNESS_PERL_SWITCHES="-MModule::Util::Masked" make test

Otherwise somewhere near the start of a script,

    use Module::Util::Masked;

Nothing actually changes in Module::Util until one of the above mask modules such as Test::Without::Module is loaded and asked to mask some modules. Then the mangled Module::Util will report such modules not found.

The mangling cannot be undone, but usually there's no need to. If some modules should be made visible again then ask the masking Test::Without::Module or whichever to unmask.

Implementation

Module::Mask is recognised by the object it adds to @INC. Module::Mask::Deps is a subclass of Module::Mask and is recognised likewise. Test::Without::Module is recognised by the fake_module() coderef it adds to @INC (which is not documented as such, so is a bit dependent on the Test::Without::Module implementation).

The masking object or coderef in @INC is applied at the point it appears in the @INC list. This means any directory in @INC before the mask is unaffected, the same way it's unaffected for a require etc. The masking modules normally put themselves at the start of @INC and are thus usually meant to act on everything.

SEE ALSO

Module::Util, Module::Mask, Module::Mask::Deps, Test::Without::Module

HOME PAGE

http://user42.tuxfamily.org/test-variousbits/index.html

COPYRIGHT

Copyright 2010, 2011, 2012 Kevin Ryde

Test-VariousBits is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Test-VariousBits is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Test-VariousBits. If not, see <http://www.gnu.org/licenses/>.