1Module::Mask(3) User Contributed Perl Documentation Module::Mask(3)
2
3
4
6 Module::Mask - Pretend certain modules are not installed
7
9 use Module::Mask;
10
11 {
12 my $mask = new Module::Mask ('My::Module');
13 eval { require My::Module };
14 if ($@) {
15 # ... should be called
16 }
17 else {
18 warn "require succeeded unexpectedly"
19 }
20 }
21
22 # The mask is out of scope, this should now work.
23 eval { require My::Module };
24
25 # There's also an inverted version:
26 {
27 my $mask = new Module::Mask::Inverted qw( Foo Bar );
28
29 # Now only Foo and Bar can be loaded by require:
30 eval {require Baz};
31 }
32
34 Sometimes you need to test what happens when a given module is not
35 installed. This module provides a way of temporarily hiding installed
36 modules from perl's require mechanism. The Module::Mask object adds
37 itself to @INC and blocks require calls to restricted modules.
38
39 Module::Mask will not affect modules already loaded at time of
40 instantiation.
41
43 import
44 use Module::Mask @modules;
45
46 $class->import(@modules);
47
48 Globally masks modules. This can be used to block optional modules for
49 testing purposes.
50
51 perl -MModule::Mask=MyOptionalModule my_test.pl
52
53 new
54 $obj = $class->new(@modules);
55
56 Returns a new instance of this class. Any arguments are passed to
57 mask_modules.
58
59 mask_modules
60 $obj = $obj->mask_modules(@modules)
61
62 Add the given modules to the mask. Arguments can be paths or module
63 names, module names will be stored internally as relative paths. So
64 there's no difference between the following statements:
65
66 $mask->mask_modules('My::Module');
67 $mask->mask_modules('My/Module.pm');
68
69 clear_mask
70 $obj = $obj->clear_mask()
71
72 Stops the object from masking modules by removing it from @INC. This is
73 automatically called when object goes out of scope.
74
75 set_mask
76 $obj = $obj->set_mask()
77
78 Makes the object start masking modules by adding it to @INC. This is
79 called by new().
80
81 This also has the effect of moving the object to the front of @INC
82 again, which could prove useful if @INC has been manipulated since the
83 object was first instantiated.
84
85 Calling this method on an object already in @INC won't cause multiple
86 copies to appear.
87
88 is_masked
89 $bool = $obj->is_masked($module)
90
91 Returns true if the mask object is currently masking the given module,
92 false otherwise.
93
94 Module::Mask::Inverted objects have the opposite behaviour.
95
96 list_masked
97 @modules = $obj->list_masked()
98
99 Returns a list of modules that are being masked. These are in the form
100 of relative file paths, as found in %INC.
101
102 INC
103 Implements the hook in @INC. See perldoc -f require
104
105 message
106 $message = $obj->message($filename)
107
108 Returns the "module not found" message for the given filename. This
109 should be identical to the message that perl generates, so that code
110 that detects missing modules works as expected.
111
112 If you want module masking to be more obvious, override this method
113 yourself:
114
115 @My::Mask::ISA = 'Module::Mask';
116 sub My::Mask::message = sub {
117 my ($self, $filename) = @_;
118 return "$filename masked\n";
119 }
120
121 The return value is passed directly to die in INC().
122
124 Because loaded modules cannot be masked, the following module are
125 effectively never able to be masked as they are used my Module::Mask.
126
127 · Module::Util
128
129 · Scalar::Util
130
131 · Carp
132
133 Plus some other core modules and pragmata used by these.
134
135 Run
136
137 perl -MModule::Mask -le 'print for keys %INC'
138
139 To see a definitive list.
140
142 perldoc -f require
143
144 Module::Util
145
147 Matt Lawrence <mattlaw@cpan.org>
148
149
150
151perl v5.12.3 2011-03-29 Module::Mask(3)