NAME

Return::MultiLevel - return across multiple call levels

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). 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.

Implementation notes

This module uses unwind from Scope::Upper to do its work.

If Scope::Upper is not available, it substitutes its own pure Perl implementation, which is based on a combination of eval and goto.

AUTHOR

Lukas Mai, <l.mai at web.de>

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

Return-MultiLevel-0.03