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.05 to version0.06. 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->class_hookable_filter( 'run_hook', $hook, $action ) has returned truth, the callback specified by this method is registered with a hook.

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

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->class_hookable_filter( 'register_method', $method, $action ) has returned truth, this method registers a plugin and function.

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

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.

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

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

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 "class_hookable_context" about context object which can be specified in $hook->hookable_context.

$args

The argument specified by the run_hook method.

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

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

FILTER METHODS

class_hookable_set_filter

  $hook->class_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 "class_hookable_filter" about a calling of the filter.

class_hookable_filter_prefix

  $hook->class_hookable_filter_prefix('myfilter_prefix');

This method is accessor of filter prefix.

When finding filter in $hook->class_hookable_filter method, prefix specified by this method is used.

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

When prefix is not specified, this method returns 'class_hookable_filter' by default.

class_hookable_filter

  my $result = $hook->class_hookable_filter( $filter => @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 $hook->can("${prefix}_${filter_name}") is defined, its method is used as a filter.

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

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

Next when a specified filter is specified by $hook->class_hookable_set_filter method, the filter is used.

When a filter was not found, this method uses the filter to which truth is just always returned.

Arguments of filter:

  $hook->class_hookable_set_filter(
      register_hook     => sub {
          my ( $self, $filter, $hook, $action ) = @_;
      },
      register_method   => sub {
          my ( $self, $filter, $method, $action ) = @_;
      },
      run_hook          => sub {
          my ( $self, $filter, $hook, $action, $args ) = @_;
      },
      call_method       => sub {
          my ( $self, $filter, $method, $action, $args ) = @_;
      },
  )

The filters Class::Hookable calls are 'register_hook', 'register_method', 'run_hook' and 'call_method', and the argument to which it's passed is as follows.

$self

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

This argument is passed to all filters.

$filter

The filter name called in $hook->class_hookable_filter.

This argument is passed to all filters.

@args

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

The argument when Class::Hookable calls a filter, is as follows.

$hook or $method

the hook name or the method name.

This argument is passed to all 'register_hook', 'reigster_method', 'run_hook' and 'call_method'.

$action

  # In case of hook
  my ( $plugin, $callback ) = @{ $action }{qw( plugin callback )};

  # In case of method
  my ( $plugin, $function ) = @{ $action }{qw( plugin function )};

The hash reference including the plugin and the callback or function.

This argument is passed to all 'register_hook', 'reigster_method', 'run_hook' and 'call_method'.

$args

The argument specified by the run_hook or call_method method.

This argument is passed to 'run_hook' and 'call_method'.

UTILITY METHODS

registered_hooks

  my $all_hook_data = $hook->registered_hooks;
  #  $all_hook_data = { 'hook.name' => [ { plugin => $plugin callback => \&callback }, ... ] ... };

  my @all_hook_name = $hook->registered_hooks;
  #  @all_hook_name = qw( hook.A hook.B hook.C ... );
  
  my $registered_data = $hook->registered_hooks( $plugin );
  #  $registered_data = [ 'hook.A' => \&callabck, 'hook.B' => \&callback, ... ];
  
  my @registered_hooks = $hook->registered_hooks( $plugin );
  #  @registered_hooks = qw( hook.A hook.B hook.C ... );
  
  my $registered_data = $hook->registered_hooks( \&callback );
  #  $registered_data = [ 'hook.A' => $plugin, 'hook.B' => $plugin, ... ];

  my @registered_hooks = $hook->registered_hooks( \&callback );
  #  @registered_hooks = qw( hook.A hook.B hook.C ... );

This method gets registered data or a hook name.

This method returns registered data in scalar context and returns registered hooks name in list context.

List of arguments and return values:

when there are no arguments

scalar context

This method returns all registered data.

This data is same as $hook->class_hookable_hooks.

list context

This method returns a registered all hook name.

when a registered $plugin object was specified

scalar context

This method returns the hook name with which a plugin is registered and the callback when registering.

The returned value is ARRAY reference, and the contents are the following feeling.

  [
      'hook.A' => \&callbackA,
      'hook.B' => \&callbackB,
      ...
  ]

list context

This method returns the hook name with which a plugin is registered.

when registered \&callback was specified

scalar context

This method returns the hook name with which callback is registered and the plugin when registering.

The returned value is ARRAY reference, and the contents are the following feeling.

  [
      'hook.A' => $plugin,
      'hook.B' => $plugin,
      ...
  ]

list context

This method returns the hook name with which callback is registered.

registered_methods

  my $all_hook_data = $hook->registered_methods;
  #  $all_hook_data = { 'method.name' => { plugin => $plugin, function => \&function, }, ... };

  my @all_hook_name = $hook->registered_methods;
  #  @all_hook_name = qw( method.A method.B method.C ... );
  
  my $registered_data = $hook->registered_methods( $plugin );
  #  $registered_data = [ 'method.A' => \&function, 'method.B' => \&function, ... ];
  
  my @registered_methods = $hook->registered_methods( $plugin );
  #  @registered_methods = qw( method.A method.B method.C ... );
  
  my $registered_data = $hook->registered_methods( \&function );
  #  $registered_data = [ 'method.A' => \&function, 'method.B' => \&function ];

  my @registered_methods = $hook->registered_hooks( \&function );
  #  @registered_methods = qw( method.A method.B method.C ... );

This method gets registered data or a method name.

This method returns registered data in scalar context and returns registered methods name in list context.

List of arguments and return values:

when there are no arguments

scalar context

This method returns all registered data.

This data is same as $hook->class_hookable_methods.

list context

This method returns a registered all method name.

when a registered $plugin object was specified

scalar context

This method returns the method name with which a plugin is registered and the function when registering.

The returned value is ARRAY reference, and the contents are the following feeling.

  [
      'method.A' => \&functionA,
      'method.B' => \&functionB,
      ...
  ]

list context

This method returns the method name with which a plugin is registered.

when registered \&function was specified

scalar context

This method returns the method name with which function is registered and the plugin when registering.

The returned value is ARRAY reference, and the contents are the following feeling.

  [
      'method.A' => $plugin,
      'method.B' => $plugin,
      ...
  ]

list context

This method returns the hook name with which callback is registered.

remove_hook

  $hook->remove_hook( target => $plugin );
  $hook->remove_hook( target => $plugin->can('callback') );
  $hook->remove_hook( target => { plugin => $plugin, callback => $plugin->can('callback') } );
  $hook->remove_hook( target => [ $pluginA \&callbackB, \%expressonC ] );
  
  $hook->remove_hook( target => $plugin, from => 'hook.name' );
  $hook->remove_hook( target => $plugin, from => [qw( hook.A hook.B )] );
  
  $hook->remove_hook( target => \@targets, from => \@hooks );
  
  my $removed = $hook->remove_hook( target => $plugin );

This method deleted hook which matches the specified condition.

About Arguments:

'target'

An deleted target is specified.

They are $plugin, \&callback and \%hash_ref that it can be specified as this argument.

When specifying plugin and callback in hash reference, hook with designated plugin and calllback is deleted.

It is possible to specify more than one deletion target using Array reference.

This argument is indispensable.

'from'

It is specified in which hook an deletion target is deleted.

More than one hook can be specified by using Arrary reference.

When this argument was not specified, an deletion target is deleted from all hook.

About Return value

This method returns deleted hook to a return value.

A return value is the following feeling:

  $removed = {
      'hook.A' => [
          { plugin => $plugin, callback => \&callback },
          { plugin => $plugin, callback => \&callback },
      ],
      'hook.B' => [
          { plugin => $plugin, callback => \&callback },
          { plugin => $plugin, callback => \&callback },
      ],
  }

remove_method

  $hook->remove_method( target => $plugin );
  $hook->remove_method( target => $plugin->can('function') );
  $hook->remove_method( target => { plugin => $plugin, function => $plugin->can('function') } );
  $hook->remove_method( target => [ $pluginA \&functionB, \%expressonC ] );
  
  $hook->remove_method( target => $plugin, from => 'method.name' );
  $hook->remove_method( target => $plugin, from => [qw( method.A method.B )] );
  
  $hook->remove_method( target => \@targets, from => \@methods, );
  
  my $removed = $hook->remove_method( target => $plugin );

This method deleted method which matches the specified condition.

About Arguments:

'target'

An deleted target is specified.

They are $plugin, \&function and \%hash_ref that it can be specified as this argument.

When specifying plugin and callback in hash reference, hook with designated plugin and function is deleted.

It is possible to specify more than one deletion target using Array reference.

This argument is indispensable.

'from'

It is specified in which method an deletion target is deleted.

More than one method can be specified by using Arrary reference.

When this argument was not specified, an deletion target is deleted from all method.

About Return value

This method returns deleted method to a return value.

A return value is the following feeling:

  $removed = {
      'method.A' => { plugin => $plugin, function => \&function },
      'method.B' => { plugin => $plugin, function => \&function },
  }

clear_hooks

  # clear 'hook.A' and 'hook.B'
  $hook->clear_hooks(qw( hook.A hook.B ));
  
  # clear all
  $hook->clear_hooks;
  
  my $removed = $hook->clear_hooks;

This method deleted all registered hooks.

An deleted hook name is specified as an argument.

When arguments were specified, all plugin registered with specified hooks are deleted, and when arguments are not specified, all plugins are deleted from all hooks.

A return value of this method is such feeling:

  $removed = {
      'hook.A' => [
          { plugin => $pluginA, callback => $pluginA->can('foo') },
          { plugin => $pluginB, callback => $pluginB->can('bar') },
          ...
      ],
      'hook.B' => [
          { plugin => $pluginA, callback => $pluginA->can('foo') },
          { plugin => $pluginB, callback => $pluginB->can('bar') },
          ...
      ],
      ...
  };

clear_methods

  # clear 'method.A' and 'methodB'
  $hook->clear_methods(qw( method.A method.B ));
  
  # clear all
  $hook->clear_methods;
  
  my $removed = $hook->clear_methods;

This method deletes all registered method.

An deleted method name is specified as an argument.

When arguments were specified, a plugin registered with specified method is deleted, and when arguments are not specified, all plugins are deleted from all methods.

A return value of this method is such feeling:

  $removed = {
      'method.A' => { plugin => $pluginA, function => $pluginA->can('foo') },
      'method.B' => { plugin => $pluginB, function => %pluginB->can('bar') },
      ...
  };

ACCESSOR METOHDS

class_hookable_stash

  my $data = $hook->class_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.

class_hookable_context

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

This method is accessor of context object.

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

class_hookable_hooks

  my $hooks = $hook->class_hookable_hooks;

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

class_hookable_methods

  my $methods = $hook->class_hookable_methods;

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

class_hookable_filters

  my $filters = $hook->class_hookable_filters;

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

AUTHOR

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

Code by Naoki Okamura (Nyarla) <nyarla[:)]thotep.net>

LICENSE

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

To install Class::Hookable, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Class::Hookable

CPAN shell

perl -MCPAN -e shell
install Class::Hookable

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

BASIC METHOD

new

REGISTER METOHDS

register_hook

register_method

CALL METHODS

run_hook

run_hook_once

call_method

FILTER METHODS

class_hookable_set_filter

class_hookable_filter_prefix

class_hookable_filter

UTILITY METHODS

registered_hooks

registered_methods

remove_hook

remove_method

clear_hooks

clear_methods

ACCESSOR METOHDS

class_hookable_stash

class_hookable_context

class_hookable_hooks

class_hookable_methods

class_hookable_filters

AUTHOR

LICENSE

Module Install Instructions