NAME

lib::filter - Only allow some specified modules to be locateable/loadable

VERSION

This document describes version 0.08 of lib::filter (from Perl distribution lib-filter), released on 2015-06-18.

SYNOPSIS

 # 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 some more modules
 % perl -Mlib::filter=allow_noncore,0,allow,'List::MoreUtils;List::MoreUtils::PP;List::MoreUtils::XS' 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

 # 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

DESCRIPTION

This pragma installs a hook in @INC to allow only some modules from being found/loadable. This pragma is useful for testing, e.g.:

• 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:

• 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.

How a module is filtered: first, 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.

SEE ALSO

lib::none

lib::core::only

Devel::Hide

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.

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.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

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.

cpanm lib::filter

perl -MCPAN -e shell
install lib::filter