1Sub::WrapPackages(3) User Contributed Perl Documentation Sub::WrapPackages(3)
2
6 Sub::WrapPackages - add pre- and post-execution wrappers around all the
7 subroutines in packages or around individual subs
8
10 use Sub::WrapPackages
11 packages => [qw(Foo Bar Baz::*)], # wrap all subs in Foo and Bar
12 # and any Baz::* packages
13 subs => [qw(Barf::a, Barf::b)], # wrap these two subs as well
14 wrap_inherited => 1, # and wrap any methods
15 # inherited by Foo, Bar, or
16 # Baz::*
17 pre => sub {
18 print "called $_[0] with params ".
19 join(', ', @_[1..$#_])."\n";
20 },
21 post => sub {
22 print "$_[0] returned $_[1]\n";
23 };
24
26 While this module does broadly the same job as the 1.x versions did,
27 the interface may have changed incompatibly. Sorry. Hopefully it'll
28 be more maintainable and slightly less crazily magical. Also, caller()
29 should now work properly, ignoring wrappings.
30
32 This module installs pre- and post- execution subroutines for the
33 subroutines or packages you specify. The pre-execution subroutine is
34 passed the wrapped subroutine's name and all its arguments. The post-
35 execution subroutine is passed the wrapped sub's name and its results.
36 The return values from the pre- and post- subs are ignored, and they
38 are called in the same context (void, scalar or list) as the calling
39 code asked for.
40 Normal usage is to pass a bunch of parameters when the module is used.
42 However, you can also call Sub::WrapPackages::wrapsubs with the same
43 parameters.
44
46 Either pass parameters on loading the module, as above, or pass them to
47 ...
48 the wrapsubs subroutine
50 the subs arrayref
51 In the synopsis above, you will see two named parameters, "subs"
52 and "packages". Any subroutine mentioned in "subs" will be
53 wrapped. Any subroutines mentioned in 'subs' must already exist -
54 ie their modules must be loaded - at the time you try to wrap them.
55 the packages arrayref
57 Any package mentioned here will have all its subroutines wrapped,
58 including any that it imports at load-time. Packages can be loaded
59 in any order - they don't have to already be loaded for
60 Sub::WrapPackages to work its magic.
61 You can specify wildcard packages. Anything ending in ::* is
63 assumed to be such. For example, if you specify Orchard::Tree::*,
64 then that matches Orchard::Tree, Orchard::Tree::Pear,
65 Orchard::Apple::KingstonBlack etc, but not - of course - Pine::Tree
66 or My::Orchard::Tree.
67 Note, however, that if a module exports a subroutine at load-time
69 using "import" then that sub will be wrapped in the exporting
70 module but not in the importing module. This is because import()
71 runs before we get a chance to fiddle with things. Sorry.
72 Deferred wrapping of subs in packages that aren't yet loaded works
74 via a subroutine inserted in @INC. This means that if you mess
75 around with @INC, eg by inserting a directoy at the beginning of
76 the path, the magic might not get a chance to run. If you "use
77 lib" to mess with @INC though, it should work, as I've over-ridden
78 lib's import() method. That said, code this funky has no right to
79 work. Use with caution!
80 wrap_inherited
82 In conjunction with the "packages" arrayref, this wraps all calls
83 to inherited methods made through those packages. If you call
84 those methods directly in the superclass then they are not affected
85 - unless they're wrapped in the superclass of course.
86 pre and post
88 References to the subroutines you want to use as wrappers.
89
91 AUTOLOAD and DESTROY are not treated as being special. I'm not sure
92 whether they should be or not.
93 If you use wrap_inherited but classes change their inheritance tree at
95 run-time, then very bad things will happen. VERY BAD THINGS. So don't
96 do that. You shouldn't be doing that anyway. Mind you, you shouldn't
97 be doing the things that this module does either. BAD PROGRAMMER, NO
98 BIKKIT!
99 If you find any other lurking horrors, please report them using
101 https://rt.cpan.org/Public/Dist/Display.html?Name=Sub-WrapPackages
102 <https://rt.cpan.org/Public/Dist/Display.html?Name=Sub-WrapPackages>.
103
105 I like to know who's using my code. All comments, including
106 constructive criticism, are welcome. Please email me.
107
109 <http://www.cantrell.org.uk/cgit/cgit.cgi/perlmodules/>
110
112 Copyright 2003-2009 David Cantrell <david@cantrell.org.uk>
113 This software is free-as-in-speech software, and may be used,
115 distributed, and modified under the terms of either the GNU General
116 Public Licence version 2 or the Artistic Licence. It's up to you which
117 one you use. The full text of the licences can be found in the files
118 GPL2.txt and ARTISTIC.txt, respectively.
119
121 Thanks to Tom Hukins for sending in a test case for the situation when
122 a class and a subclass are both defined in the same file, and for
123 prompting me to support inherited methods;
124 to Dagfinn Ilmari Mannsaker for help with the craziness for fiddling
126 with modules that haven't yet been loaded;
127 to Lee Johnson for reporting a bug caused by perl 5.10's constant.pm
129 being Far Too Clever, and providing a patch and test;
130 to Adam Trickett who thought this was a jolly good idea;
132 and to Ed Summers, whose code for figgering out what functions a
134 package contains I borrowed out of Acme::Voodoo.
135perl v5.12.2 2010-03-06 Sub::WrapPackages(3)