1Devel::Hide(3) User Contributed Perl Documentation Devel::Hide(3)
2
6 Devel::Hide - Forces the unavailability of specified Perl modules (for
7 testing)
8
10 # hide modules globally, across the entire process
11 use Devel::Hide qw(Module/ToHide.pm);
13 require Module::ToHide; # fails
14 use Devel::Hide qw(Test::Pod Test::Pod::Coverage);
16 require Test::More; # ok
17 use Test::Pod 1.18; # fails
18 # 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 Other common usage patterns:
29 $ perl -MDevel::Hide=Module::ToHide Makefile.PL
31 $ perl -MDevel::Hide=Module::ToHide,Test::Pod Makefile.PL
32 $ PERL5OPT=-MDevel::Hide
34 $ DEVEL_HIDE_PM='Module::ToHide Test::Pod'
35 $ export PERL5OPT DEVEL_HIDE_PM
36 $ perl Makefile.PL
37
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 You are strongly encouraged to only use lexical hiding and to
46 update existing code.
47 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
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 They die with a message like:
60 Can't locate Module/ToHide.pm in @INC (hidden)
62 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 For example, to test if your distribution does the right thing when a
70 module is missing, you can do
71 perl -MDevel::Hide=Test::Pod Makefile.PL
73 forcing "Test::Pod" to not be found (whether it is installed or not).
75 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 perl -MDevel::Hide=XML::SAX script_which_uses_xml_simple.pl
83 NOTE. This module does not use Carp. As said before, denial dies.
85 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 There are three alternative ways to include modules in the hidden list:
92 import()
94 this is probably the most commonly used method, called
95 automagically when you do this:
96 use Devel::Hide qw(Foo Bar::Baz);
98 or
100 perl -MDevel::Hide=...
102 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 Optionally, you can provide some arguments *before* the list of
109 modules:
110 -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 -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 Everything following this will only have effect until the end of
123 the current scope. Yes, that includes "-quiet".
124 -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
130 There is some interaction between "lib" and this module
131 use Devel::Hide qw(Module/ToHide.pm);
133 use lib qw(my_lib);
134 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 Also for modules that were loaded before Devel::Hide, "require" and
141 "use" succeeds.
142 Since 0.0005, Devel::Hide warns about modules already loaded.
144 $ perl -MDevel::Hide=Devel::Hide -e ''
146 Devel::Hide: Too late to hide Devel/Hide.pm
147
149 Nothing is exported.
150
152 DEVEL_HIDE_PM - if defined, the list of modules is added
153 to the list of hidden modules
154 DEVEL_HIDE_VERBOSE - on by default. If off, suppresses
156 the initial message which shows the list of hidden modules
157 in effect
158 PERL5OPT - used if you specify '-from:children'
160
162 "perldoc -f require"
163 Test::Without::Module
165
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 Please report any other bugs you find via CPAN RT
172 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Hide>.
173
175 Adriano R. Ferreira, <ferreira@cpan.org>
176 with contributions from David Cantrell <dcantrell@cpan.org>
178
180 Copyright (C) 2005-2007, 2018 by Adriano R. Ferreira
181 Some parts copyright (C) 2020 by David Cantrell
183 This library is free software; you can redistribute it and/or modify it
185 under the same terms as Perl itself.
186perl v5.38.0 2023-07-20 Devel::Hide(3)