/ 
Sub-Stubber-0.01
/ Sub::Stubber

NAME

Sub::Stubber - Self-monkeypatch your on demand.

SYNOPSIS

package Expensive;
use Sub::Stubber;
use base qw(Sub::Stubber Exporter);

our @EXPORT = qw(expensive_1 expensive_2);
Sub::Stubber->regstubs(@EXPORT);
Sub::Stubber->add_trigger(import => '__USE_STUBS__');
Sub::Stubber->add_trigger(env => EXPENSIVE_USE_STUBS);

sub expensive_1 ($$) {
    sleep(100);
}
sub expensive_2 (@) {
    sleep(200);
}

Meanwhile, in calling code:

use Expensive qw(__USE_STUBS__);
expensive_1 'foo', 'bar'; #returns immediately
my @l;
expensive_2 @l; #returns immediately

From the command line:

EXPENSIVE_USE_STUBS=1 perl -MExpensive -e 'expensive_1 1,2'

DESCRIPTION

Sub::Stubber allows for modules to conveniently change their containing functions into stubs. This is useful for code which by default does expensive operations, but which may not be desired for one-off cases, such as test environments or scripts - or in cases where calling code knows that those functions will never need to return anything significant.

The 'stubification' of the modules is hard. This does not attempt to merely export stubbed functions to calling code, but will override the actual functions with their stubbed versions, so exported, fully qualified and intra-package calls to these functions will all use the stubs instead.

If you would like to see a more export-oriented module, have a look at Sub::Exporter.

This module has no exports of its own, and its functionality is available via inheritance and/or package methods:

Sub::Stubber->regstubs(...)

Register one or more sub specifications to be used in conjunction with the calling package.

A stub specification can either be a simple name, or a hash reference.

In the case of the former, a simple function is generated that returns undef. In the case of the latter, the hash reference is taken to contain one or more pairs of function names as keys, and their intended return values as values. Value can be any scalar

Sub::Stubber->add_trigger(trigger_type, trigger_name)

Modules need to know when they need to generate a trigger function.

The trigger_type argument specifies what type of trigger should be added, and trigger_name is the name of that trigger.

Note that triggers only have meaning within Sub::Stubber's import function, but should work as a standalone in a future release.

The triggers provided are:

env

Check the environment to see if a specific flag trigger_name is set to true.

import

Check arguments passed to import for a token matching trigger_name.

Sub::Stubber->mkstubs(extra stub specifiers)

'Stubbify' the functions registered with regstubs and/or additional stub specifiers passed as arguments to mkstubs.

This does not do checking on environment variables, and should be used from your own import function, if Sub::Stubber's import isn't sufficient.

INHERITING

You can inherit from Sub::Stubber. Inheriting provides an import method which works with Exporter, and allows it to scan special import-time tokens and/or environment variables specifying whether functions should be stubbified.

If you choose to inherit from this module, ensure that Sub::Stubber's import gets called first by placing it at the beginning of your module's @ISA.

Thus:

our @ISA = qw(Sub::Stubber Exporter);

TODO

Make this module more friendly for code which doesn't like to inherit it.

AUTHOR & COPYRIGHT

Copyright (C) 2012 M. Nunberg

You may use and distribute this software under the same terms and conditions as Perl itself.