local-lib5/man/man3/Hook::LexWrap.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Hook::LexWrap 3"
 127 .TH Hook::LexWrap 3 "2008-12-18" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Hook::LexWrap \- Lexically scoped subroutine wrappers
 134 .SH "VERSION"
 135 .IX Header "VERSION"
 136 This document describes version 0.21 of Hook::LexWrap,
 137 released November  6, 2008.
 138 .SH "SYNOPSIS"
 139 .IX Header "SYNOPSIS"
 140 .Vb 1
 141 \&        use Hook::LexWrap;
 142 \&
 143 \&        sub doit { print "[doit:", caller, "]"; return {my=>"data"} }
 144 \&
 145 \&        SCOPED: {
 146 \&                wrap doit,
 147 \&                        pre  => sub { print "[pre1: @_]\en" },
 148 \&                        post => sub { print "[post1:@_]\en"; $_[1]=9; };
 149 \&
 150 \&                my $temporarily = wrap doit,
 151 \&                        post => sub { print "[post2:@_]\en" },
 152 \&                        pre  => sub { print "[pre2: @_]\en  "};
 153 \&
 154 \&                @args = (1,2,3);
 155 \&                doit(@args);    # pre2\->pre1\->doit\->post1\->post2
 156 \&        }
 157 \&
 158 \&        @args = (4,5,6);
 159 \&        doit(@args);            # pre1\->doit\->post1
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 Hook::LexWrap allows you to install a pre\- or post-wrapper (or both)
 164 around an existing subroutine. Unlike other modules that provide this
 165 capacity (e.g. Hook::PreAndPost and Hook::WrapSub), Hook::LexWrap
 166 implements wrappers in such a way that the standard \f(CW\*(C`caller\*(C'\fR function
 167 works correctly within the wrapped subroutine.
 168 .PP
 169 To install a prewrappers, you write:
 170 .PP
 171 .Vb 1
 172 \&        use Hook::LexWrap;
 173 \&
 174 \&        wrap \*(Aqsubroutine_name\*(Aq, pre => \e&some_other_sub;
 175 \&
 176 \&   #or: wrap *subroutine_name,  pre => \e&some_other_sub;
 177 .Ve
 178 .PP
 179 The first argument to \f(CW\*(C`wrap\*(C'\fR is a string containing the name of the
 180 subroutine to be wrapped (or the typeglob containing it, or a
 181 reference to it). The subroutine name may be qualified, and the
 182 subroutine must already be defined. The second argument indicates the
 183 type of wrapper being applied and must be either \f(CW\*(Aqpre\*(Aq\fR or
 184 \&\f(CW\*(Aqpost\*(Aq\fR. The third argument must be a reference to a subroutine that
 185 implements the wrapper.
 186 .PP
 187 To install a post-wrapper, you write:
 188 .PP
 189 .Vb 1
 190 \&        wrap \*(Aqsubroutine_name\*(Aq, post => \e&yet_another_sub;
 191 \&
 192 \&   #or: wrap *subroutine_name,  post => \e&yet_another_sub;
 193 .Ve
 194 .PP
 195 To install both at once:
 196 .PP
 197 .Vb 3
 198 \&        wrap \*(Aqsubroutine_name\*(Aq,
 199 \&             pre  => \e&some_other_sub,
 200 \&             post => \e&yet_another_sub;
 201 .Ve
 202 .PP
 203 or:
 204 .PP
 205 .Vb 3
 206 \&        wrap *subroutine_name,
 207 \&             post => \e&yet_another_sub,  # order in which wrappers are
 208 \&             pre  => \e&some_other_sub;   # specified doesn\*(Aqt matter
 209 .Ve
 210 .PP
 211 Once they are installed, the pre\- and post-wrappers will be called before
 212 and after the subroutine itself, and will be passed the same argument list.
 213 .PP
 214 The pre\- and post-wrappers and the original subroutine also all see the same
 215 (correct!) values from \f(CW\*(C`caller\*(C'\fR and \f(CW\*(C`wantarray\*(C'\fR.
 216 .SS "Short-circuiting and long-circuiting return values"
 217 .IX Subsection "Short-circuiting and long-circuiting return values"
 218 The pre\- and post-wrappers both receive an extra argument in their \f(CW@_\fR
 219 arrays. That extra argument is appended to the original argument list
 220 (i.e. is can always be accessed as \f(CW$_\fR[\-1]) and acts as a place-holder for
 221 the original subroutine's return value.
 222 .PP
 223 In a pre-wrapper, \f(CW$_\fR[\-1] is \*(-- for obvious reasons \*(-- \f(CW\*(C`undef\*(C'\fR. However,
 224 \&\f(CW$_\fR[\-1] may be assigned to in a pre-wrapper, in which case Hook::LexWrap
 225 assumes that the original subroutine has been \*(L"pre-empted\*(R", and that
 226 neither it, nor the corresponding post-wrapper, nor any wrappers that
 227 were applied \fIbefore\fR the pre-empting pre-wrapper was installed, need
 228 be run. Note that any post-wrappers that were installed after the
 229 pre-empting pre-wrapper was installed \fIwill\fR still be called before the
 230 original subroutine call returns.
 231 .PP
 232 In a post-wrapper, \f(CW$_\fR[\-1] contains the return value produced by the
 233 wrapped subroutine. In a scalar return context, this value is the scalar
 234 return value. In an list return context, this value is a reference to
 235 the array of return values. \f(CW$_\fR[\-1] may be assigned to in a post-wrapper,
 236 and this changes the return value accordingly.
 237 .PP
 238 Access to the arguments and return value is useful for implementing
 239 techniques such as memoization:
 240 .PP
 241 .Vb 4
 242 \&        my %cache;
 243 \&        wrap fibonacci,
 244 \&                pre  => sub { $_[\-1] = $cache{$_[0]} if $cache{$_[0]} },
 245 \&                post => sub { $cache{$_[0]} = $_[\-1] };
 246 .Ve
 247 .PP
 248 or for converting arguments and return values in a consistent manner:
 249 .PP
 250 .Vb 5
 251 \&        # set_temp expects and returns degrees Fahrenheit,
 252 \&        # but we want to use Celsius
 253 \&        wrap set_temp,
 254 \&                pre   => sub { splice @_, 0, 1, $_[0] * 1.8 + 32 },
 255 \&                post  => sub { $_[\-1] = ($_[0] \- 32) / 1.8 };
 256 .Ve
 257 .SS "Lexically scoped wrappers"
 258 .IX Subsection "Lexically scoped wrappers"
 259 Normally, any wrappers installed by \f(CW\*(C`wrap\*(C'\fR remain attached to the
 260 subroutine until it is undefined. However, it is possible to make
 261 specific wrappers lexically bound, so that they operate only until
 262 the end of the scope in which they're created (or until some other
 263 specific point in the code).
 264 .PP
 265 If \f(CW\*(C`wrap\*(C'\fR is called in a \fInon-void\fR context:
 266 .PP
 267 .Vb 1
 268 \&        my $lexical = wrap \*(Aqsub_name\*(Aq, pre => \e&wrapper;
 269 .Ve
 270 .PP
 271 it returns a special object corresponding to the particular wrapper being
 272 placed around the original subroutine. When that object is destroyed
 273 \&\*(-- when its container variable goes out of scope, or when its
 274 reference count otherwise falls to zero (e.g. \f(CW\*(C`undef $lexical\*(C'\fR), or
 275 when it is explicitly destroyed (\f(CW\*(C`$lexical\->DESTROY\*(C'\fR) \*(--
 276 the corresponding wrapper is removed from around
 277 the original subroutine. Note, however, that all other wrappers around the
 278 subroutine are preserved.
 279 .SS "Anonymous wrappers"
 280 .IX Subsection "Anonymous wrappers"
 281 If the subroutine to be wrapped is passed as a reference (rather than by name
 282 or by typeglob), \f(CW\*(C`wrap\*(C'\fR does not install the wrappers around the
 283 original subroutine. Instead it generates a new subroutine which acts
 284 as if it were the original with those wrappers around it.
 285 It then returns a reference to that new subroutine. Only calls to the original
 286 through that wrapped reference invoke the wrappers. Direct by-name calls to
 287 the original, or calls through another reference, do not.
 288 .PP
 289 If the original is subsequently wrapped by name, the anonymously wrapped
 290 subroutine reference does not see those wrappers. In other words,
 291 wrappers installed via a subroutine reference are completely independent
 292 of those installed via the subroutine's name (or typeglob).
 293 .PP
 294 For example:
 295 .PP
 296 .Vb 1
 297 \&        sub original { print "ray" }
 298 \&
 299 \&        # Wrap anonymously...
 300 \&        my $anon_wrapped = wrap \e&original, pre => sub { print "do..." };
 301 \&
 302 \&        # Show effects...
 303 \&        original();             # prints "ray"
 304 \&        $anon_wrapped\->();      # prints "do..ray"
 305 \&
 306 \&        # Wrap nonymously...
 307 \&        wrap *original,
 308 \&                pre  => sub { print "fa.." },
 309 \&                post => sub { print "..mi" };
 310 \&
 311 \&        # Show effects...
 312 \&        original();             #   now prints "fa..ray..mi"
 313 \&        $anon_wrapped\->();      # still prints "do...ray"
 314 .Ve
 315 .SH "DIAGNOSTICS"
 316 .IX Header "DIAGNOSTICS"
 317 .ie n .IP """Can\*(Aqt wrap non\-existent subroutine %s""" 4
 318 .el .IP "\f(CWCan\*(Aqt wrap non\-existent subroutine %s\fR" 4
 319 .IX Item "Cant wrap non-existent subroutine %s"
 320 An attempt was made to wrap a subroutine that was not defined at the
 321 point of wrapping.
 322 .ie n .IP """\*(Aqpre\*(Aq value is not a subroutine reference""" 4
 323 .el .IP "\f(CW\*(Aqpre\*(Aq value is not a subroutine reference\fR" 4
 324 .IX Item "pre value is not a subroutine reference"
 325 The value passed to \f(CW\*(C`wrap\*(C'\fR after the \f(CW\*(Aqpre\*(Aq\fR flag was not
 326 a subroutine reference. Typically, someone forgot the \f(CW\*(C`sub\*(C'\fR on
 327 the anonymous subroutine:
 328 .Sp
 329 .Vb 1
 330 \&        wrap \*(Aqsubname\*(Aq, pre => { your_code_here() };
 331 .Ve
 332 .Sp
 333 and Perl interpreted the last argument as a hash constructor.
 334 .ie n .IP """\*(Aqpost\*(Aq value is not a subroutine reference""" 4
 335 .el .IP "\f(CW\*(Aqpost\*(Aq value is not a subroutine reference\fR" 4
 336 .IX Item "post value is not a subroutine reference"
 337 The value passed to \f(CW\*(C`wrap\*(C'\fR after the \f(CW\*(Aqpost\*(Aq\fR flag was not
 338 a subroutine reference.
 339 .ie n .IP """Uselessly wrapped subroutine reference in void context"" (warning only)" 4
 340 .el .IP "\f(CWUselessly wrapped subroutine reference in void context\fR (warning only)" 4
 341 .IX Item "Uselessly wrapped subroutine reference in void context (warning only)"
 342 When the subroutine to be wrapped is passed as a subroutine reference,
 343 \&\f(CW\*(C`wrap\*(C'\fR does not install the wrapper around the original, but instead
 344 returns a reference to a subroutine which wraps the original
 345 (see \*(L"Anonymous wrappers\*(R").
 346 .Sp
 347 However, there's no point in doing this if you don't catch the resulting
 348 subroutine reference.
 349 .SH "AUTHOR"
 350 .IX Header "AUTHOR"
 351 Damian Conway (damian@conway.org)
 352 .SH "BLAME"
 353 .IX Header "BLAME"
 354 Schwern made me do this (by implying it wasn't possible ;\-)
 355 .SH "BUGS"
 356 .IX Header "BUGS"
 357 There are undoubtedly serious bugs lurking somewhere in code this funky :\-)
 358 .PP
 359 Bug reports and other feedback are most welcome.
 360 .SH "SEE ALSO"
 361 .IX Header "SEE ALSO"
 362 Sub::Prepend
 363 .SH "COPYRIGHT"
 364 .IX Header "COPYRIGHT"
 365 .Vb 3
 366 \&      Copyright (c) 2001, Damian Conway. All Rights Reserved.
 367 \&    This module is free software. It may be used, redistributed
 368 \&        and/or modified under the same terms as Perl itself.
 369 .Ve