NAME
    Class::Hook - Add hooks on methods from other classes

SYNOPSIS
      use Class::Hook;

      Class::Hook->before(\&sub1);
      Class::Hook->after(\&sub2);
      Class::Hook->activate();
      # or
      Class::Hook->new(\&sub1, \&sub2);

      # and then
      Anotherclass->aMethod($someParam); # Hooked class

DESCRIPTION
    Class::Hook enables you to trace methods calls from your code to other
    classes.

    Instead of putting 'use Foo;' in your code, simply type 'use
    Class::Hook;'. The class Foo is unknown in your code. It will be
    magically catched by Class::Hook which will call Foo itself. You can see
    Class::Hook as a kind of relay.

    You can setup a subroutine to be called before any call to Foo->amethod
    and a subroutine to be called after the call. Your subs will receive all
    the information that Foo->amethod will receive, so you can trace
    everything between your code and Foo.

METHODS
  new($subref_before, $subref_after, $param)

    Install subroutines to be called whenever a method from an unknown class
    is called. It is equivalent to the following code:

      Class::Hook->before($subref_before, $param);
      Class::Hook->after($subref_after, $param);
      Class::Hook->activate();

  before($subref, $param)

    Install subroutine to be called whenever a call to an unknown class is
    made. $param will be sent to your $subref if specified &$subref will
    receive the following parameters: ( $param, { class => $class_or_object,
    method => $method_called, param => [@params_sent], counter =>
    $no_calls_for_this_method } ) or the following parameters if $param
    undefined ({ class => $class_or_object, method => $method_called, param
    => [@params_sent], counter => $no_calls_for_this_method } )

  after($subref, $param)

    Install subroutine to be called whenever a call to an unknown class
    returns. $param will be sent to your $subref if specified. &$subref will
    receive the following parameters ( $param, { class => $class_or_object,
    method => $method_called, param => [@params_sent], counter =>
    $no_calls_for_this_method, 'return' => [@return_values], duration =>
    $duration in seconds } ) or the following parameters if $param
    undefined( { class => $class_or_object, method => $method_called, param
    => [@params_sent], counter => $no_calls_for_this_method, 'return' =>
    [@return_values], duration => $duration in seconds } )

  activate()

    Activates the hooks on methods calls to unknown classes. Your subs
    `before' and `after' will be called at each call to an unknown package.

  deactivate()

    Stops hooks.

EXAMPLES
      You want to study calls to a class 'Foo'
      ========================================
      main.pl
      =======
      # Don't write 'use Foo;'!
      use Data::Dumper;
      use Class::Hook;
      Class::Hook->new(\&mybefore, \&myafter);

      Foo->new('bla', 'blu');
      Foo->bar( { key1 => 'value1',
                  key2 => 'value2'} );
      Foo->xxxx(); # Non existing method

      sub mybefore {
          print "Before called: ".Dumper(\@_);
      }

      sub myafter {
          print "After called: ".Dumper(\@_);
      }

      Foo.pm
      ======
      package Foo;
      sub new {
          my ($class, @param) = @_;
          warn "Foo->new called";
          return bless { 'something' => 'whatever',
                         'init'      => \@param }
                         => $class;
      }

      sub bar {
          warn "Foo->bar called";
          return "Hello from bar";
      }

      1;

CAVEATS
    It works only with method calls, not with subroutines calls. Foo->method
    will work Foo::method will NOT work UNIVSERAL::AUTOLOAD is overriden
    after Class::Hook->activate() has been called. Expect some strange
    behaviors if the module you use plays with it.

BUGS
    Don't rely on it for production purpose. Has been tested on perl 5.6.0
    only

AUTHOR
    "Pierre Denis" <pierre@itrelease.net>

COPYRIGHT
    Copyright (C) 2005, IT Release Ltd. This is free software. This software
    may be modified and/or distributed under the same terms as Perl itself.