/ 
Class-Hookable-0.02
/ Class::Hookable

NAME

Class::Hookable - Base class for hook mechanism

SYNOPSIS

package MyApp::Plugins;
use base qw( Class::Hookable );

my $hook = MyApp::Plugins->new;

$hook->register_hook(
    $plugin,
    'hook.name' => $plugin->can('callback'),
);

$hook->run_hook('hook.name', $args);

DESCRIPTION

Class::Hookable is the simple base class for the hook mechanism. This module supports only a hook mechanism.

This module was made by making reference to the hook mechanism of Plagger. I thank Tatsuhiko Miyagawa who made wonderful application.

BASIC METHOD

new

my $hook = Class::Hookalbe->new;

This method is a constructor of Class::Hookable. Nothing but that is being done.

REGISTER METOHDS

register_hook

$hook->register_hook(
    $plugin,
    'hook.A' => $plugin->can('callbackA'),
    'hook.B' => $plugin->can('callbackB'),
);

This method registers a plugin object and callbacks which corresponds to hooks.

The plugin object is specified as the first argument, and one after that is specified by the order of 'hook' => \&callabck.

filter_register_hook

sub filter_register_hook {
    my ( $self, $hook, $action ) = @_;
    my ( $plugin, $callback ) = @{ $action }{qw( plugin callback )};
    # your filter code
}

When registering a plugin, this method is filtered a plugin. Arguments are passed by the order of $hook and $action.

$hook

The hook name specified as the run_hook method.

$action

The hash reference including plugin and callback.

When this method has returned ture, plugin and hook are registered, and when having returned false, it isn't registered.

This method exists to rewrite when inheriting.

UTILITY METHODS

registered_hooks

my @hooks = $hook->registered_hooks( $plugin );
my @hooks = $hook->registered_hooks( 'ClassName' );

This method returns hooks with which a plugin is registered. An argument is plugin object or class name.

registered_plugins

for my $action ( $hook->registered_plugins('hook.name') ) {
    my ( $plugin, $callback ) = @{ $action }{qw( plugin callback )};
    # some code
}

This method returns plugin and callback registered with a hook. Return value is a list of hash reference including plugin and callback.

delete_plugin

$hook->delete_plugin( $plugin );
$hook->delete_plugin( 'ClassName', 'hook.A', 'hook.B' );

This method delete a registered plugin.

When specifying only a plugin object (or class name) as an argument, a plugin is deleted from all hooks.

And when specifying a plugin object (or class name) and hooks as arguments, a plugin is deleted from specified hooks.

delete_hook

$hook->delete_hook( 'hook.name' );
$hook->delete_hook( 'hook.name', $pluginA, 'ClassName' );

This method delete a registered hook.

When specifying only a hook as an argument, all plugin registered with the hook are deleted.

And when specifying a hook and plugin object (or class name) as arguments, specified plugins are deleted from a specified hook.

CALL METHODS

run_hook

$hook->run_hook( $hook, $args, $once, $callback );
my @results = $hook->run_hook('hook.name', \%args, undef, \&callback);
my $result  = $hook->run_hook('hook.name', \%args, 1, \&callback);

This method calls callback of the registered plugin to hook by the registered order. Arguments are specified by the order of $hook, $args, $once and $callback.

Arguments to run_hook method:

$hook

Designation of the hook with which a plugin was registered. This argument is indispensable.

$args

The argument which passes it to callback. This argument is optional.

$once

When this argument becomes true, this method finishes calling callback when the first return value has been received.

This argument is optional.

$callback
my $callback = sub {
    my ( $result ) = @_;
    # some code
}

This argument specifies code reference.

When having received a return value from callback of the registered, the callback specified by this argument is called.

A return value of callback of registered plugin is passed to an argument of this callback.

Argument to callback of the registered plugin:

sub callback {
    my ( $plugin, $context, $args ) = @_;
    # some code
}

The argument by which it is passed to callback is $plugin, $context, $args.

$plugin

The plugin object which passed a plugin and callback to the register_hook method when registering.

$context

The context object.

When $hook->context is specified, the specified object is passed, and when it isn't so, $hook(Class::Hookable) object is passed.

see also "context" method.

$args

$args specified by the run_hook method.

run_hook_once

my $result = $hook->run_hook_once( $hook, $args, $callback );

This method is an alias of $hook->run_hook( $hook, $args, 1, \&callback ).

filter_run_hook

sub filter_run_hook {
    my ( $self, $hook, $args, $action ) = @_;
    my ( $plugin, $callabck ) = @{ $action }{qw( plugin callback )};
    # some code
}

When calling a hook, this method is filtered a plugin. Argument are passed by the order of $hook, $args, $action.

$hook

The hook name specified by the run_hook method.

$args

The argument specified by the run_hook method.

$action

The hash reference including the plugin and the callback.

When this method has returned true, callback of a plugin is called, and when having returned false, callback isn't called.

This method exists to rewrite when inheriting.

ACCESSOR METOHDS

context

my $context = $hook->context;
$hook->context( $context );

This method is accessor of context object.

When specifying object by this method, it's passed to callback of the plugin as context object.

see also "run_hook" method.

hooks

my $hooks = $hook->hooks;

This method is accessor to hash reference which keeps hooks. all method of Class::Hookable is accessing hooks through this method.

AUTHOR

Original idea by Tatsuhiko Miyagawa http://search.cpan.org/~miyagawa in Plagger

Code by Naoki Okamura (Nyarla) <thotep@nayrla.net>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.