.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Return::MultiLevel 3pm" .TH Return::MultiLevel 3pm "2017-10-08" "perl v5.26.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Return::MultiLevel \- return across multiple call levels .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Return::MultiLevel qw(with_return); \& \& sub inner { \& my ($f) = @_; \& $f\->(42); # implicitly return from \*(Aqwith_return\*(Aq below \& print "You don\*(Aqt see this\en"; \& } \& \& sub outer { \& my ($f) = @_; \& inner($f); \& print "You don\*(Aqt see this either\en"; \& } \& \& my $result = with_return { \& my ($return) = @_; \& outer($return); \& die "Not reached"; \& }; \& print $result, "\en"; # 42 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides a way to return immediately from a deeply nested call stack. This is similar to exceptions, but exceptions don't stop automatically at a target frame (and they can be caught by intermediate stack frames using \&\f(CW\*(C`eval\*(C'\fR). In other words, this is more like \&\fIsetjmp\fR\|(3)/\fIlongjmp\fR\|(3) than \f(CW\*(C`die\*(C'\fR. .PP Another way to think about it is that the \*(L"multi-level return\*(R" coderef represents a single\-use/upward\-only continuation. .SS "Functions" .IX Subsection "Functions" The following functions are available (and can be imported on demand). .IP "with_return \s-1BLOCK\s0" 4 .IX Item "with_return BLOCK" Executes \fI\s-1BLOCK\s0\fR, passing it a code reference (called \f(CW$return\fR in this description) as a single argument. Returns whatever \fI\s-1BLOCK\s0\fR returns. .Sp If \f(CW$return\fR is called, it causes an immediate return from \f(CW\*(C`with_return\*(C'\fR. Any arguments passed to \f(CW$return\fR become \f(CW\*(C`with_return\*(C'\fR's return value (if \&\f(CW\*(C`with_return\*(C'\fR is in scalar context, it will return the last argument passed to \&\f(CW$return\fR). .Sp It is an error to invoke \f(CW$return\fR after its surrounding \fI\s-1BLOCK\s0\fR has finished executing. In particular, it is an error to call \f(CW$return\fR twice. .SH "DEBUGGING" .IX Header "DEBUGGING" This module uses \f(CW\*(C`unwind\*(C'\fR from \&\f(CW\*(C`Scope::Upper\*(C'\fR to do its work. If \&\f(CW\*(C`Scope::Upper\*(C'\fR is not available, it substitutes its own pure Perl implementation. You can force the pure Perl version to be used regardless by setting the environment variable \f(CW\*(C`RETURN_MULTILEVEL_PP\*(C'\fR to 1. .PP If you get the error message \f(CW\*(C`Attempt to re\-enter dead call frame\*(C'\fR, that means something has called a \f(CW$return\fR from outside of its \f(CW\*(C`with_return { ... }\*(C'\fR block. You can get a stack trace of where that \f(CW\*(C`with_return\*(C'\fR was by setting the environment variable \f(CW\*(C`RETURN_MULTILEVEL_DEBUG\*(C'\fR to 1. .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" You can't use this module to return across implicit function calls, such as signal handlers (like \f(CW$SIG{ALRM}\fR) or destructors (\f(CW\*(C`sub DESTROY { ... }\*(C'\fR). These are invoked automatically by perl and not part of the normal call chain. .SH "SUPPORT AND DOCUMENTATION" .IX Header "SUPPORT AND DOCUMENTATION" After installing, you can find documentation for this module with the \&\f(CW\*(C`perldoc\*(C'\fR command. .PP .Vb 1 \& perldoc Return::MultiLevel .Ve .PP You can also look for information at . .PP To see a list of open bugs, visit . .PP To report a new bug, send an email to \&\f(CW\*(C`bug\-Return\-MultiLevel [at] rt.cpan.org\*(C'\fR. .SH "AUTHOR" .IX Header "AUTHOR" Lukas Mai, \f(CW\*(C`\*(C'\fR .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2013\-2014 Lukas Mai. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: the \s-1GNU\s0 General Public License as published by the Free Software Foundation; or the Artistic License. .PP See for more information.