Return...iLevel(3pm)

💖 Return::MultiLevel — Return across multiple call levels 💖

okay so bestie. the header on this one says Return...iLevel(3pm) because the terminal chopped it, but the actual name is Return::MultiLevel and it lives in the perl man pages, section 3pm. and VERSION is version 0.08. periodt. 💅

---

✨ SYNOPSIS ✨

like, just look at it. gorgeous. flawless. no notes.

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

the way that 42 just yeets itself all the way back up through two whole stack frames and lands in $result?? that's the whole vibe. 😭✨

---

🌸 DESCRIPTION 🌸

so this module gives you a way to return immediately from a deeply nested call stack. and like, yes, that sounds like exceptions, but hear me out because it is not the same thing, ngl:

exceptions do not stop automatically at a target frame, and they can be caught by intermediate stack frames using eval. this thing? it does not care. it goes straight to the target and nobody in between gets a vote. in other words, this is more like setjmp(3) / longjmp(3) than die. 🫶

another way to think about it (and honestly this one is kind of iconic): the "multi-level return" coderef represents a single-use / upward-only continuation. it goes up, it goes once, and then it's done. 💀

🎀 Functions 🎀

the following functions are available, and they 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 (and 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. one shot only, bestie. that's the whole deal. 🚫

---

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

so basically: RETURN_MULTILEVEL_PP=1 for "please use the pure perl one," and RETURN_MULTILEVEL_DEBUG=1 for "bestie who did this, show me the receipts." 🔥

---

💀 CAVEATS 💀

You can't use this module to return across implicit function calls, such as:

• signal handlers (like $SIG{ALRM})
• destructors (sub DESTROY { ... })

These are invoked automatically by perl and not part of the normal call chain. so like. no skipping those ones. the vibes simply do not travel there. 🙈

---

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

---

and that's the whole page, bestie!! this one came from perl v5.32.1, dated 2021-12-25, and it's Return...iLevel(3pm) — well, Return::MultiLevel(3pm) if your terminal has the range 💖🎀✨ bye!!