NAME

Hook::Filter::Rule - A hook filter rule

VERSION

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

DESCRIPTION

WARNING: if you only intend to use Hook::Filter you won't have to actually use Hook::Filter::Rule and can skip this page.

A filter rule is a perl expression that evaluates to either true or false. Each time a call is made to one of the hooked subroutines all the filter rules registered in Hook::Filter are evaluated, and if one of them returns true, the hooked function is called. Otherwise it is skipped.

A rule is one line of valid perl code that usually combines boolean operators with functions implemented in the Hook::Filter::Plugins:: modules.

SYNOPSIS

use Hook::Filter::Rule;

my $rule = Hook::Filter::Rule->new("from_pkg(qr{^Test::})");
if ($rule->eval) {
    print "just now, the rule [".$rule->rule."] is true\n";
}

$rule->eval() returns true when the filtered subroutines is called from a package whose namespace starts with Test::.

INTERFACE

new($rule)

Return a new Hook::Filter::Rule created from the string $rule. $rule is a valid line of perl code that should return either true or false when eval-ed. It can use any of the functions exported by the plugins modules located under 'Hook::Filter::Plugins::'.

eval()

Eval this rule. Depending on the context in which it is run (state of the stack, caller, variables, etc.) eval() will return either true or false. If the rule dies/croaks/confesses while being eval-ed, a perl warning is thrown and the rule is assumed to return true (fail-safe). The warning contains details about the error message, the rule itself and where it comes from (as specified with source()).

source($message)

Specify the origin of the rule. If the rule was parsed from a configuration file, $message should be the path to this file. This is used in the warning message emitted when a rule fails during eval().

rule()

Return the rule string ($rule in new()).

DIAGNOSTICS

use Hook::Filter::Rule croaks if a plugin module tries to export a function name that is already exported by an other plugin.

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

$rule->eval() will emit a perl warning if the rule dies when eval-ed.

$rule->source($text) croaks if $text is not a scalar.

BUGS AND LIMITATIONS

See Hook::Filter

SEE ALSO

See Hook::Filter, Hook::Filter::Hook, Hook::Filter::Plugins::Location.

AUTHOR

Erwan Lemonnier <erwan@cpan.org>

COPYRIGHT AND LICENSE

See Hook::Filter.

DISCLAIMER OF WARRANTY

See Hook::Filter.