NAME

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

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::Hook 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 modules under Hook::Filter::Plugins::.

SYNOPSIS

    use Hook::Filter::Rule;

    my $rule = Hook::Filter::Rule->new("1");
    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, modules under Hook::Filter::Plugins::.

VERSION

$Id: Rule.pm,v 1.2 2007/05/16 13:31:36 erwan_lemonnier Exp $

AUTHOR

Erwan Lemonnier <erwan@cpan.org>

LICENSE

See Hook::Filter.