lib::filter - Only allow some specified modules to be locateable/loadable
This document describes version 0.18 of lib::filter (from Perl distribution lib-filter), released on 2015-06-29.
# equivalent to -Mlib::none % perl -Mlib::filter=allow_core,0,allow_noncore,0 yourscript.pl # equivalent to -Mlib::core::only % perl -Mlib::filter=allow_noncore,0 yourscript.pl # only allow a specific set of modules % perl -Mlib::filter=allow_core,0,allow_noncore,0,allow,'XSLoader,List::Util' yourscript.pl # allow core modules plus additional modules by pattern % perl -Mlib::filter=allow_noncore,0,allow_re,'^DateTime::.*' yourscript.pl # allow core modules plus 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 core modules plus 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 # disallow some modules (for testing/simulating the non-availability of a # module, pretending that a module does not exist) % 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 # custom filtering (disallow Foo::*)xs % perl -Mlib::filter=filter,sub{not/^Foo::/} yourscript.pl
This pragma installs a hook in @INC to allow only some modules from being found/loadable. This pragma is useful for testing, e.g.:
@INC
test whether a fatpacked script really can run with just core modules;
test that a program/module can function when an optional (recommends/suggests) dependency is absent;
test that a test script can function (i.e. skip tests) when an optional dependency is absent;
more flexible than lib::none and lib::core::only.
lib::none is absolutely ruthless: your fatpacked script must fatpack all modules (including things like strict, warnings) as lib::none empties @INC and removes perl's ability to load any more modules.
lib::core::only only puts core paths in @INC so your fatpacked script must contain all non-core modules. But this is also too restrictive in some cases because we cannot fatpack XS modules and want to let the script load those from filesystem.
lib::filter makes it possible for you to, e.g. only allow core modules, plus some other modules (like some XS modules).
To use this pragma:
use lib::filter %opts;
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_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
lib::none
lib::core::only
Devel::Hide
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.
perlancar <perlancar@cpan.org>
This software is copyright (c) 2015 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.