=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.  See L<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
L<Scope::Escape/current_escape_continuation>) and the similar unblessed
continuations (generated by L<Scope::Escape/current_escape_function>)
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.

=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
made to use it.

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, 2011, 2017 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.