Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Sub::WrapPackages(3)  User Contributed Perl Documentation Sub::WrapPackages(3)

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

	   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::*
	       except	=> qr/::w[oi]bble$/,	   # but don't wrap any	sub called
						   #   wibble or wobble
	       pre	=> sub {
		   print "called $_[0] with params ".
		     join(', ',	@_[1..$#_])."\n";
	       post	=> sub {
		   print "$_[0]	returned $_[1]\n";

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

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

       The return values from the pre- and post- subs are ignored, and they
       are called in the same context (void, scalar or list) as	the calling
       code 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 same

       Either pass parameters on loading the module, as	above, or pass them to

   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 modules must 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	loaded
	   in any order	- they don't have to already be	loaded for
	   Sub::WrapPackages to	work its magic.

	   You can specify wildcard packages.  Anything	ending in ::* is
	   assumed to be such.	For example, if	you specify Orchard::Tree::*,
	   then	that matches Orchard::Tree, Orchard::Tree::Pear,
	   Orchard::Apple::KingstonBlack etc, 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 in the importing module.  This is because import()
	   runs	before we get a	chance to fiddle with things.  Sorry.

	   Deferred wrapping of	subs in	packages that aren't yet loaded	works
	   via a subroutine inserted in	@INC.  This means that if you mess
	   around with @INC, eg	by inserting a directoy	at the beginning of
	   the path, the magic 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!

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

       pre and post
	   References to the subroutines you want to use as wrappers.

	   A regex, any	subroutine whose fully-qualified name (ie including
	   the package name) matches this will not be wrapped.

	   This	exists,	but probably isn't of much use unless you want to hack
	   on Sub::WrapPackage's guts.

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

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

       Bug reports should be made on Github or by email.

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


       Copyright 2003-2009 David Cantrell <>

       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 Tom Hukins for	sending	in a test case for the situation when
       a class and a subclass are both defined in the same file, and for
       prompting me to support inherited methods;

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

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

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

       to Ed Summers, whose code for figgering out what	functions a package
       contains	I borrowed out of Acme::Voodoo;

       and to Yanick Champoux for numerous readability improvements.

perl v5.32.1			  2017-10-25		  Sub::WrapPackages(3)


Want to link to this manual page? Use this URL:

home | help