The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Class-Hookable-0.05
/ 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 base class for the hook mechanism. This module supports the hook mechanism like Plagger.

This module was made based on the hook mechanism of Plagger. I thank Tatsuhiko Miyagawa and Plagger contributors.

NOTE:

Class::Hookable is having substantial changes from version 0.02 to version0.03. When using Class::Hookable, please be careful.

Please see Changes file about a change point.

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.

Only when $hook->hookable_call_filter( 'run_hook', $hook, $action ) has returned truth, the callback specified by this method is registered with a hook.

Please see "hookable_call_filter" about $hook->hookable_call_filter.

Arguments of $hook->hookable_call_filter:

  $hook->hookable_call_filter( 'run_hook', $hook, $action );
'run_hook'

'run_hook' is filter name.

$hook

The hook name specified as the register_hook method.

$action
  my ( $plugin, $callback ) = @{ $action }{qw( plugin callback )};

The hash reference including plugin and callback.

register_method

  $hook->register_method(
      $plugin,
      'method.A' => $plugin->can('methodA'),
      'method.B' => $plugin->can('methodB'),
  );

This method registers a plugin and functions with the methods.

The specification of arguments is same as "register_hook" method.

The method is different from hook and only a set of plugin and function are kept about one method. When specifying the method name which exists already, the old method is replaced with the new method.

Only when $hook->hookable_call_filter( 'register_method', $method, $action ) has returned truth, this method registers a plugin and function.

Please see "hookable_call_filter" about $hook->hookable_call_filter.

Arguments of $hook->hookable_call_filter:

'register_method'

'run_hook' is filter name.

$method

The method name specified as the register_method method.

$action
  my ( $plugin, $function ) = @{ $action }{qw( plugin function )};

The hash reference including plugin and function.

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.

Arguments of registered callback:

  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->hookable_context is specified, the specified object is passed, and when it isn't so, object of Class::Hookable (or object of inherited Class::Hookable class) is passed.

Please see "hookable_context" about context object which can be specified in $hook->hookable_context.

$args

the argument specified by the run_hook method.

Arguments of $hook->hookable_call_filter:

  $hook->hookable_call_filter( 'run_hook', $hook, $args, $action );

Only when $hook->hookable_call_filter( 'run_hook', $hook, $args, $action ) has returned truth, this method calls callback.

Please see "hookable_call_filter" about $hook->hookable_call_filter.

'run_hook'

'run_hook' is filter name.

$hook

The hook name specified by the run_hook method.

$args

The argument specified by the run_hook method.

$action
  my ( $plugin, $callback ) = @{ $action }{qw( plugin callback )};

The hash reference including the plugin and the callback.

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 ).

call_method

  my $result = $hook->call_method( $method => $args );

This method calls function of the registered plugin to method. Arguments are specified by the order of $method and $args.

When the function was not found, no this methods are returned.

Arguments of call_method method:

$method

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

$args

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

