MAN page from Fedora 14 perl-Sub-WrapPackages-2.0-2.fc14.noarch.rpm

Sub::WrapPackages

Section: User Contributed Perl Documentation (3)
Updated: 2010-03-06
Index

NAME

Sub::WrapPackages - add pre- and post-execution wrappers around all thesubroutines in packages or around individual subs

SYNOPSIS

    use Sub::WrapPackages        packages => [qw(Foo Bar Baz::*)],   # wrap all subs in Foo and Bar                                            #   and any Baz::* packages        subs     => [qw(Barf::a, Barf::b)], # wrap these two subs as well        wrap_inherited => 1,                # and wrap any methods                                            #   inherited by Foo, Bar, or                                            #   Baz::*        pre      => sub {            print "called $_[0] with params ".              join(', ', @_[1..$#_])."\n";        },        post     => sub {            print "$_[0] returned $_[1]\n";        };

COMPATIBILITY

While this module does broadly the same job as the 1.x versions did,the interface may have changed incompatibly. Sorry. Hopefully it'llbe more maintainable and slightly less crazily magical. Also, caller()should now work properly, ignoring wrappings.

DESCRIPTION

This module installs pre- and post- execution subroutines for thesubroutines or packages you specify. The pre-execution subroutineis passed thewrapped subroutine's name and all its arguments. The post-executionsubroutine is passed the wrapped sub's name and its results.

The return values from the pre- and post- subs are ignored, and theyare called in the same context (void, scalar or list) as the callingcode asked for.

Normal usage is to pass a bunch of parameters when the module is used.However, you can also call Sub::WrapPackages::wrapsubs with the sameparameters.

PARAMETERS

Either pass parameters on loading the module, as above, or pass themto ...

the wrapsubs subroutine

the subs arrayref

In the synopsis above, you will see two named parameters, "subs" and"packages". Any subroutine mentioned in "subs" will be wrapped.Any subroutines mentioned in 'subs' must already exist - ie their modulesmust be loaded - at the time you try to wrap them.

the packages arrayref

Any package mentioned here will have all its subroutines wrapped,including any that it imports at load-time. Packages can be loadedin any order - they don't have to already be loaded for Sub::WrapPackagesto work its magic.

You can specify wildcard packages. Anything ending in ::* is assumedto be such. For example, if you specify Orchard::Tree::*, then thatmatches Orchard::Tree, Orchard::Tree::Pear, Orchard::Apple::KingstonBlacketc, but not - of course - Pine::Tree or My::Orchard::Tree.

Note, however, that if a module exports a subroutine at load-time using"import" then that sub will be wrapped in the exporting module but not inthe importing module. This is because import() runs before we get a chanceto fiddle with things. Sorry.

Deferred wrapping of subs in packages that aren't yet loaded worksvia a subroutine inserted in @INC. This means that if you mess aroundwith @INC, eg by inserting a directoy at the beginning of the path, themagic might not get a chance to run. If you "use lib" to mess with@INC though, it should work, as I've over-ridden lib's import() method.That said, code this funky has no right to work. Use with caution!

wrap_inherited

In conjunction with the "packages" arrayref, this wraps all calls toinherited methods made through those packages. If you call thosemethods directly in the superclass then they are not affected - unlessthey're wrapped in the superclass of course.

pre and post

References to the subroutines you want to use as wrappers.

BUGS

AUTOLOAD and DESTROY are not treated as being special. I'm not surewhether they should be or not.

If you use wrap_inherited but classes change their inheritance tree atrun-time, then very bad things will happen. VERY BAD THINGS. So don'tdo that. You shouldn't be doing that anyway. Mind you, you shouldn'tbe doing the things that this module does either. BAD PROGRAMMER, NOBIKKIT!

If you find any other lurking horrors, please report them usinghttps://rt.cpan.org/Public/Dist/Display.html?Name=Sub-WrapPackages <https://rt.cpan.org/Public/Dist/Display.html?Name=Sub-WrapPackages>.

FEEDBACK

I like to know who's using my code. All comments, including constructivecriticism, are welcome. Please email me.

SOURCE CODE REPOSITORY

<http://www.cantrell.org.uk/cgit/cgit.cgi/perlmodules/>

COPYRIGHT and LICENCE

This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

THANKS TO

Thanks to Tom Hukins for sending in a test case for the situation whena class and a subclass are both defined in the same file, and forprompting me to support inherited methods;

to Dagfinn Ilmari Mannsaker for help with the craziness forfiddling with modules that haven't yet been loaded;

to Lee Johnson for reporting a bug caused by perl 5.10'sconstant.pm being Far Too Clever, and providing a patch and test;

to Adam Trickett who thought this was a jolly good idea;

and to EdSummers, whose code for figgering out what functions a package containsI borrowed out of Acme::Voodoo.

Index

the wrapsubs subroutine

BUGS

FEEDBACK

SOURCE CODE REPOSITORY

COPYRIGHT and LICENCE

THANKS TO

This document was created byman2html,using the manual pages.