NAME

Hook::WrapSub - wrap subs with pre- and post-call hooks

SYNOPSIS

use Hook::WrapSub qw( wrap_subs unwrap_subs );

wrap_subs \&before, 'some_func', 'another_func', \&after;

unwrap_subs 'some_func';

DESCRIPTION

wrap_subs

     This function enables intercepting a call to any named
     function; handlers may be added both before and after the
     call to the intercepted function.

     For example:

       wrap_subs \&before, 'some_func', \&after;

     In this case, whenever the sub named 'some_func' is called,
     the &before sub is called first, and the &after sub is
     called afterwards.  These are both optional.  If you only
     want to intercept the call beforehand:

       wrap_subs \&before, 'some_func';

     You may pass more than one sub name:

       wrap_subs \&before, 'foo', 'bar', 'baz', \&after;

     and each one will have the same hooks applied.

     The sub names may be qualified.  Any unqualified names are
     assumed to reside in the package of the caller.

     The &before sub and the &after sub are both passed the
     argument list which is destined for the wrapped sub.  This
     can be inspected, and even altered, in the &before sub:

       sub before {
         ref($_[1]) && $_[1] =~ /\bARRAY\b/
           or croak "2nd arg must be an array-ref!";
         @_ or @_ = qw( default values );
         # if no args passed, insert some default values
       }

     The &after sub is also passed this list.  Modifications to
     it will (obviously) not be seen by the wrapped sub, but the
     caller will see the changes, if it happens to be looking.

     Here's an example that causes a certain method call to be
     redirected to a specific object.  (Note, we use splice to
     change $_[0], because assigning directly to $_[0] would cause
     the change to be visible to the caller, due to the magical
     aliasing nature of @_.)

       my $handler_object = new MyClass;

       Hook::WrapSub::wrap_subs
         sub { splice @, 0, 1, $handlerobject },
         'MyClass::some_method';

       my $other_object = new MyClass;
       $other_object->some_method;

       # even though the method is invoked on
       # $other_object, it will actually be executed
       # with a 0'th argument = $handler_obj,
       # as arranged by the pre-call hook sub.

     Package Variables

     There are some Hook::WrapSub package variables defined,
     which the &before and &after subs may inspect.

     $Hook::WrapSub::name
         This is the fully qualified name of the wrapped sub.

     @Hook::WrapSub::caller
         This is a list which strongly resembles the result of a
         call to the built-in function caller; it is provided
         because calling caller will in fact produce confusing
         results; if your sub is inclined to call caller, have it
         look at this variable instead.

     @Hook::WrapSub::result
         This contains the result of the call to the wrapped sub.
         It is empty in the &before sub.  In the &after sub, it
         will be empty if the sub was called in a void context,
         it will contain one value if the sub was called in a
         scalar context; otherwise, it may have any number of
         elements.  Note that the &after function is not
         prevented from modifying the contents of this array; any
         such modifications will be seen by the caller!

     This simple example shows how Hook::WrapSub can be used to
     log certain subroutine calls:

       sub before {
         print STDERR <<"    EOF";
           About to call $Hook::WrapSub::name( @_ );
           Wantarray=$Hook::WrapSub::caller[5]
         EOF
       }

       sub after {
         print STDERR <<"    EOF";
           Called $Hook::WrapSub::name( @_ );
           Result=( @Hook::WrapSub::result )
         EOF
         @Hook::WrapSub::result
           or @Hook::WrapSub::result = qw( default return );
         # if the sub failed to return something...
       }

     Much more elaborate uses are possible.  Here's one one way
     it could be used with database operations:

       my $dbh; # initialized elsewhere.

       wrap_subs
         sub {
           $dbh->checkpoint
         },

         'MyDb::update',
         'MyDb::delete',

         sub {
           # examine result of sub call:
           if ( $Hook::WrapSub::result[0] ) {
             # success
             $dbh->commit;
           }
           else {
             # failure
             $dbh->rollback;
           }
         };

     unwrap_subs

     This removes the most recent wrapping of the named subs.

     NOTE: Any given sub may be wrapped an unlimited number of
     times.  A "stack" of the wrappings is maintained internally.
     wrap_subs "pushes" a wrapping, and unwrap_subs "pops".

AUTHOR

jdporter@min.net (John Porter)

COPYRIGHT

     This is free software.  This software may be modified and/or
     distributed under the same terms as Perl itself.