git.maemo.org Git - pkg-perl/blob - deb-src/libsub-uplevel-perl/libsub-uplevel-perl-0.1901/README

   1 NAME
   2     Sub::Uplevel - apparently run a function in a higher stack frame
   3
   4 VERSION
   5     This documentation describes version 0.1901
   6
   7 SYNOPSIS
   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
  21 DESCRIPTION
  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 EXAMPLE
  56     The main reason I wrote this module is so I could write wrappers around
  57     functions and they wouldn't be aware they've been wrapped.
  58
  59         use Sub::Uplevel;
  60
  61         my $original_foo = \&foo;
  62
  63         *foo = sub {
  64             my @output = uplevel 1, $original_foo;
  65             print "foo() returned:  @output";
  66             return @output;
  67         };
  68
  69     If this code frightens you you should not use this module.
  70
  71 BUGS and CAVEATS
  72     Well, the bad news is uplevel() is about 5 times slower than a normal
  73     function call. XS implementation anyone?
  74
  75     Sub::Uplevel overrides CORE::GLOBAL::caller temporarily for the scope of
  76     each uplevel call. It does its best to work with any previously existing
  77     CORE::GLOBAL::caller (both when Sub::Uplevel is first loaded and within
  78     each uplevel call) such as from Contextual::Return or Hook::LexWrap.
  79
  80     However, if you are routinely using multiple modules that override
  81     CORE::GLOBAL::caller, you are probably asking for trouble.
  82
  83 HISTORY
  84     Those who do not learn from HISTORY are doomed to repeat it.
  85
  86     The lesson here is simple: Don't sit next to a Tcl programmer at the
  87     dinner table.
  88
  89 THANKS
  90     Thanks to Brent Welch, Damian Conway and Robin Houston.
  91
  92 AUTHORS
  93     David A Golden <dagolden@cpan.org> (current maintainer)
  94
  95     Michael G Schwern <schwern@pobox.com> (original author)
  96
  97 LICENSE
  98     Original code Copyright (c) 2001 to 2007 by Michael G Schwern.
  99     Additional code Copyright (c) 2006 to 2008 by David A Golden.
 100
 101     This program is free software; you can redistribute it and/or modify it
 102     under the same terms as Perl itself.
 103
 104     See http://www.perl.com/perl/misc/Artistic.html
 105
 106 SEE ALSO
 107     PadWalker (for the similar idea with lexicals), Hook::LexWrap, Tcl's
 108     uplevel() at http://www.scriptics.com/man/tcl8.4/TclCmd/uplevel.htm
 109