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.