lib::filter - Allow/disallow loading modules
This document describes version 0.23 of lib::filter (from Perl distribution lib-filter), released on 2016-07-08.
use lib::filter %opts;
lib::filter lets you allow/disallow loading modules using some rules. It works by installing a coderef in @INC (and additionally by pruning some entries in @INC). The main use-case for this pragma is for testing.
@INC
It has been pointed out to me that for some tasks, alternatives to using this module exist, so I'll be presenting those in the examples below.
To disallow loading any module:
% perl -Mlib::filter=allow_core,0,allow_noncore,0 yourscript.pl
You can also use lib::none for this, or simply empty @INC.
To allow only core modules:
For example for testing a fatpacked script (see App::FatPacker):
% perl -Mlib::filter=allow_noncore,0 yourscript.pl
You can also use lib::core::only for this, which comes with the App-FatPacker distribution.
To only allow a specific set of modules:
% perl -Mlib::filter=allow_core,0,allow_noncore,0,allow,'XSLoader,List::Util' yourscript.pl
To allow core modules plus some additional modules:
For example to test a fatpacked script that might still require some XS modules:
# allow additional modules by pattern % perl -Mlib::filter=allow_noncore,0,allow_re,'^DateTime::.*' yourscript.pl
# allow additional modules listed in a file % perl -Mlib::filter=allow_noncore,0,allow_list,'/tmp/allow.txt' yourscript.pl # allow core modules plus additional modules found in some dirs % perl -Mlib::filter=allow_noncore,0,extra_path,'.:proj/lib' yourscript.pl # allow some non-core XS modules % perl -MModule::CoreList -Mlib::filter=filter,'sub{ return 1 if Module::CoreList->is_core($_); return 1 if m!Clone|Acme/Damn!; 0' yourscript.pl % perl -Mlib::coreplus=Clone,Acme::Damn yourscript.pl
Alternatively, you can also test by preloading the additional modules before using lib::core::only:
% perl -mClone -mAcme::Damn -Mlib::core::only yourscript.pl
To disallow some modules:
For example to test that a script can still run without a module (e.g. an optional prereq):
% perl -Mlib::filter=disallow,'YAML::XS;JSON::XS' yourscript.pl # idem, but the list of disallowed modules are retrieved from a file % perl -Mlib::filter=disallow_list,/tmp/disallow.txt yourscript.pl
Devel::Hide is another module which you can you for exactly this purpose:
% perl -MDevel::Hide=YAML::XS,JSON::XS yourscript.pl
Do custom filtering
% perl -Mlib::filter=filter,sub{not/^Foo::/} yourscript.pl
Known options:
debug => bool
If set to true, print diagnostics when filtering.
disallow => str
Add a semicolon-separated list of modules to disallow.
disallow_re => str
Add modules matching regex pattern to disallow.
disallow_list => filename
Read a file containing list of modules to disallow (one module per line).
allow => str
Add a semicolon-separated list of module names to allow.
allow_re => str
Allow modules matching regex pattern.
allow_list => filename
Read a file containing list of modules to allow (one module per line).
allow_is_recursive => bool (default: 0)
If set to 1, then will also allow modules that are required by the allowed modules (and modules that are allowed by those modules, and so on). This is convenient if you want to allow a non-trivial module, say, Moo or Moose which will require other modules too. Without this option, you will need to explicitly allow each of those modules yourself.
allow_core => bool (default: 1)
Allow core modules.
allow_noncore => bool (default: 1)
Allow non-core modules.
extra_inc => str
Add additional path to search modules in. String must be colon-separated paths.
filter => code
Do custom filtering. Code will receive module name (e.g. Foo/Bar.pm) as its argument ($_ is also localized to contained the module name, for convenience) and should return 1 if the module should be allowed.
Foo/Bar.pm
$_
How a module is filtered:
First it's checked against filter, if that option is defined
filter
then, it is checked against the disallow/disallow_re/disallow_list.
If it matches one of those options then the module is disallowed.
Otherwise it is checked against the allow/allow_re/allow_list.
If it matches one of those options and the module's path is found in the directories in @INC, then the module is allowed.
Finally, allow_core/allow_noncore is checked.
When allow_core is set to false, core directories are excluded. Likewise, when allow_noncore is set to false, non-core directories are excluded.
allow_core
allow_noncore
Please visit the project's homepage at https://metacpan.org/release/lib-filter.
Source repository is at https://github.com/perlancar/perl-lib-filter.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=lib-filter
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
Related/similar modules: lib::none, lib::core::only, Devel::Hide, Test::Without::Module.
To simulate the absence of certain programs in PATH, you can try File::Which::Patch::Hide.
perlancar <perlancar@cpan.org>
This software is copyright (c) 2016 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install lib::filter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm lib::filter
CPAN shell
perl -MCPAN -e shell install lib::filter
For more information on module installation, please visit the detailed CPAN module installation guide.