/ 
Module-Mask-Deps-0.01
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 Build.PL:

perl Build.PL
PERL_HARNESS_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 either Module::Build or ExtUtils::MakeMaker to build its list of declared dependant modules.

Under Module::Build, the core module collection for the declared minimum perl version is used instead of the current core list.

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 int he 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.

get_deps

@deps = $class->get_deps()

Returns current dependencies as defined in either Build.PL or Makefile.PL. 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.

Module::Build

If Build.PL exists, Module::Build->current is used to obtain a Module::Build object, and its requires and build_requires fields are used as dependencies.

This means that the dependencies can only be picked up if Build.PL has already been run.

If a particular perl version is specified as a dependency, then the list of core modules for that version of perl is used.

Note that modules in recommends are not included.

ExtUtils::MakeMaker

If Makefile.PL exists, dependencies are obtained by running perl Makefile.PL PREREQ_PRINT=1.

The current perl version ($]) is always used to determine core modules.

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.

    If you are using Module::Build, ensure that you have run Build.PL and generated a Build script.

    If you are using ExtUtils::MakeMaker, ensure that the current directory contains your Makefile.PL script.

    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>