NAME
    Return::MultiLevel - Return across multiple call levels
VERSION
    version 0.08
SYNOPSIS
      use Return::MultiLevel qw(with_return);
     
      sub inner {
        my ($f) = @_;
        $f->(42);  # implicitly return from 'with_return' below
        print "You don't see this\n";
      }
     
      sub outer {
        my ($f) = @_;
        inner($f);
        print "You don't see this either\n";
      }
     
      my $result = with_return {
        my ($return) = @_;
        outer($return);
        die "Not reached";
      };
      print $result, "\n";  # 42
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 eval). In other words, this is more like
    setjmp(3)/longjmp(3) than die.
    Another way to think about it is that the "multi-level return" coderef
    represents a single-use/upward-only continuation.
 Functions
    The following functions are available (and can be imported on demand).
    with_return BLOCK
      Executes BLOCK, passing it a code reference (called $return in this
      description) as a single argument. Returns whatever BLOCK returns.
      If $return is called, it causes an immediate return from with_return.
      Any arguments passed to $return become with_return's return value (if
      with_return is in scalar context, it will return the last argument
      passed to $return).
      It is an error to invoke $return after its surrounding BLOCK has
      finished executing. In particular, it is an error to call $return
      twice.
DEBUGGING
    This module uses unwind from Scope::Upper to do its work. If
    Scope::Upper 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 RETURN_MULTILEVEL_PP to
    1.
    If you get the error message Attempt to re-enter dead call frame, that
    means something has called a $return from outside of its with_return {
    ... } block. You can get a stack trace of where that with_return was by
    setting the environment variable RETURN_MULTILEVEL_DEBUG to 1.
CAVEATS
    You can't use this module to return across implicit function calls,
    such as signal handlers (like $SIG{ALRM}) or destructors (sub DESTROY {
    ... }). These are invoked automatically by perl and not part of the
    normal call chain.
AUTHORS
      * Lukas Mai
      * Graham Ollis <plicease@cpan.org>
COPYRIGHT AND LICENSE
    This software is copyright (c) 2013,2014,2021 by Lukas Mai.
    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.