/ 
Module-Mask-Deps-0.07
River stage zero No dependents
/ Module::Mask::Deps

NAME

Module::Mask::Deps - Mask modules not listed as dependencies

SYNOPSIS

Cause your test suite to blow up if you require a module not listed as a requirement in META.yml or META.json.

perl Build.PL
HARNESS_PERL_SWITCHES=-MModule::Mask::Deps ./Build test

Or use directly in your testing code:

use Module::Mask::Deps;

BEGIN {
    # die if an unlisted module is used
    use_ok('My::Module');
}

# turn off masking (at compile time)
no Module::Mask::Deps;

# .. or at run-time
unimport Module::Mask::Deps;

Or use lexically:

require Module::Mask::Deps;

{
    my $mask = new Module::Mask::Deps;

    # Non-dependencies masked until end-of-scope.

    # ... 
}

require Arbitrary::Module;

DESCRIPTION

This module aims to help module developers keep track of their dependencies by only allowing modules to be loaded if they are in core or are listed as dependencies.

It uses Module::CoreList and Parse::CPAN::Meta to build its list of declared dependant modules.

METHODS

import

use Module::Mask::Deps;

import Module::Mask::Deps;

Causes a Module::Mask::Deps object to be created as $Module::Mask::Deps::Mask. This means that when called with use the mask object is is in scope at compile time and therefore should affect all subsequent use and require statements in the program.

unimport

unimport Module::Mask::Deps

no Module::Mask::Deps;

Stops the mask from working until import is called again. See clear_mask in Module::Mask

Note that no Module::Mask::Deps occurs at compile time and is not lexical in the same way as no strict and <no warnings> are.

new

$obj = $class->new()

Returns a new Module::Mask::Deps object. See Module::Mask for details about how modules are masked.

set_mask

$obj = $obj->set_mask()

Overloaded from Module::Mask to place the mask object after any relative paths at the beginning of @INC.

Typically, in a testing environment, local paths are unshifted into @INC by blib.pm, lib.pm or command-line switches. We don't want the mask to affect those paths.

Also, relative paths passed to require will not be masked.

# Will check @INC but won't be masked
require 't/my_script.pl';

# Won't even check @INC
require './t/my_script.pl';

get_deps

@deps = $class->get_deps()

Returns current dependencies as defined in either META.json or META.yml, checked in that order. This is used internally by import and new, so there's no need to call it directly.

It returns all explicitly defined dependencies, plus all core dependencies for the appropriate version of Perl, i.e. either the minimum version specified in the meta file or the currently running version.

The sections of the metadata checked for dependencies are:

requires
test_requires
build_requires

BUGS AND LIMITATIONS

Like Module::Mask, already loaded modules cannot be masked. This means that dependencies of Module::Mask::Deps can never be masked.

To see a full list of modules for which this applies, run:

perl -le 'require Module::Mask::Deps; print for keys %INC'

DIAGNOSTICS

All error messages are prefixes by the name of the calling class, e.g.

Module::Mask::Deps: Couldn't find dependencies

The following fatal errors can occur:

  • Couldn't find dependencies

    The class couldn't find dependencies for the current distribution.

    This may mean that META.yml or META.json do not (yet) exist. Running make dist or make distmeta (or equivalents) may fix this.

    Further information about the error might be provided on subsequent lines.

  • Couldn't find core modules for perl $version

    The given perl version couldn't be found in %Module::CoreList::version, you might need to upgrade Module::CoreList, or the perl version specified in Build.PL might be invalid. Otherwise, please report it as a bug.

SEE ALSO

Module::Mask, Module::CoreList

AUTHOR

Matt Lawrence <mattlaw@cpan.org>