Arguments of registered function:

  sub function {
      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 function to the register_method method when registering.

$context

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

Please see "hookable_context" about context object which can be specified in $hook->hookable_context.

$args

The argument specified by the run_hook method.

Arguments of $hook->hookable_call_filter:

  $hook->hookable_call_filter( 'call_method', $method, $args, $action );

Only when $hook->hookable_call_filter( 'call_method', $method, $args, $action ) has returned truth, this method calls function.

Please see "hookable_call_filter" about $hook->hookable_call_filter.

'call_method'

'call_method' is filter name.

$method

The function name specified by the call_method method.

$args

The argument specified by the call_method method.

$action
  my ( $plugin, $function ) = @{ $action }{qw( plugin function )};

The hash reference including the plugin and the function.

FILTER METHODS

hookable_set_filter

  $hook->hookable_set_filter(
      register_hook => \&filterA
      run_hook      => \&filterB,
  );

This method registers the filter of hook and method.

Arguments are specified by the order of 'name' => \&filter. The character which can be used for the filter name is [a-zA-Z_].

When registering a homonymous filter of the filter registered already, a old filter is replaced with a new filter.

Please see "hookable_call_filter" about a calling of the filter.

hookable_call_filter

  my $bool = $hook->hookable_call_filter( $name => @args );

This method calls a specified filter.

A filter name is specified as the first argument and an argument to a filter is specified as an argument after that.

Search of filter:

This method searches for a filter from several places.

First, when a specified filter is specified by $hook->hookable_set_filter method, the filter is used.

Next when $hook->can("${prefix}_${filter_name}") is defined, its method is used as a filter.

${prefix} is return value of $hook->hookable_filter_prefix, and ${filter_name} is the filter name specified as this method.

When $hook->hookble_filter_perfix is not specified, ${prefix} will be 'hookable_filter'.

Please see "hookable_filter_prefix" about $hook->hookable_filter_prefix.

When a filter wasn't found, this method uses the filter to which truth is just always returned.

Arguments of filter:

  $hook->hookable_set_filter(
      'run_hook' => sub {
          my ( $hook, $filter, @args ) = @_;
      },
  );
$hook

Instance of Class::Hookable (or the class inheriting to Class::Hookable).

$filter

The filter name called in $hook->hookable_call_filter.

@args

Arguments to the filter to which it was passed by $hook->hookable_call_filter.

hookable_filter_prefix

  $hook->hookable_filter_prefix('myfilter_prefix');

This method is accessor of filter prefix;

When finding filter in call_filer_method, prefix specified by this method is used.

The character which can be used for the filter prefix is [a-zA-Z_].

UTILITY METHODS

registered_hooks

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

This method returns a registered hook name.

When calling without arguments, all registered hook name is returned.

And when specifying plugin obejct (or Class name) as an argument, the hook name with which a plugin is registered is returned.

registered_callbacks

  for my $action ( $hook->registered_callbacks('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. When there are no registered plugin and callback, this method returns empty list.

registered_methods

  my @methods = $hook->registered_methods( $plugin );
  my @methods = $hook->registered_methods( 'ClassName' );

This method returns a registered method names.

When calling without arguments, all registered method name is returned. and When specifying plugin object (or class name) as an arguments, the method name with which a plugin is registered is returned.

registered_function

  my $action = $hook->registered_function('method.name');
  my ( $plugin, $function ) = @{ $action }{qw( plugin function )};

This method returns plugin and callback registered with a method.

Return value is a hash reference including plugin and callback. When nothing is registered, no this methods are returned.

delete_hook

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

This method deletes a registered hook.

Hook name is specified as the first argument, and plugin object or class name is specified as an argument after that.

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 specified hooks.

delete_callback

  $hook->delete_callback( $plugin->can('callback') );
  $hook->delete_callback( \&callback => qw( hook.A hook.B ) );

This method deletes a registered callback.

Callback (CODE reference) is specified as the first argument, and some hook names are specified after that.

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

And When specifying callback and hook names as arguments, specified callbacks are deleted from specified hooks.

delete_method

  $hook->delete_method('method.name');

This method deleted a registered hookable method. The method name is specified as an argument.

delete_function

  $hook->delete_function( $plugin->can('function') );:
  $hook->delete_function( \&function => qw( method.A method.B ) );

This method deletes a registered function.

Function (CODE reference) is specified as the first argument. and some method names are specified after that.

When specifying only a function as an argument, all functions registered with the method are deleted.

And when specifying function and method names as arguments, specified functions are deleted from specified methods.

delete_plugin

  $hook->delete_plugin( $plugin );
  $hook->delete_plugin( ClassName => qw( hook.A method.A ) );

This method deletes a registered plugin.

A plugin object or class name is specified as the first argument, and hook names or method names are specified as an argument after that.

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

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

ACCESSOR METOHDS

hookable_stash

  my $data = $hook->hookable_stash;

This method is stash in Class::Hookable. All variables Class::Hookable needs are put here.

This method does not get arguments, and return hash reference includes all variables.

hookable_context

  # set
  $hook->hookable_context( $context );
  # get
  my $context = $hook->hookable_context;

This method is accessor of context object.

blessed object or class name is specified as the context object.

Context object specified by this method is passed as the second argument of the subroutine registered with hook and method.

see also "run_hook".

hookable_all_hooks

  my $hooks = $hook->hookable_all_hooks;

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

hookable_all_methods

  my $methods = $hook->hookable_all_methods;

This method is accesor to hash reference which keeps methods. all method of Class::Hookable is accessing methods 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.