1Module::Mask(3)       User Contributed Perl Documentation      Module::Mask(3)
2
3
4

NAME

6       Module::Mask - Pretend certain modules are not installed
7

SYNOPSIS

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

DESCRIPTION

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

METHODS

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 error message to be used when the filename is not found.
109       This is normally "$filename masked by $class", but can be overridden in
110       subclasses if necessary. Carp's shortmess is used to make this message
111       appear to come from the caller, i.e. the "require" or "use" statement
112       attempting to load the file.
113
114       One possible application of this would be to make the error message
115       look more like perl's native "Could not find $filename in \@INC ...".
116

BUGS

118       Because loaded modules cannot be masked, the following module are
119       effectively never able to be masked as they are used my Module::Mask.
120
121       •   Module::Util
122
123       •   Scalar::Util
124
125       •   Carp
126
127       Plus some other core modules and pragmata used by these.
128
129       Run
130
131           perl -MModule::Mask -le 'print for keys %INC'
132
133       To see a definitive list.
134

SEE ALSO

136       perldoc -f require
137
138       Module::Util
139

AUTHOR

141       Matt Lawrence <mattlaw@cpan.org>
142
143
144
145perl v5.36.0                      2023-01-20                   Module::Mask(3)