NAME

       Hook::LexWrap - Lexically scoped subroutine wrappers

VERSION

       This document describes version 0.23 of Hook::LexWrap.

SYNOPSIS

               use Hook::LexWrap;

               sub doit { print "[doit:", caller, "]"; return {my=>"data"} }

               SCOPED: {
                       wrap doit,
                               pre  => sub { print "[pre1: @_]\n" },
                               post => sub { print "[post1:@_]\n"; $_[1]=9; };

                       my $temporarily = wrap doit,
                               post => sub { print "[post2:@_]\n" },
                               pre  => sub { print "[pre2: @_]\n  "};

                       @args = (1,2,3);
                       doit(@args);    # pre2->pre1->doit->post1->post2
               }

               @args = (4,5,6);
               doit(@args);            # pre1->doit->post1

DESCRIPTION

       Hook::LexWrap allows you to install a pre- or post-wrapper (or both) around an existing
       subroutine. Unlike other modules that provide this capacity (e.g. Hook::PreAndPost and
       Hook::WrapSub), Hook::LexWrap implements wrappers in such a way that the standard "caller"
       function works correctly within the wrapped subroutine.

       To install a prewrappers, you write:

               use Hook::LexWrap;

               wrap 'subroutine_name', pre => \&some_other_sub;

          #or: wrap *subroutine_name,  pre => \&some_other_sub;

       The first argument to "wrap" is a string containing the name of the subroutine to be
       wrapped (or the typeglob containing it, or a reference to it). The subroutine name may be
       qualified, and the subroutine must already be defined. The second argument indicates the
       type of wrapper being applied and must be either 'pre' or 'post'. The third argument must
       be a reference to a subroutine that implements the wrapper.

       To install a post-wrapper, you write:

               wrap 'subroutine_name', post => \&yet_another_sub;

          #or: wrap *subroutine_name,  post => \&yet_another_sub;

       To install both at once:

               wrap 'subroutine_name',
                    pre  => \&some_other_sub,
                    post => \&yet_another_sub;

       or:

               wrap *subroutine_name,
                    post => \&yet_another_sub,  # order in which wrappers are
                    pre  => \&some_other_sub;   # specified doesn't matter

       Once they are installed, the pre- and post-wrappers will be called before and after the
       subroutine itself, and will be passed the same argument list.

       The pre- and post-wrappers and the original subroutine also all see the same (correct!)
       values from "caller" and "wantarray".

   Short-circuiting and long-circuiting return values
       The pre- and post-wrappers both receive an extra argument in their @_ arrays. That extra
       argument is appended to the original argument list (i.e. is can always be accessed as
       $_[-1]) and acts as a place-holder for the original subroutine's return value.

       In a pre-wrapper, $_[-1] is -- for obvious reasons -- "undef". However, $_[-1] may be
       assigned to in a pre-wrapper, in which case Hook::LexWrap assumes that the original
       subroutine has been "pre-empted", and that neither it, nor the corresponding post-wrapper,
       nor any wrappers that were applied before the pre-empting pre-wrapper was installed, need
       be run. Note that any post-wrappers that were installed after the pre-empting pre-wrapper
       was installed will still be called before the original subroutine call returns.

       In a post-wrapper, $_[-1] contains the return value produced by the wrapped subroutine. In
       a scalar return context, this value is the scalar return value. In an list return context,
       this value is a reference to the array of return values. $_[-1] may be assigned to in a
       post-wrapper, and this changes the return value accordingly.

       Access to the arguments and return value is useful for implementing techniques such as
       memoization:

               my %cache;
               wrap fibonacci,
                       pre  => sub { $_[-1] = $cache{$_[0]} if $cache{$_[0]} },
                       post => sub { $cache{$_[0]} = $_[-1] };

       or for converting arguments and return values in a consistent manner:

               # set_temp expects and returns degrees Fahrenheit,
               # but we want to use Celsius
               wrap set_temp,
                       pre   => sub { splice @_, 0, 1, $_[0] * 1.8 + 32 },
                       post  => sub { $_[-1] = ($_[0] - 32) / 1.8 };

   Lexically scoped wrappers
       Normally, any wrappers installed by "wrap" remain attached to the subroutine until it is
       undefined. However, it is possible to make specific wrappers lexically bound, so that they
       operate only until the end of the scope in which they're created (or until some other
       specific point in the code).

       If "wrap" is called in a non-void context:

               my $lexical = wrap 'sub_name', pre => \&wrapper;

       it returns a special object corresponding to the particular wrapper being placed around
       the original subroutine. When that object is destroyed -- when its container variable goes
       out of scope, or when its reference count otherwise falls to zero (e.g. "undef $lexical"),
       or when it is explicitly destroyed ("$lexical->DESTROY") -- the corresponding wrapper is
       removed from around the original subroutine. Note, however, that all other wrappers around
       the subroutine are preserved.

   Anonymous wrappers
       If the subroutine to be wrapped is passed as a reference (rather than by name or by
       typeglob), "wrap" does not install the wrappers around the original subroutine. Instead it
       generates a new subroutine which acts as if it were the original with those wrappers
       around it.  It then returns a reference to that new subroutine. Only calls to the original
       through that wrapped reference invoke the wrappers. Direct by-name calls to the original,
       or calls through another reference, do not.

       If the original is subsequently wrapped by name, the anonymously wrapped subroutine
       reference does not see those wrappers. In other words, wrappers installed via a subroutine
       reference are completely independent of those installed via the subroutine's name (or
       typeglob).

       For example:

               sub original { print "ray" }

               # Wrap anonymously...
               my $anon_wrapped = wrap \&original, pre => sub { print "do..." };

               # Show effects...
               original();             # prints "ray"
               $anon_wrapped->();      # prints "do..ray"

               # Wrap nonymously...
               wrap *original,
                       pre  => sub { print "fa.." },
                       post => sub { print "..mi" };

               # Show effects...
               original();             #   now prints "fa..ray..mi"
               $anon_wrapped->();      # still prints "do...ray"

DIAGNOSTICS

       "Can't wrap non-existent subroutine %s"
           An attempt was made to wrap a subroutine that was not defined at the point of
           wrapping.

       "'pre' value is not a subroutine reference"
           The value passed to "wrap" after the 'pre' flag was not a subroutine reference.
           Typically, someone forgot the "sub" on the anonymous subroutine:

                   wrap 'subname', pre => { your_code_here() };

           and Perl interpreted the last argument as a hash constructor.

       "'post' value is not a subroutine reference"
           The value passed to "wrap" after the 'post' flag was not a subroutine reference.

       "Uselessly wrapped subroutine reference in void context" (warning only)
           When the subroutine to be wrapped is passed as a subroutine reference, "wrap" does not
           install the wrapper around the original, but instead returns a reference to a
           subroutine which wraps the original (see "Anonymous wrappers").

           However, there's no point in doing this if you don't catch the resulting subroutine
           reference.

AUTHOR

       Damian Conway (damian@conway.org)

BLAME

       Schwern made me do this (by implying it wasn't possible ;-)

BUGS

       There are undoubtedly serious bugs lurking somewhere in code this funky :-)

       Bug reports and other feedback are most welcome.

SEE ALSO

       Sub::Prepend

COPYRIGHT

             Copyright (c) 2001, Damian Conway. All Rights Reserved.
           This module is free software. It may be used, redistributed
               and/or modified under the same terms as Perl itself.