rootr.net : rootr.net : Devel::Hide(3pm)

:: RootR ::

Secure Inter-Network Operations

Devel::Hide(3pm) - phpMan

Devel::Hide(3pm) User Contributed Perl Documentation Devel::Hide(3pm)

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

SYNOPSIS
# hide modules globally, across the entire process

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

# hide modules lexically
{
use Devel::Hide qw(-lexically Foo::Bar);
# this will fail to load
eval 'use Foo::Bar';
}
# but this will load
use Foo::Bar;

Other common usage patterns:

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

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

COMPATIBILITY
global hiding
At some point global hiding may go away and only lexical hiding be supported. At that
point support for perl versions below 5.10 will be dropped. There will be at least a
two year deprecation cycle before that happens.

You are strongly encouraged to only use lexical hiding and to update existing code.

perl 5.6
Support will be dropped at some point after 2022-01-01 with no further warning. This
is because bugs in older perls prevent some code improvements. See commit dd27e50 in
the repository if you care to know what those are.

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 in @INC (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:

import()
this is probably the most commonly used method, called automagically when you do this:

use Devel::Hide qw(Foo Bar::Baz);

perl -MDevel::Hide=...

setting @Devel::Hide::HIDDEN
environment variable DEVEL_HIDE_PM
both of these two only support 'global' hiding, whereas "import()" supports lexical
hiding as well.

Optionally, you can provide some arguments *before* the list of modules:

-from:children
propagate the list of hidden modules to your process' child processes. This works by
populating "PERL5OPT", and is incompatible with Taint mode, as explained in perlrun.
Of course, this is unnecessary if your child processes are just forks of the current
one.

-lexically
This is only available on perl 5.10.0 and later. It is a fatal error to try to use it
on an older perl.

Everything following this will only have effect until the end of the current scope.
Yes, that includes "-quiet".

-quiet
suppresses diagnostic output. You will still get told about errors. This is passed to
child processes if -from:children is in effect.

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. More generally, any code that adds
anything to the front of the @INC list after Devel::Hide is loaded will have this effect.

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, suppresses
the initial message which shows the list of hidden modules
in effect

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