/ 
lib-filter-0.18
River stage three • 5 direct dependents • 693 total dependents
/ lib::filter

NAME

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

VERSION

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

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

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:

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

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.

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