NAME

lib::filter - Allow/disallow loading modules

VERSION

This document describes version 0.281 of lib::filter (from Perl distribution lib-filter), released on 2021-08-29.

SYNOPSIS

 use lib::filter %opts;

DESCRIPTION

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.

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 yourself, e.g.:
```
 {
     local @INC = ();
     ...
 }
    
```
To no-op instead of disallowing, see lib::noop::all.
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 no-op instead of disallowing, see lib::noop::except.

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_inc,'.: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 allow a module and recursively all other modules that the module requires
This is convenient when we want to allow a non-trivial module which itself uses some other modules, e.g. Moo or Moose:
```
 % perl -Mlib::filter=allow_noncore,0,allow,Moo,allow_is_recursive=0
    
```

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

To no-op instead of disallowing, see lib::noop.

Do custom filtering

 % perl -Mlib::filter=filter,sub{not/^Foo::/} yourscript.pl

OPTIONS

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.

How a module is filtered:

First it's checked against "filter", if that option is defined
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.
If "allow_is_recursive" is true, check the requirer.
If the calling package is already in %INC, we allow that. For example, if we allow "Moo" and "Moo" calls Moo::_strictures and Module::Runtime, we will also allow them. Later if "Moo::_strictures" tries to load strictures, we also allow it, and so on.
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.

ENVIRONMENT

PERL_LIB_FILTER_DEBUG

Boolean. Sets the default for the "debug" option.

HOMEPAGE

Please visit the project's homepage at <https://metacpan.org/release/lib-filter>.

SOURCE

Source repository is at <https://github.com/perlancar/perl-lib-filter>.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTORS

A. Sinan Unur <nanis@cpan.org>
Olivier Mengué <dolmen@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

 % prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

BUGS

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.