NAME

Hook::Filter::Plugin::Library - Usefull functions for writing filter rules

DESCRIPTION

A library of functions usefull when writing filter rules. Those functions should be used inside Hook::Filter rules, and nowhere else.

SYNOPSIS

Exemples of rules using test functions from Hook::Filter::Plugin::Location:

# allow all subroutine calls made from inside function 'do_this' from package 'main'
from =~ /main::do:this/

# the opposite
from !~ /main::do:this/

# the called subroutine matches a given name
subname =~ /foobar/

# the 2nd argument of passed to the subroutine is a string matching 'bob'
defined arg(1) && arg(1) =~ /bob/

INTERFACE - TEST FUNCTIONS

The following functions are only exported into Hook::Filter::Rule and shall only be used inside filter rules.

from

Return the fully qualified name of the caller of the filtered subroutine.

Example:

use Hook::Filter hook => 'foo';
use Hook::Filter::RulePool qw(get_rule_pool);

sub foo {}
sub bar1 { foo; }
sub bar2 { foo; }

# add a rule to allow only calls to foo from within bar1 and bar2:
get_rule_pool->add_rule("from =~ /bar\d$/");

foo();  # foo is not called
bar1(); # foo is called
bar2(); # foo is called

subname

Return the fully qualified name of the filtered subroutine being called.

Example:

use Hook::Filter hook => [ 'foo', 'bar' ];
use Hook::Filter::RulePool qw(get_rule_pool);

sub foo {};
sub bar {};

# add a rule to allow only calls to foo:
get_rule_pool->add_rule("subname eq 'main::foo'");

foo();  # foo is called
bar();  # bar is not called

arg($pos)

Return the argument at position $pos in the list of arguments to be passed to the filtered subroutine.

Example:

use Hook::Filter hook => 'debug';

sub debug {
    print $_[1]."\n" if ($_[0] <= $VERBOSITY);
}

# allow calls to debug only if the text matches the name 'bob'
get_rule_pool->add_rule("arg(1) =~ /bob/");

debug(1,"bob did that");      # debug is called
debug(3,"david thinks this"); # debug is not called

INTERFACE - PLUGIN STRUCTURE

Like all plugins under Hook::Filter::Plugins, Hook::Filter::Plugins::Library implements the class method register():

register()

Return the names of the test functions implemented in Hook::Filter::Plugins::Location. Used internally by Hook::Filter::Rule.

DIAGNOSTICS

No diagnostics. Any bug in those test functions would cause a warning emitted by Hook::Filter::Rule::eval().

BUGS AND LIMITATIONS

See Hook::Filter

SEE ALSO

See Hook::Filter, Hook::Filter::Rule, Hook::Filter::RulePool, Hook::Filter::Hooker.

VERSION

$Id: Library.pm,v 1.4 2007/05/24 14:52:37 erwan_lemonnier Exp $

AUTHOR

Erwan Lemonnier <erwan@cpan.org>.

LICENSE

See Hook::Filter.