NAME Sub::Prepend - Prepend code to named subroutines. SYNOPSIS use Sub::Prepend 'prepend'; sub foo ($) { print "Foo executed with \@_ = (@_).\n"; } BEGIN { prepend foo => sub { # This is called before foo executes. print "Foo was called with \@_ = (@_).\n"; push @_, 'and more'; } } my @bar = qw/ foo bar baz /; foo(@bar); # The prototype is preserved! __END__ Foo was called with @_ = (3). Foo executed with @_ = (3 and more). DESCRIPTION "Sub::Prepend" simply conveniently prepends code to named subroutines without any risk of the wrapping itself breaks any existing code. Prepending means that "foo" and "bar" below are equivalent (barring "caller" in the prepended block): prepend foo => sub { ... # prepended }; sub foo { ... # original } sub bar { { ... # prepended } ... # original } This is an initial release, and some things may change for the next version. If you feel something is missing or poorly designed, now is the time to voice your opinion. A key feature of this modules is what it doesn't do. See below. Differences with other modules The goal for a general subroutine wrapper must be to in itself be transparent to the target subroutine. This is currently not possible for wrappers that append code. Thus the act of the wrapping itself, regardless of the added code, may break existing code. Below is a list of features that "Sub::Prepend" has, but it also illustrates the problems with the other modules available as CPAN (see "SEE ALSO"). Fully transparent regarding "caller". When the other module try to append code they also must call the subroutine themselves, adding a call frame visible to "caller". This will break subroutines that rely on "caller". Some modules try to hack around this by overloading "caller" but that solution will fail for subroutines compiled before the wrapper module was loaded. It can also introduce subtle bugs when other modules try to overload "caller" and/or use the "DB" interface. "Sub::Prepend" avoids this by using "goto &foo" which completely hides the intermediate call frame. Fully transparent regarding return contexts (such as void, scalar, list, lvalue, dereference, count, etc). Subroutines that utilize Want to add magic for special contexts, such as optimizing for the number of return values in my ($x, $y) = foo(); a la "split", will usually break if wrapped with the other modules. This is because the return value must be saved away to be returned later, and the call done by the wrapper puts the subroutine call in another context. Simple void/scalar/list context is usually handled correctly. "Sub::Prepend" avoids this in the same way as the issue above: through "goto &foo". Preserves prototypes. In order for code like sub foo ($) { ... } my @bar; foo(@bar); to continue to work as intended for code compiled after the wrapping, the wrapper must set the proper prototype. EXPORTED FUNCTIONS Nothing is exported by default. The ":ALL" tag exports everything that can be exported. prepend($subname => sub { ... }) Makes any call to the subroutine named by $subname first go through the subroutine referenced by the second argument. If the subroutine name isn't fully qualified the current package is assumed (except for symbols that belong to main, such as "ENV" and "_"). The "qualify" function in the standard module Symbol can be used if you want the name to default to another package: use Symbol 'qualify'; prepend( qualify($name => 'Other::Package') => sub { ... } ); Note: The two subroutines *share* @_: sub foo { print "@_" } prepend(foo => sub { unshift @_, 'x' }); foo(1, 2, 3); __END__ x 1 2 3 No attempt is made to fiddle with the calling context for the prepended code. Instead, you can use "caller($Sub::Prepend::CALLER)" as a drop-in replacement for "caller()". DIAGNOSTICS Subroutine &%s not defined (F) You tried to prepend code to a subroutine that wasn't yet defined. EXAMPLES Create hybrid singleton classes Some classes are designed so that class methods act on a shared object, like a singleton class. Let's say "foo" and "bar" are attributes, then such a class could look like package Foo; use strict; use Sub::Prepend 'prepend'; sub new { bless {} => shift } { my $singleton; sub singleton { $singleton ||= shift()->new } } for (qw/ bar baz /) { prepend($_ => sub { unshift @_, shift()->singleton if not ref $_[0]; }); } sub bar { $_[0]->{bar} = $_[1] if @_ > 1; return $_[0]->{bar} } sub baz { $_[0]->{baz} = $_[1] if @_ > 1; return $_[0]->{baz} } Here I used "Sub::Prepend" to add the singleton logic to the attributes. Now "Foo->bar" and "Foo->baz" act like instance methods working on the default object. This is not necessarily a good idea. AUTHOR Johan Lodin COPYRIGHT Copyright 2007-2008 Johan Lodin. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO Hook::WrapSub Hook::PrePostCall Hook::LexWrap