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

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.

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: