.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Sub::WrapPackages 3pm" .TH Sub::WrapPackages 3pm "2022-07-23" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Sub::WrapPackages \- add pre\- and post\-execution wrappers around all the subroutines in packages or around individual subs .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& 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\*(Aqt wrap any sub called \& # wibble or wobble \& pre => sub { \& print "called $_[0] with params ". \& join(\*(Aq, \*(Aq, @_[1..$#_])."\en"; \& }, \& post => sub { \& print "$_[0] returned $_[1]\en"; \& }; .Ve .SH "COMPATIBILITY" .IX Header "COMPATIBILITY" 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, \fBcaller()\fR should now work properly, ignoring wrappings. .SH "DESCRIPTION" .IX Header "DESCRIPTION" 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. .PP 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. .PP 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 parameters. .SH "PARAMETERS" .IX Header "PARAMETERS" Either pass parameters on loading the module, as above, or pass them to ... .SS "the wrapsubs subroutine" .IX Subsection "the wrapsubs subroutine" .IP "the subs arrayref" 4 .IX Item "the subs arrayref" In the synopsis above, you will see two named parameters, \f(CW\*(C`subs\*(C'\fR and \&\f(CW\*(C`packages\*(C'\fR. Any subroutine mentioned in \f(CW\*(C`subs\*(C'\fR 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. .IP "the packages arrayref" 4 .IX Item "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. .Sp 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. .Sp Note, however, that if a module exports a subroutine at load-time using \&\f(CW\*(C`import\*(C'\fR then that sub will be wrapped in the exporting module but not in the importing module. This is because \fBimport()\fR runs before we get a chance to fiddle with things. Sorry. .Sp Deferred wrapping of subs in packages that aren't yet loaded works via a subroutine inserted in \f(CW@INC\fR. This means that if you mess around with \f(CW@INC\fR, eg by inserting a directoy at the beginning of the path, the magic might not get a chance to run. If you \f(CW\*(C`use lib\*(C'\fR to mess with \&\f(CW@INC\fR though, it should work, as I've over-ridden lib's \fBimport()\fR method. That said, code this funky has no right to work. Use with caution! .IP "wrap_inherited" 4 .IX Item "wrap_inherited" In conjunction with the \f(CW\*(C`packages\*(C'\fR 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. .IP "pre and post" 4 .IX Item "pre and post" References to the subroutines you want to use as wrappers. .IP "except" 4 .IX Item "except" A regex, any subroutine whose fully-qualified name (ie including the package name) matches this will not be wrapped. .IP "debug" 4 .IX Item "debug" This exists, but probably isn't of much use unless you want to hack on Sub::WrapPackage's guts. .SH "BUGS" .IX Header "BUGS" \&\s-1AUTOLOAD\s0 and \s-1DESTROY\s0 are not treated as being special. I'm not sure whether they should be or not. .PP If you use wrap_inherited but classes change their inheritance tree at run-time, then very bad things will happen. \s-1VERY BAD THINGS.\s0 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. \s-1BAD PROGRAMMER, NO BIKKIT\s0! .PP Bug reports should be made on Github or by email. .SH "FEEDBACK" .IX Header "FEEDBACK" I like to know who's using my code. All comments, including constructive criticism, are welcome. Please email me. .SH "SOURCE CODE REPOSITORY" .IX Header "SOURCE CODE REPOSITORY" .SH "COPYRIGHT and LICENCE" .IX Header "COPYRIGHT and LICENCE" Copyright 2003\-2009 David Cantrell <\fIdavid@cantrell.org.uk\fR> .PP This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the \s-1GNU\s0 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 \s-1GPL2\s0.txt and \s-1ARTISTIC\s0.txt, respectively. .SH "THANKS TO" .IX Header "THANKS TO" 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; .PP to Dagfinn Ilmari Mannsaker for help with the craziness for fiddling with modules that haven't yet been loaded; .PP to Lee Johnson for reporting a bug caused by perl 5.10's constant.pm being Far Too Clever, and providing a patch and test; .PP to Adam Trickett who thought this was a jolly good idea; .PP to Ed Summers, whose code for figgering out what functions a package contains I borrowed out of Acme::Voodoo; .PP and to Yanick Champoux for numerous readability improvements.