NAME

       Devel::Hide - Forces the unavailability of specified Perl modules (for testing)

SYNOPSIS

           use Devel::Hide qw(Module/ToHide.pm);
           require Module::ToHide; # fails

           use Devel::Hide qw(Test::Pod Test::Pod::Coverage);
           require Test::More; # ok
           use Test::Pod 1.18; # fails

       Other common usage patterns:

           $ perl -MDevel::Hide=Module::ToHide Makefile.PL

           bash$ PERL5OPT=MDevel::Hide
           bash$ DEVEL_HIDE_PM='Module::Which Test::Pod'
           bash$ export PERL5OPT DEVEL_HIDE_PM
           bash$ perl Makefile.PL

       outputs (like blib)

           Devel::Hide hides Module::Which, Test::Pod, etc.

DESCRIPTION

       Given a list of Perl modules/filenames, this module makes "require" and "use" statements fail (no matter
       the specified files/modules are installed or not).

       They die with a message like:

           Can't locate Module/ToHide.pm (hidden)

       The original intent of this module is to allow Perl developers to test for alternative behavior when some
       modules are not available. In a Perl installation, where many modules are already installed, there is a
       chance to screw things up because you take for granted things that may not be there in other machines.

       For example, to test if your distribution does the right thing when a module is missing, you can do

           perl -MDevel::Hide=Test::Pod Makefile.PL

       forcing "Test::Pod" to not be found (whether it is installed or not).

       Another use case is to force a module which can choose between two requisites to use the one which is not
       the default.  For example, "XML::Simple" needs a parser module and may use "XML::Parser" or "XML::SAX"
       (preferring the latter).  If you have both of them installed, it will always try "XML::SAX".  But you can
       say:

           perl -MDevel::Hide=XML::SAX script_which_uses_xml_simple.pl

       NOTE. This module does not use Carp. As said before, denial dies.

       This module is pretty trivial. It uses a code reference in @INC to get rid of specific modules during
       require - denying they can be successfully loaded and stopping the search before they have a chance to be
       found.

       There are three alternative ways to include modules in the hidden list:

       •   setting @Devel::Hide::HIDDEN

       •   environment variable DEVEL_HIDE_PM

       •   import()

       Optionally, you can propagate the list of hidden modules to your process' child processes, by passing
       '-from:children' as the first option when you use() this module. This works by populating "PERL5OPT", and
       is incompatible with Taint mode, as explained in perlrun.

   CAVEATS
       There is some interaction between "lib" and this module

           use Devel::Hide qw(Module/ToHide.pm);
           use lib qw(my_lib);

       In this case, 'my_lib' enters the include path before the Devel::Hide hook and if Module/ToHide.pm is
       found in 'my_lib', it succeeds.

       Also for modules that were loaded before Devel::Hide, "require" and "use" succeeds.

       Since 0.0005, Devel::Hide warns about modules already loaded.

           $ perl -MDevel::Hide=Devel::Hide -e ''
           Devel::Hide: Too late to hide Devel/Hide.pm

   EXPORTS
       Nothing is exported.

ENVIRONMENT VARIABLES

       DEVEL_HIDE_PM - if defined, the list of modules is added
          to the list of hidden modules

       DEVEL_HIDE_VERBOSE - on by default. If off, supresses
          the initial message which shows the list of hidden modules
          in effect

       PERL5OPT - used if you specify '-from:children'

SEE ALSO

       "perldoc -f require"

       Test::Without::Module

BUGS

       Please report bugs via CPAN RT http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Hide
       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Hide>.

AUTHORS

       Adriano R. Ferreira, <ferreira@cpan.org>

       with contributions from David Cantrell <dcantrell@cpan.org>

COPYRIGHT AND LICENSE

       Copyright (C) 2005-2007 by Adriano R. Ferreira

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