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 <[email protected]>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.