local-lib5/man/man3/Sub::Uplevel.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Sub::Uplevel 3"
 132 .TH Sub::Uplevel 3 "2009-11-17" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Sub::Uplevel \- apparently run a function in a higher stack frame
 135 .SH "VERSION"
 136 .IX Header "VERSION"
 137 This documentation describes version 0.22
 138 .SH "SYNOPSIS"
 139 .IX Header "SYNOPSIS"
 140 .Vb 1
 141 \&  use Sub::Uplevel;
 142 .Ve
 143 .PP
 144 .Vb 3
 145 \&  sub foo {
 146 \&      print join " \- ", caller;
 147 \&  }
 148 .Ve
 149 .PP
 150 .Vb 3
 151 \&  sub bar {
 152 \&      uplevel 1, \e&foo;
 153 \&  }
 154 .Ve
 155 .PP
 156 .Vb 2
 157 \&  #line 11
 158 \&  bar();    # main \- foo.plx \- 11
 159 .Ve
 160 .SH "DESCRIPTION"
 161 .IX Header "DESCRIPTION"
 162 Like Tcl's \fIuplevel()\fR function, but not quite so dangerous.  The idea
 163 is just to fool \fIcaller()\fR.  All the really naughty bits of Tcl's
 164 \&\fIuplevel()\fR are avoided.
 165 .PP
 166 \&\fB\s-1THIS\s0 \s-1IS\s0 \s-1NOT\s0 \s-1THE\s0 \s-1SORT\s0 \s-1OF\s0 \s-1THING\s0 \s-1YOU\s0 \s-1WANT\s0 \s-1TO\s0 \s-1DO\s0 \s-1EVERYDAY\s0\fR
 167 .IP "\fBuplevel\fR" 4
 168 .IX Item "uplevel"
 169 .Vb 1
 170 \&  uplevel $num_frames, \e&func, @args;
 171 .Ve
 172 .Sp
 173 Makes the given function think it's being executed \f(CW$num_frames\fR higher
 174 than the current stack level.  So when they use caller($frames) it
 175 will actually give caller($frames + \f(CW$num_frames\fR) for them.
 176 .Sp
 177 \&\f(CW\*(C`uplevel(1, \e&some_func, @_)\*(C'\fR is effectively \f(CW\*(C`goto &some_func\*(C'\fR but
 178 you don't immediately exit the current subroutine.  So while you can't
 179 do this:
 180 .Sp
 181 .Vb 5
 182 \&    sub wrapper {
 183 \&        print "Before\en";
 184 \&        goto &some_func;
 185 \&        print "After\en";
 186 \&    }
 187 .Ve
 188 .Sp
 189 you can do this:
 190 .Sp
 191 .Vb 6
 192 \&    sub wrapper {
 193 \&        print "Before\en";
 194 \&        my @out = uplevel 1, &some_func;
 195 \&        print "After\en";
 196 \&        return @out;
 197 \&    }
 198 .Ve
 199 .Sp
 200 \&\f(CW\*(C`uplevel\*(C'\fR will issue a warning if \f(CW$num_frames\fR is more than the current call
 201 stack depth.
 202 .SH "EXAMPLE"
 203 .IX Header "EXAMPLE"
 204 The main reason I wrote this module is so I could write wrappers
 205 around functions and they wouldn't be aware they've been wrapped.
 206 .PP
 207 .Vb 1
 208 \&    use Sub::Uplevel;
 209 .Ve
 210 .PP
 211 .Vb 1
 212 \&    my $original_foo = \e&foo;
 213 .Ve
 214 .PP
 215 .Vb 5
 216 \&    *foo = sub {
 217 \&        my @output = uplevel 1, $original_foo;
 218 \&        print "foo() returned:  @output";
 219 \&        return @output;
 220 \&    };
 221 .Ve
 222 .PP
 223 If this code frightens you \fByou should not use this module.\fR
 224 .SH "BUGS and CAVEATS"
 225 .IX Header "BUGS and CAVEATS"
 226 Well, the bad news is \fIuplevel()\fR is about 5 times slower than a normal
 227 function call.  \s-1XS\s0 implementation anyone?  It also slows down every invocation
 228 of \fIcaller()\fR, regardless of whether \fIuplevel()\fR is in effect.
 229 .PP
 230 Sub::Uplevel overrides CORE::GLOBAL::caller temporarily for the scope of
 231 each uplevel call.  It does its best to work with any previously existing
 232 CORE::GLOBAL::caller (both when Sub::Uplevel is first loaded and within
 233 each uplevel call) such as from Contextual::Return or Hook::LexWrap.
 234 .PP
 235 However, if you are routinely using multiple modules that override
 236 CORE::GLOBAL::caller, you are probably asking for trouble.
 237 .PP
 238 You \fBshould\fR load Sub::Uplevel as early as possible within your program.  As
 239 with all \s-1CORE::GLOBAL\s0 overloading, the overload will not affect modules that
 240 have already been compiled prior to the overload.  One module that often is
 241 unavoidably loaded prior to Sub::Uplevel is Exporter.  To forceably recompile
 242 Exporter (and Exporter::Heavy) after loading Sub::Uplevel, use it with the
 243 \&\*(L":aggressive\*(R" tag:
 244 .PP
 245 .Vb 1
 246 \&    use Sub::Uplevel qw/:aggressive/;
 247 .Ve
 248 .PP
 249 The private function \f(CW\*(C`Sub::Uplevel::_force_reload()\*(C'\fR may be passed a list of
 250 additional modules to reload if \*(L":aggressive\*(R" is not aggressive enough.
 251 Reloading modules may break things, so only use this as a last resort.
 252 .PP
 253 As of version 0.20, Sub::Uplevel requires Perl 5.6 or greater.
 254 .SH "HISTORY"
 255 .IX Header "HISTORY"
 256 Those who do not learn from \s-1HISTORY\s0 are doomed to repeat it.
 257 .PP
 258 The lesson here is simple:  Don't sit next to a Tcl programmer at the
 259 dinner table.
 260 .SH "THANKS"
 261 .IX Header "THANKS"
 262 Thanks to Brent Welch, Damian Conway and Robin Houston.
 263 .SH "AUTHORS"
 264 .IX Header "AUTHORS"
 265 David A Golden <dagolden@cpan.org> (current maintainer)
 266 .PP
 267 Michael G Schwern <schwern@pobox.com> (original author)
 268 .SH "LICENSE"
 269 .IX Header "LICENSE"
 270 Original code Copyright (c) 2001 to 2007 by Michael G Schwern.
 271 Additional code Copyright (c) 2006 to 2008 by David A Golden.
 272 .PP
 273 This program is free software; you can redistribute it and/or modify it
 274 under the same terms as Perl itself.
 275 .PP
 276 See http://www.perl.com/perl/misc/Artistic.html
 277 .SH "SEE ALSO"
 278 .IX Header "SEE ALSO"
 279 PadWalker (for the similar idea with lexicals), Hook::LexWrap,
 280 Tcl's \fIuplevel()\fR at http://www.scriptics.com/man/tcl8.4/TclCmd/uplevel.htm