manpagez: man pages & more
man Devel::Hide(3)
Home | html | info | man
Devel::Hide(3)        User Contributed Perl Documentation       Devel::Hide(3)



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);

           or

               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'


SEE ALSO

       "perldoc -f require"

       Test::Without::Module(3)


BUGS

       bug "-from:children" and "-lexically" don't like each other.  Anything
           hidden lexically may be hidden from all child processes without
           regard for scope. Don't use them together.

       Please report any other bugs you find via CPAN RT
       <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, 2018 by Adriano R. Ferreira

       Some parts copyright (C) 2020 by David Cantrell

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

perl v5.34.1                      2021-09-28                    Devel::Hide(3)

devel-hide 0.1.500 - Generated Tue Aug 20 11:21:03 CDT 2024
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.