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.

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.

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:

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.

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).

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.