1NAME 2 Sub::Uplevel - apparently run a function in a higher stack frame 3 4VERSION 5 This documentation describes version 0.22 6 7SYNOPSIS 8 use Sub::Uplevel; 9 10 sub foo { 11 print join " - ", caller; 12 } 13 14 sub bar { 15 uplevel 1, \&foo; 16 } 17 18 #line 11 19 bar(); # main - foo.plx - 11 20 21DESCRIPTION 22 Like Tcl's uplevel() function, but not quite so dangerous. The idea is 23 just to fool caller(). All the really naughty bits of Tcl's uplevel() 24 are avoided. 25 26 THIS IS NOT THE SORT OF THING YOU WANT TO DO EVERYDAY 27 28 uplevel 29 uplevel $num_frames, \&func, @args; 30 31 Makes the given function think it's being executed $num_frames 32 higher than the current stack level. So when they use 33 caller($frames) it will actually give caller($frames + $num_frames) 34 for them. 35 36 `uplevel(1, \&some_func, @_)' is effectively `goto &some_func' but 37 you don't immediately exit the current subroutine. So while you 38 can't do this: 39 40 sub wrapper { 41 print "Before\n"; 42 goto &some_func; 43 print "After\n"; 44 } 45 46 you can do this: 47 48 sub wrapper { 49 print "Before\n"; 50 my @out = uplevel 1, &some_func; 51 print "After\n"; 52 return @out; 53 } 54 55 `uplevel' will issue a warning if `$num_frames' is more than the 56 current call stack depth. 57 58EXAMPLE 59 The main reason I wrote this module is so I could write wrappers around 60 functions and they wouldn't be aware they've been wrapped. 61 62 use Sub::Uplevel; 63 64 my $original_foo = \&foo; 65 66 *foo = sub { 67 my @output = uplevel 1, $original_foo; 68 print "foo() returned: @output"; 69 return @output; 70 }; 71 72 If this code frightens you you should not use this module. 73 74BUGS and CAVEATS 75 Well, the bad news is uplevel() is about 5 times slower than a normal 76 function call. XS implementation anyone? It also slows down every 77 invocation of caller(), regardless of whether uplevel() is in effect. 78 79 Sub::Uplevel overrides CORE::GLOBAL::caller temporarily for the scope of 80 each uplevel call. It does its best to work with any previously existing 81 CORE::GLOBAL::caller (both when Sub::Uplevel is first loaded and within 82 each uplevel call) such as from Contextual::Return or Hook::LexWrap. 83 84 However, if you are routinely using multiple modules that override 85 CORE::GLOBAL::caller, you are probably asking for trouble. 86 87 You should load Sub::Uplevel as early as possible within your program. 88 As with all CORE::GLOBAL overloading, the overload will not affect 89 modules that have already been compiled prior to the overload. One 90 module that often is unavoidably loaded prior to Sub::Uplevel is 91 Exporter. To forceably recompile Exporter (and Exporter::Heavy) after 92 loading Sub::Uplevel, use it with the ":aggressive" tag: 93 94 use Sub::Uplevel qw/:aggressive/; 95 96 The private function `Sub::Uplevel::_force_reload()' may be passed a 97 list of additional modules to reload if ":aggressive" is not aggressive 98 enough. Reloading modules may break things, so only use this as a last 99 resort. 100 101 As of version 0.20, Sub::Uplevel requires Perl 5.6 or greater. 102 103HISTORY 104 Those who do not learn from HISTORY are doomed to repeat it. 105 106 The lesson here is simple: Don't sit next to a Tcl programmer at the 107 dinner table. 108 109THANKS 110 Thanks to Brent Welch, Damian Conway and Robin Houston. 111 112AUTHORS 113 David A Golden <dagolden@cpan.org> (current maintainer) 114 115 Michael G Schwern <schwern@pobox.com> (original author) 116 117LICENSE 118 Original code Copyright (c) 2001 to 2007 by Michael G Schwern. 119 Additional code Copyright (c) 2006 to 2008 by David A Golden. 120 121 This program is free software; you can redistribute it and/or modify it 122 under the same terms as Perl itself. 123 124 See http://www.perl.com/perl/misc/Artistic.html 125 126SEE ALSO 127 PadWalker (for the similar idea with lexicals), Hook::LexWrap, Tcl's 128 uplevel() at http://www.scriptics.com/man/tcl8.4/TclCmd/uplevel.htm 129 130