/ 
Scope-Unwind-0.001-TRIAL
River stage zero No dependents
/ Scope::Unwind

NAME

Scope::Unwind - Return to an upper scope

VERSION

version 0.001

DESCRIPTION

This module lets you return from any subroutine in your call stack.

FUNCTIONS

unwind

unwind;
unwind @values, $context;

Returns @values from the subroutine, eval or format context pointed by or just above $context, and immediately restarts the program flow at this point - thus effectively returning @values to an upper scope. If @values is empty, then the $context parameter is optional and defaults to the current context (making the call equivalent to a bare return;) ; otherwise it is mandatory.

The upper context isn't coerced onto @values, which is hence always evaluated in list context. This means that

my $num = sub {
 my @a = ('a' .. 'z');
 unwind @a => HERE;
 # not reached
}->();

will set $num to 'z'.

HERE

my $current_context = HERE;

The context of the current scope.

SUB

my $sub_context = SUB;
my $sub_context = SUB $from;

The context of the closest subroutine above $from. If $from already designates a subroutine context, then it is returned as-is ; hence SUB SUB == SUB. If no subroutine context is present in the call stack, then a warning is emitted and the current context is returned (see "DIAGNOSTICS" for details).

EVAL

my $eval_context = EVAL;
my $eval_context = EVAL $from;

The context of the closest eval above $from. If $from already designates an eval context, then it is returned as-is ; hence EVAL EVAL == EVAL. If no eval context is present in the call stack, then a warning is emitted and the current context is returned (see "DIAGNOSTICS" for details).

UP

my $upper_context = UP;
my $upper_context = UP $from;

The context of the scope just above $from. If $from points to the top-level scope in the current stack, then a warning is emitted and $from is returned (see "DIAGNOSTICS" for details).

TOP

my $top_context = TOP;

Returns the context that currently represents the highest scope.

SCOPE

my $context = SCOPE;
my $context = SCOPE $level;

The $level-th upper context, regardless of its type. If $level points above the top-level scope in the current stack, then a warning is emitted and the top-level context is returned (see "DIAGNOSTICS" for details).

CALLER

my $context = CALLER;
my $context = CALLER $level;

The context of the $level-th upper subroutine/eval/format. It kind of corresponds to the context represented by caller $level, but while e.g. caller 0 refers to the caller context, CALLER 0 will refer to the top scope in the current context. If $level points above the top-level scope in the current stack, then a warning is emitted and the top-level context is returned (see "DIAGNOSTICS" for details).

ACKNOWLEDGEMENTS

This module blatantly steals from Vincent Pit's Scope::Upper, but tried so provide a much more limited functionality set: only unwinding is supported, no localization or destructors in upper scopes

AUTHORS

  • Leon Timmermans <leont@cpan.org>

  • Vincent Pit <vpit@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Vincent Pit, Leon Timmermans.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.