NAME

Hook::Filter::Hook - Wrap subroutines in a filtering closure

VERSION

$Id: Hook.pm,v 1.1 2006/01/27 06:35:48 erwan Exp $

DESCRIPTION

SYNOPSIS

use Hook::Filter::Hook;
use Hook::Filter::Rule;

my $hook = new Hook::Filter::Hook();

my $rule = new Hook::Filter::Rule("in_package('My::Package') && in_sub('my_sub')");
$hook->register_rule($rule);

$hook->filter_sub("My::Package","mylog");

Later on, you may want to change the rules during runtime:

$hook->flush_rules();
$hook->register_rule($newrule1);
$hook->register_rule($newrule2);

INTERFACE - METHODS

new()

Return a new generic Hook::Filter::Hook instance.

register_rule($rule)

Add a new Hook::Filter::Rule $rule to this Hook::Filter::Hook instance.

filter_sub($subname)

Filter the function or method $subname. $subname must be of the form package_name::function_name. All calls to $subname will thereafter be redirected to a wrapper closure that will evaluate all the rules registered in Hook::Filter::Hook and if one of the rules evals to true, the original function $package::$sub() will be called normally. Otherwise it will be skipped and its result simulated.

flush_rules()

Remove all rules currently registered in this Hook::Filter::Hook.

INTERFACE - CLASS FUNCTIONS

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.

AUTHOR

Erwan Lemonnier <erwan@cpan.org>.

COPYRIGHT AND LICENSE

See Hook::Filter.

DISCLAIMER OF WARRANTY

See Hook::Filter.