NAME

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

VERSION

This document describes version 0.03 of lib::filter (from Perl distribution lib-filter), released on 2015-05-22.

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

 # 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. fatpacked script and is 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:

• allow_core => bool (default: 1)

• allow_noncore => bool (default: 1)

• allow => str

  Add a semicolon-separated list of modules to allow.

• disallow => str

  Add a semicolon-separated list of modules to disallow. This will take precedence over any allowed list.

• allow_re => str

  Allow modules matching regex pattern.

• disallow_re => str

  Disallow modules matching regex pattern. This will take precedence over any allowed list.

• allow_list => filename

  Read a file containing list of modules to allow (one module per line).

• disallow_list => filename

  Read a file containing list of modules to disallow (one module per line). This wlll take precedence over any allowed list.

• extra_inc => str

  Add additional path to search modules in. String must be colon-separated paths.

SEE ALSO

lib::none

lib::core::only

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.