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.

      * 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 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_path,'.: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 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

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

