NAME

Scope::Escape::Continuation - reified escape continuation

SYNOPSIS

$escape->go($result);
if($escape->wantarray) { ...
if($escape->is_accessible) { ...

if($escape->may_be_valid) { ...
$escape->invalidate;

$escape = $escape->as_function;
$escape = $escape->as_continuation;

DESCRIPTION

An object of this class is the reified form of an escape continuation, referencing some Perl stack frame, as generated by one of the operators in Scope::Escape. This class provides a method-based interface for working with these continuations. See Scope::Escape for all the details of the continuations' behaviour.

In addition to being blessed, objects of this class are Perl functions, and can be invoked by ordinary calling. The only difference between these blessed continuations (generated by "current_escape_continuation" in Scope::Escape) and the similar unblessed continuations (generated by "current_escape_function" in Scope::Escape) is whether they are blessed. As a result, the methods of this class can be called directly, as functions, on escape continuations in either form.

CONSTRUCTOR

This class provides no constructor method. Use the operator "current_escape_continuation" in Scope::Escape.

METHODS

Each of these methods can be called in two ways. Firstly, it can be called as a method, looked up in the ordinary way, on a continuation that is blessed into this class. Secondly, it can be called as a function, located in the Scope::Escape::Continuation package, with its first argument being a continuation object. When calling as a function, it doesn't matter whether the continuation is blessed into this class. The operators in Scope::Escape offer a choice of whether generated continuations are to be blessed.

$escape->go(VALUE ...)

Scope::Escape::Continuation::go(ESCAPE, VALUE ...)

Transfers control through the continuation. This method/function does not return in the ordinary way; instead, the stack frame (block) that is the target of the continuation returns, with intermediate stack frames being abandoned. Zero or more VALUEs may be supplied, which will be returned from the target stack frame.

The VALUEs are interpreted according to the syntactic context in which the target of the continuation was invoked. In void context, all the VALUEs are ignored. In scalar context, only the last VALUE is returned, or undef if no VALUEs were supplied. In list context, the full list of VALUEs is used unmodified. Note that this non-local context information does not directly influence the evaluation of the arguments for this method. The "wantarray" method provides a way to detect the context, if it is desired to return different values depending on it.

The same effect as this method/function can be achieved by calling the continuation object itself as a function.

If this method is called on an invalid continuation, the behaviour is undefined.

$escape->wantarray

Scope::Escape::Continuation::wantarray(ESCAPE)

Indicates the syntactic context in which the target of the continuation was invoked, and thus what kind of return value is desired when transferring through the continuation. The return value of this method/function is to be interpreted the same way as that of the core wantarray operator: undef for void context, defined but false for scalar context, true for list context.

If this method is called on an invalid continuation, the behaviour is undefined.

$escape->is_accessible

Scope::Escape::Continuation::is_accessible(ESCAPE)

Returns a truth value indicating whether it is possible to transfer through the continuation from the current stack frame. This is normally true, provided that the continuation is valid. It is false if there is a stack frame, between the current one and the target of the continuation, that blocks unwinding. Most eval stack frames have this effect.

If this method is called on an invalid continuation, the behaviour is undefined.

$escape->may_be_valid

Scope::Escape::Continuation::may_be_valid(ESCAPE)

Returns a truth value indicating whether the continuation might still be valid for use. This facility does not guarantee to detect if a continuation is invalid, hence the name. A false return indicates that the continuation is definitely invalid. A true return yields no solid information.

This method may be used on any continuation, even if it is invalid.

$escape->invalidate

Scope::Escape::Continuation::invalidate(ESCAPE)

Marks the continuation as definitely invalid for use. After being so marked, the "may_be_valid" method will return false for the continuation, and "go" and other methods will die if an attempt is made to use it.

This method may be used on any continuation, even if it is already invalid.

$escape->as_function

Scope::Escape::Continuation::as_function(ESCAPE)

Repackages the continuation as an unblessed function, as if it had originally been generated by the operator "current_escape_function" in Scope::Escape. Returns a reference to the unblessed function.

This method may be used on any continuation, even if it is invalid.

$escape->as_continuation

Scope::Escape::Continuation::as_continuation(ESCAPE)

Repackages the continuation as a Scope::Escape::Continuation object, as if it had originally been generated by the operator "current_escape_continuation" in Scope::Escape. Returns a reference to the object.

This method may be used on any continuation, even if it is invalid.

SEE ALSO

Scope::Escape, Scope::Upper

AUTHOR

Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

Copyright (C) 2010, 2011, 2017 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

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