NAME

Contentment::Hooks - Runs the Contentment hook system

SYNOPSIS

  use Contentment::Hooks;

  # register Foo:bar() for hook 'foo' with order weight 50.
  Contentment::Hooks->register(
	  hook  => 'foo', 
	  name  => 'Foo',
	  code  => \&Foo::bar, 
	  order => 50,
  );

  # register Foo::baz() for hook 'foo' with default priority
  Contentment::Hooks->register(hook => 'foo', code => \&Foo::baz);

  # run the 'foo' hook with the given arguments
  Contentment::Hooks->call('foo', 0, foo => 7);

  # This would call:
  #   &Foo::baz(0, foo => 7);
  #   &Foo::bar(0, foo => 7);
  # Default priority = 0 and lower order weights run first.
 

DESCRIPTION

Contentment depends heavily upon the hook system to allow each aspect of the system to be overridden by one or more plugins providing features to the system. These plugins register themselves with the hooks they wish to be dropped into and then those registered bits of code are run when the named hook is.

HOOK API

Contentment::Hook->register(%args)

This registers a handler for a hook. All arguments are passed in a hash:

hook (required)

The name of the hook the handler is registering for.

code (required)

The subroutine that will handle the hook.

order (optional: defaults to 0)

The order weight the handler should have. Lower numbers will be run first and higher numbers will be run last. It's recommended that these values be kept between -99 and 99.

name (optional)

Some hooks require names to be used so that each name can be handled differently. How the names are used will depend upon the hook, so see the documentation for the hook for details.

id (optional)

In some cases, it is desirable to unregister a hook handler. By passing this id, it can be passed to the unregister method to remove this hook. If no id is given, one will be assigned.

Contentment::Hook->unregister($hook, $id)

Removed the hook handler for hook $hook registered with id $id.

Contentment::Hook->count($hook)

Count the number of registered hooks for the hook $hook.

Contentment::Hook->count_named($hook, $name)

Count the number of registered hooks for the hook $hook named $name.

Contentment::Hook->call($hook, @args)

Call the hook named $hook and pass arguments @args. The arguments are optional.

Each subroutine registered for the hook is executed in order. The return value of the final hook is returned.

Contentment::Hook->call_named($hook, $name, @args)

Call only handlers for $name registered for the hook named $hook and pass arguments @args. The arguments are optional.

Each subroutine registered for the hook is executed in order. The return value of the final hook is returned.

$iterator = Contentment::Hook->call_iterator($name)

This returns an object that may be used to iterate through all the hook subroutines manually. This is handy if the hooks are permitted to manipulate arguments, have significant return values, or need to have the output of each fed one into the other, etc. This method is reentrant, so if you want to recursively iterate through hooks, the iterators will not clobber each other.

See "CALL ITERATOR" for more information.

CALL ITERATOR

Using a call iterator (via the call_iterator method), you can run each hook subroutine one at a time.

  my $iter = Contentment::Hooks->call_iterator('foo');
  while ($iter->next) {
	  # Pass a handler it's data associated by name
	  $iter->call($data{$iter->name});
  }

$test = $iter->next

Moves the iterator to point to the next hook handler. This method returns a true value if there is another handler to run and false if there are no more.

$iter->call(@args)

Calls the current handler for the hook with the given arguments. This method returns the value returned by the nested subroutine.

$name = $iter->name

Returns the name that was associated with the handler according to the "name" argument when the handler was registered. Returns undef if no such argument was given.

$name = $iter->order

Returns the order weight that the handler was registered with. Returns 0 if none was given.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

Contentment is distributed and licensed under the same terms as Perl itself.