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