=head1 NAME
Scope::Escape::Continuation - reified escape continuation
=head1 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;
=head1 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 L<Scope::Escape>. This class provides a method-based interface
for
working
with
these continuations. The methods can also be called
directly, as functions, on escape continuations in unblessed form.
See L<Scope::Escape>
for
all the details of the continuations' behaviour.
=head1 CONSTRUCTOR
This class provides
no
constructor method. Use the operator
L<Scope::Escape/current_escape_continuation>.
=head1 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 C<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 L<Scope::Escape> offer a choice of whether generated
continuations are to be blessed.
=over
=item
$escape
->go(VALUE ...)
=item 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 I<VALUE>s may be supplied, which will be
returned from the target stack frame.
The I<VALUE>s are interpreted according to the syntactic context in
which the target of the continuation was invoked. In void context, all
the I<VALUE>s are ignored. In
scalar
context, only the
last
I<VALUE>
is returned, or C<
undef
>
if
no
I<VALUE>s were supplied. In list context,
the full list of I<VALUE>s is used unmodified. Note that this non-
local
context information does not directly influence the evaluation of the
arguments
for
this method. The L</
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.
=item
$escape
->
wantarray
=item 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
L<
wantarray
|perlfunc/
wantarray
> operator: C<
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.
=item
$escape
->is_accessible
=item 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 C<
eval
> stack frames have this effect.
If this method is called on an invalid continuation, the behaviour
is undefined.
=item
$escape
->may_be_valid
=item 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.
=item
$escape
->invalidate
=item Scope::Escape::Continuation::invalidate(ESCAPE)
Marks the continuation as definitely invalid
for
use
. After being
so marked, the L</may_be_valid> method will
return
false
for
the
continuation, and L</go> and other methods will C<
die
>
if
an attempt is
This method may be used on any continuation, even
if
it is already
invalid.
=item
$escape
->as_function
=item Scope::Escape::Continuation::as_function(ESCAPE)
Repackages the continuation as an unblessed function,
as
if
it had originally been generated by the operator
L<Scope::Escape/current_escape_function>.
Returns a reference to the unblessed function.
This method may be used on any continuation, even
if
it is invalid.
=item
$escape
->as_continuation
=item Scope::Escape::Continuation::as_continuation(ESCAPE)
Repackages the continuation as a L<Scope::Escape::Continuation> object,
as
if
it had originally been generated by the operator
L<Scope::Escape/current_escape_continuation>.
Returns a reference to the object.
This method may be used on any continuation, even
if
it is invalid.
=back
=head1 SEE ALSO
L<Scope::Escape>,
L<Scope::Upper>
=head1 AUTHOR
Andrew Main (Zefram) <zefram
@fysh
.org>
=head1 COPYRIGHT
Copyright (C) 2010 Andrew Main (Zefram) <zefram
@fysh
.org>
=head1 LICENSE
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.