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 <lodin@cpan.org>

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

cpanm Sub::Prepend

perl -MCPAN -e shell
install Sub::Prepend