1Sub::WrapPackages(3)  User Contributed Perl Documentation Sub::WrapPackages(3)
2
3
4

NAME

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

SYNOPSIS

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

COMPATIBILITY

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

DESCRIPTION

34       This module installs pre- and post- execution subroutines for the
35       subroutines or packages you specify.  The pre-execution subroutine is
36       passed the wrapped subroutine's name and all its arguments.  The post-
37       execution subroutine is passed the wrapped sub's name and its results.
38
39       The return values from the pre- and post- subs are ignored, and they
40       are called in the same context (void, scalar or list) as the calling
41       code asked for.
42
43       Normal usage is to pass a bunch of parameters when the module is used.
44       However, you can also call Sub::WrapPackages::wrapsubs with the same
45       parameters.
46

PARAMETERS

48       Either pass parameters on loading the module, as above, or pass them to
49       ...
50
51   the wrapsubs subroutine
52       the subs arrayref
53           In the synopsis above, you will see two named parameters, "subs"
54           and "packages".  Any subroutine mentioned in "subs" will be
55           wrapped.  Any subroutines mentioned in 'subs' must already exist -
56           ie their modules must be loaded - at the time you try to wrap them.
57
58       the packages arrayref
59           Any package mentioned here will have all its subroutines wrapped,
60           including any that it imports at load-time.  Packages can be loaded
61           in any order - they don't have to already be loaded for
62           Sub::WrapPackages to work its magic.
63
64           You can specify wildcard packages.  Anything ending in ::* is
65           assumed to be such.  For example, if you specify Orchard::Tree::*,
66           then that matches Orchard::Tree, Orchard::Tree::Pear,
67           Orchard::Apple::KingstonBlack etc, but not - of course - Pine::Tree
68           or My::Orchard::Tree.
69
70           Note, however, that if a module exports a subroutine at load-time
71           using "import" then that sub will be wrapped in the exporting
72           module but not in the importing module.  This is because import()
73           runs before we get a chance to fiddle with things.  Sorry.
74
75           Deferred wrapping of subs in packages that aren't yet loaded works
76           via a subroutine inserted in @INC.  This means that if you mess
77           around with @INC, eg by inserting a directoy at the beginning of
78           the path, the magic might not get a chance to run.  If you "use
79           lib" to mess with @INC though, it should work, as I've over-ridden
80           lib's import() method.  That said, code this funky has no right to
81           work.  Use with caution!
82
83       wrap_inherited
84           In conjunction with the "packages" arrayref, this wraps all calls
85           to inherited methods made through those packages.  If you call
86           those methods directly in the superclass then they are not affected
87           - unless they're wrapped in the superclass of course.
88
89       pre and post
90           References to the subroutines you want to use as wrappers.
91
92       except
93           A regex, any subroutine whose fully-qualified name (ie including
94           the package name) matches this will not be wrapped.
95
96       debug
97           This exists, but probably isn't of much use unless you want to hack
98           on Sub::WrapPackage's guts.
99

BUGS

101       AUTOLOAD and DESTROY are not treated as being special.  I'm not sure
102       whether they should be or not.
103
104       If you use wrap_inherited but classes change their inheritance tree at
105       run-time, then very bad things will happen. VERY BAD THINGS.  So don't
106       do that.  You shouldn't be doing that anyway.  Mind you, you shouldn't
107       be doing the things that this module does either.  BAD PROGRAMMER, NO
108       BIKKIT!
109
110       Bug reports should be made on Github or by email.
111

FEEDBACK

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

SOURCE CODE REPOSITORY

117       <git://github.com/DrHyde/perl-modules-Sub-WrapPackages.git>
118
120       Copyright 2003-2009 David Cantrell <david@cantrell.org.uk>
121
122       This software is free-as-in-speech software, and may be used,
123       distributed, and modified under the terms of either the GNU General
124       Public Licence version 2 or the Artistic Licence. It's up to you which
125       one you use. The full text of the licences can be found in the files
126       GPL2.txt and ARTISTIC.txt, respectively.
127

THANKS TO

129       Thanks to Tom Hukins for sending in a test case for the situation when
130       a class and a subclass are both defined in the same file, and for
131       prompting me to support inherited methods;
132
133       to Dagfinn Ilmari Mannsaker for help with the craziness for fiddling
134       with modules that haven't yet been loaded;
135
136       to Lee Johnson for reporting a bug caused by perl 5.10's constant.pm
137       being Far Too Clever, and providing a patch and test;
138
139       to Adam Trickett who thought this was a jolly good idea;
140
141       to Ed Summers, whose code for figgering out what functions a package
142       contains I borrowed out of Acme::Voodoo;
143
144       and to Yanick Champoux for numerous readability improvements.
145
146
147
148perl v5.34.0                      2021-07-22              Sub::WrapPackages(3)
Impressum