1Devel::Hide(3)        User Contributed Perl Documentation       Devel::Hide(3)
2
3
4

NAME

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

SYNOPSIS

10           # hide modules globally, across the entire process
11
12           use Devel::Hide qw(Module/ToHide.pm);
13           require Module::ToHide; # fails
14
15           use Devel::Hide qw(Test::Pod Test::Pod::Coverage);
16           require Test::More; # ok
17           use Test::Pod 1.18; # fails
18
19           # hide modules lexically
20           {
21               use Devel::Hide qw(-lexically Foo::Bar);
22               # this will fail to load
23               eval 'use Foo::Bar';
24           }
25           # but this will load
26           use Foo::Bar;
27
28       Other common usage patterns:
29
30           $ perl -MDevel::Hide=Module::ToHide Makefile.PL
31           $ perl -MDevel::Hide=Module::ToHide,Test::Pod Makefile.PL
32
33           $ PERL5OPT=-MDevel::Hide
34           $ DEVEL_HIDE_PM='Module::ToHide Test::Pod'
35           $ export PERL5OPT DEVEL_HIDE_PM
36           $ perl Makefile.PL
37

COMPATIBILITY

39       global hiding
40           At some point global hiding may go away and only lexical hiding be
41           supported. At that point support for perl versions below 5.10 will
42           be dropped. There will be at least a two year deprecation cycle
43           before that happens.
44
45           You are strongly encouraged to only use lexical hiding and to
46           update existing code.
47
48       perl 5.6
49           Support will be dropped at some point after 2022-01-01 with no
50           further warning. This is because bugs in older perls prevent some
51           code improvements. See commit dd27e50 in the repository if you care
52           to know what those are.
53

DESCRIPTION

55       Given a list of Perl modules/filenames, this module makes "require" and
56       "use" statements fail (no matter the specified files/modules are
57       installed or not).
58
59       They die with a message like:
60
61           Can't locate Module/ToHide.pm in @INC (hidden)
62
63       The original intent of this module is to allow Perl developers to test
64       for alternative behavior when some modules are not available. In a Perl
65       installation, where many modules are already installed, there is a
66       chance to screw things up because you take for granted things that may
67       not be there in other machines.
68
69       For example, to test if your distribution does the right thing when a
70       module is missing, you can do
71
72           perl -MDevel::Hide=Test::Pod Makefile.PL
73
74       forcing "Test::Pod" to not be found (whether it is installed or not).
75
76       Another use case is to force a module which can choose between two
77       requisites to use the one which is not the default.  For example,
78       "XML::Simple" needs a parser module and may use "XML::Parser" or
79       "XML::SAX" (preferring the latter).  If you have both of them
80       installed, it will always try "XML::SAX".  But you can say:
81
82           perl -MDevel::Hide=XML::SAX script_which_uses_xml_simple.pl
83
84       NOTE. This module does not use Carp. As said before, denial dies.
85
86       This module is pretty trivial. It uses a code reference in @INC to get
87       rid of specific modules during require - denying they can be
88       successfully loaded and stopping the search before they have a chance
89       to be found.
90
91       There are three alternative ways to include modules in the hidden list:
92
93       import()
94           this is probably the most commonly used method, called
95           automagically when you do this:
96
97               use Devel::Hide qw(Foo Bar::Baz);
98
99           or
100
101               perl -MDevel::Hide=...
102
103       setting @Devel::Hide::HIDDEN
104       environment variable DEVEL_HIDE_PM
105           both of these two only support 'global' hiding, whereas "import()"
106           supports lexical hiding as well.
107
108       Optionally, you can provide some arguments *before* the list of
109       modules:
110
111       -from:children
112           propagate the list of hidden modules to your process' child
113           processes. This works by populating "PERL5OPT", and is incompatible
114           with Taint mode, as explained in perlrun. Of course, this is
115           unnecessary if your child processes are just forks of the current
116           one.
117
118       -lexically
119           This is only available on perl 5.10.0 and later. It is a fatal
120           error to try to use it on an older perl.
121
122           Everything following this will only have effect until the end of
123           the current scope. Yes, that includes "-quiet".
124
125       -quiet
126           suppresses diagnostic output. You will still get told about errors.
127           This is passed to child processes if -from:children is in effect.
128

CAVEATS

130       There is some interaction between "lib" and this module
131
132           use Devel::Hide qw(Module/ToHide.pm);
133           use lib qw(my_lib);
134
135       In this case, 'my_lib' enters the include path before the Devel::Hide
136       hook and if Module/ToHide.pm is found in 'my_lib', it succeeds. More
137       generally, any code that adds anything to the front of the @INC list
138       after Devel::Hide is loaded will have this effect.
139
140       Also for modules that were loaded before Devel::Hide, "require" and
141       "use" succeeds.
142
143       Since 0.0005, Devel::Hide warns about modules already loaded.
144
145           $ perl -MDevel::Hide=Devel::Hide -e ''
146           Devel::Hide: Too late to hide Devel/Hide.pm
147

EXPORTS

149       Nothing is exported.
150

ENVIRONMENT VARIABLES

152       DEVEL_HIDE_PM - if defined, the list of modules is added
153          to the list of hidden modules
154
155       DEVEL_HIDE_VERBOSE - on by default. If off, suppresses
156          the initial message which shows the list of hidden modules
157          in effect
158
159       PERL5OPT - used if you specify '-from:children'
160

SEE ALSO

162       "perldoc -f require"
163
164       Test::Without::Module
165

BUGS

167       bug "-from:children" and "-lexically" don't like each other.  Anything
168           hidden lexically may be hidden from all child processes without
169           regard for scope. Don't use them together.
170
171       Please report any other bugs you find via CPAN RT
172       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Hide>.
173

AUTHORS

175       Adriano R. Ferreira, <ferreira@cpan.org>
176
177       with contributions from David Cantrell <dcantrell@cpan.org>
178
180       Copyright (C) 2005-2007, 2018 by Adriano R. Ferreira
181
182       Some parts copyright (C) 2020 by David Cantrell
183
184       This library is free software; you can redistribute it and/or modify it
185       under the same terms as Perl itself.
186
187
188
189perl v5.32.1                      2021-01-27                    Devel::Hide(3)
Impressum