Add the original source packages to maemo, source lenny

[dh-make-perl] / dev / i386 / libsub-uplevel-perl / libsub-uplevel-perl-0.1901 / README

diff --git a/dev/i386/libsub-uplevel-perl/libsub-uplevel-perl-0.1901/README b/dev/i386/libsub-uplevel-perl/libsub-uplevel-perl-0.1901/README
new file mode 100644 (file)
index 0000000..1515f66
--- /dev/null
+++ b/dev/i386/libsub-uplevel-perl/libsub-uplevel-perl-0.1901/README
@@ -0,0 +1,109 @@
+NAME
+    Sub::Uplevel - apparently run a function in a higher stack frame
+
+VERSION
+    This documentation describes version 0.1901
+
+SYNOPSIS
+      use Sub::Uplevel;
+
+      sub foo {
+          print join " - ", caller;
+      }
+
+      sub bar {
+          uplevel 1, \&foo;
+      }
+
+      #line 11
+      bar();    # main - foo.plx - 11
+
+DESCRIPTION
+    Like Tcl's uplevel() function, but not quite so dangerous. The idea is
+    just to fool caller(). All the really naughty bits of Tcl's uplevel()
+    are avoided.
+
+    THIS IS NOT THE SORT OF THING YOU WANT TO DO EVERYDAY
+
+    uplevel
+          uplevel $num_frames, \&func, @args;
+
+        Makes the given function think it's being executed $num_frames
+        higher than the current stack level. So when they use
+        caller($frames) it will actually give caller($frames + $num_frames)
+        for them.
+
+        "uplevel(1, \&some_func, @_)" is effectively "goto &some_func" but
+        you don't immediately exit the current subroutine. So while you
+        can't do this:
+
+            sub wrapper {
+                print "Before\n";
+                goto &some_func;
+                print "After\n";
+            }
+
+        you can do this:
+
+            sub wrapper {
+                print "Before\n";
+                my @out = uplevel 1, &some_func;
+                print "After\n";
+                return @out;
+            }
+
+EXAMPLE
+    The main reason I wrote this module is so I could write wrappers around
+    functions and they wouldn't be aware they've been wrapped.
+
+        use Sub::Uplevel;
+
+        my $original_foo = \&foo;
+
+        *foo = sub {
+            my @output = uplevel 1, $original_foo;
+            print "foo() returned:  @output";
+            return @output;
+        };
+
+    If this code frightens you you should not use this module.
+
+BUGS and CAVEATS
+    Well, the bad news is uplevel() is about 5 times slower than a normal
+    function call. XS implementation anyone?
+
+    Sub::Uplevel overrides CORE::GLOBAL::caller temporarily for the scope of
+    each uplevel call. It does its best to work with any previously existing
+    CORE::GLOBAL::caller (both when Sub::Uplevel is first loaded and within
+    each uplevel call) such as from Contextual::Return or Hook::LexWrap.
+
+    However, if you are routinely using multiple modules that override
+    CORE::GLOBAL::caller, you are probably asking for trouble.
+
+HISTORY
+    Those who do not learn from HISTORY are doomed to repeat it.
+
+    The lesson here is simple: Don't sit next to a Tcl programmer at the
+    dinner table.
+
+THANKS
+    Thanks to Brent Welch, Damian Conway and Robin Houston.
+
+AUTHORS
+    David A Golden <dagolden@cpan.org> (current maintainer)
+
+    Michael G Schwern <schwern@pobox.com> (original author)
+
+LICENSE
+    Original code Copyright (c) 2001 to 2007 by Michael G Schwern.
+    Additional code Copyright (c) 2006 to 2008 by David A Golden.
+
+    This program is free software; you can redistribute it and/or modify it
+    under the same terms as Perl itself.
+
+    See http://www.perl.com/perl/misc/Artistic.html
+
+SEE ALSO
+    PadWalker (for the similar idea with lexicals), Hook::LexWrap, Tcl's
+    uplevel() at http://www.scriptics.com/man/tcl8.4/TclCmd/uplevel.htm
+