Contentment::Hooks - Runs the Contentment hook system 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. 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
This registers a handler for a hook. All arguments are passed in a hash: The name of the hook the handler is registering for. The subroutine that will handle the hook. 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. 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. 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. Removed the hook handler for hook $hook registered with id $id. Count the number of registered hooks for the hook $hook. Count the number of registered hooks for the hook $hook named $name. 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. 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. 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}); } 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. Calls the current handler for the hook with the given arguments. This method returns the value returned by the nested subroutine. 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. Returns the order weight that the handler was registered with. Returns 0 if none was given. Andrew Sterling Hanenkamp, <hanenkamp@cpan.org> Contentment is distributed and licensed under the same terms as Perl itself.