#################################################################
#
# Hook::Filter::Plugin::Library - Usefull functions for writing filter rules
#
# $Id: Library.pm,v 1.4 2007/05/24 14:52:37 erwan_lemonnier Exp $
#
# 060302 erwan Created
# 070516 erwan Removed from_xxx(), added from(), arg() and subname()
#
package Hook::Filter::Plugins::Library;
use strict;
use warnings;
use Carp qw(croak);
use Data::Dumper;
use Hook::Filter::Hooker;# qw( get_caller_subname get_caller_package get_subname get_arguments );
#----------------------------------------------------------------
#
# register - return a list of the tests available in this plugin
#
sub register {
return qw(from arg subname);
}
#----------------------------------------------------------------
#
# from - returns the fully qualified name of the caller
#
sub from {
return Hook::Filter::Hooker::get_caller_subname();
}
#----------------------------------------------------------------
#
# arg - return the n-ieme argument passed to the filtered subroutine
#
sub arg {
my $pos = shift;
croak "invalid rule: function arg expects a number, got: ".Dumper($pos,@_) if (!defined $pos || @_ || $pos !~ /^\d+$/);
my @args = Hook::Filter::Hooker::get_arguments();
return $args[$pos];
}
#----------------------------------------------------------------
#
# subname - return the fully qualified name of the called subroutine
#
sub subname {
return Hook::Filter::Hooker::get_subname();
}
1;
__END__
=head1 NAME
Hook::Filter::Plugin::Library - Usefull functions for writing filter rules
=head1 DESCRIPTION
A library of functions usefull when writing filter rules.
Those functions should be used inside C<Hook::Filter> rules, and nowhere else.
=head1 SYNOPSIS
Exemples of rules using test functions from C<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/
=head1 INTERFACE - TEST FUNCTIONS
The following functions are only exported into C<Hook::Filter::Rule> and
shall only be used inside filter rules.
=over 4
=item C<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
=item C<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
=item C<< arg($pos) >>
Return the argument at position C<$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
=back
=head1 INTERFACE - PLUGIN STRUCTURE
Like all plugins under C<Hook::Filter::Plugins>, C<Hook::Filter::Plugins::Library> implements the class method C<< register() >>:
=over 4
=item C<< register() >>
Return the names of the test functions implemented in C<Hook::Filter::Plugins::Location>. Used
internally by C<Hook::Filter::Rule>.
=back
=head1 DIAGNOSTICS
No diagnostics. Any bug in those test functions would cause a warning emitted by C<Hook::Filter::Rule::eval()>.
=head1 BUGS AND LIMITATIONS
See Hook::Filter
=head1 SEE ALSO
See Hook::Filter, Hook::Filter::Rule, Hook::Filter::RulePool, Hook::Filter::Hooker.
=head1 VERSION
$Id: Library.pm,v 1.4 2007/05/24 14:52:37 erwan_lemonnier Exp $
=head1 AUTHOR
Erwan Lemonnier C<< <erwan@cpan.org> >>.
=head1 LICENSE
See Hook::Filter.
=cut