Hook::LexWrap(3) User Contributed Perl Documentation Hook::LexWrap(3)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.
perl v5.12.5 2013-08-25 Hook::LexWrap(3)
