NAME

Hook::Filter::Hooker - Wrap subroutines in a firewalling closure

DESCRIPTION

This module is used internaly by Hook::Filter to generate an anonymous sub (the runtime subroutine firewall itself) that is wrapped around each filtered subroutine and either forwards the call to the subroutine or stop it and spoofs return values (undef or an empty list depending on context).

SYNOPSIS

use Hook::Filter::Hooker;

my $hooker = new Hook::Filter::Hooker();

$hooker->filter_sub("My::Package");

# mylog is declared in the current package
$hooker->filter_sub("mylog");

INTERFACE

Hook::Filter::Hooker exports no functions by default. But the following functions can be imported upon using Hook::Filter::Hooker:

$hooker->filter_sub($subname)

Add a filter aroun the subroutine $subname. $subname must either be a fully qualified function name, or the name of a function located in the current package.

All calls to $subname will thereafter be redirected to a wrapper closure that will evaluate all the rules registered in Hook::Filter::RulePool and if one of the rules evals to true, the original function $subname will be called normally. Otherwise it will be skipped and its result spoofed.

The following class functions are to be used by modules under Hook::Filter::Plugins that implement specific test functions for use in filter rules.

Any use of the following functions in a different context than inside the implementation of a filter rule test is guaranteed to return only garbage.

See Hook::Filter::Plugins::Location for a usage example.

get_caller_package()

Return the name of the package calling the filtered subroutine.

get_caller_file()

Return the name of the file calling the filtered subroutine.

get_caller_line()

Return the line number at which the filtered subroutine was called.

get_caller_subname()

Return the complete name (package+name) of the subroutine calling the filtered subroutine. If the subroutine was called directly from the main namespace, return an empty string.

get_subname()

Return the complete name of the filtered subroutine for which the rules are being eval-ed.

get_arguments()

Return the list of arguments that would be passed to the filtered subroutine.

DIAGNOSTICS

$hook->register_rule($rule) croaks if $rule is not a Hook::Filter::Rule.

$hook->filter_sub($pkg,$func) croaks when passed invalid arguments.

The closure wrapping all filtered subroutines emits perl warning when rules die upon being eval-ed.

BUGS AND LIMITATIONS

See Hook::Filter

SEE ALSO

See Hook::Filter, Hook::Filter::Rule, modules under Hook::Filter::Plugins.

VERSION

$Id: Hooker.pm,v 1.3 2007/05/16 14:36:51 erwan_lemonnier Exp $

AUTHOR

Erwan Lemonnier <erwan@cpan.org>.

LICENSE

See Hook::Filter.