upper scope frames.
VERSION
- Version 0.01
+ Version 0.02
SYNOPSIS
use Scope::Context;
for (1 .. 5) {
sub {
eval {
- # create Scope::Context objects
+ # Create Scope::Context objects for different upper frames.
my ($block, $sub, $eval, $loop);
{
$block = Scope::Context->new;
# This prints "hello" when the eval block above ends.
$eval->reap(sub { print "hello\n" });
- # Ignore $SIG{__DIE__} just for the loop.
+ # Ignore $SIG{__DIE__} just for the loop body.
$loop->localize_delete('%SIG', '__DIE__');
# Execute the callback as if it ran in place of the sub.
# Immediately return (1, 2, 3) from the sub, bypassing the eval.
$sub->unwind(@values, 3);
+
+ # Not reached.
}
+
+ # Not reached.
}->();
+
+ # unwind() returns here. "hello\n" was printed, and now
+ # $SIG{__DIE__} is undefined.
}
DESCRIPTION
thrown if you attempt to act on a context that has already expired. This
means that :
- my $sc;
+ my $cxt;
{
- $sc = Scope::Context->new;
+ $cxt = Scope::Context->new;
}
- $sc->reap(sub { print "hello\n });
+ $cxt->reap(sub { print "hello\n });
will croak when "reap" is called.
METHODS
- "new [ $context ]"
+ "new"
+ my $cxt = Scope::Context->new;
+ my $cxt = Scope::Context->new($scope_upper_cxt);
+
Creates a new immutable Scope::Context object from the
- Scope::Upper-comptabile context $context. If omitted, $context defaults
- to the current context.
+ Scope::Upper-comptabile context identifier $context. If omitted,
+ $context defaults to the current context.
"here"
A synonym for "new".
"cxt"
- Read-only accessor to the Scope::Upper context corresponding to the
- topic Scope::Context object.
+ my $scope_upper_cxt = $cxt->cxt;
+
+ Read-only accessor to the Scope::Upper context identifier associated
+ with the invocant.
"uid"
- Read-only accessor to the Scope::Upper UID of the topic Scope::Context
- object.
+ my $uid = $cxt->uid;
+
+ Read-only accessor to the Scope::Upper unique identifier representing
+ the Scope::Upper context associated with the invocant.
This class also overloads the "==" operator, which will return true if
and only if its two operands are Scope::Context objects that have the
same UID.
"is_valid"
- Returns true if and only if the topic context is still valid (that is,
- it designates a scope that is higher than the topic context in the call
- stack).
+ my $is_valid = $cxt->is_valid;
+
+ Returns true if and only if the invocant is still valid (that is, it
+ designates a scope that is higher on the call stack than the current
+ scope).
"assert_valid"
- Throws an exception if the topic context has expired and is no longer
- valid. Returns true otherwise.
+ $cxt->assert_valid;
+
+ Throws an exception if the invocant has expired and is no longer valid.
+ Returns true otherwise.
+
+ "package"
+ $cxt->package;
+
+ Returns the namespace in use when the scope denoted by the invocant
+ begins.
+
+ "file"
+ $cxt->file;
+
+ Returns the name of the file where the scope denoted by the invocant
+ belongs to.
+
+ "line"
+ $cxt->line;
+
+ Returns the line number where the scope denoted by the invocant begins.
+
+ "sub_name"
+ $cxt->sub_name;
+
+ Returns the name of the subroutine called for this context, or "undef"
+ if this is not a subroutine context.
+
+ "sub_has_args"
+ $cxt->sub_has_args;
+
+ Returns a boolean indicating whether a new instance of @_ was set up for
+ this context, or "undef" if this is not a subroutine context.
+
+ "gimme"
+ $cxt->gimme;
+
+ Returns the context (in the sense of "wantarray" in perlfunc) in which
+ the scope denoted by the invocant is executed.
+
+ "eval_text"
+ $cxt->eval_text;
+
+ Returns the contents of the string being compiled for this context, or
+ "undef" if this is not an eval context.
+
+ "is_require"
+ $cxt->is_require;
+
+ Returns a boolean indicating whether this eval context was created by
+ "require", or "undef" if this is not an eval context.
+
+ "hints_bits"
+ $cxt->hints_bits;
+
+ Returns the value of the lexical hints bit mask (available as $^H at
+ compile time) in use when the scope denoted by the invocant begins.
+
+ "warnings_bits"
+ $cxt->warnings_bits;
+
+ Returns the bit string representing the warnings (available as
+ "${^WARNING_BITS}" at compile time) in use when the scope denoted by the
+ invocant begins.
+
+ "hints_hash"
+ $cxt->hints_hash;
+
+ Returns a reference to the lexical hints hash (available as "%^H" at
+ compile time) in use when the scope denoted by the invocant begins. This
+ method is available only on perl 5.10 and greater.
"want"
+ my $want = $cxt->want;
+
Returns the Perl context (in the sense of "wantarray" : "undef" for void
context, '' for scalar context, and true for list context) in which is
- executed the scope corresponding to the topic Scope::Context object.
+ executed the scope pointed by the invocant.
+
+ "up"
+ my $up_cxt = $cxt->up;
+ my $up_cxt = $cxt->up($frames);
+ my $up_cxt = Scope::Context->up;
- "up [ $frames ]"
Returns a new Scope::Context object pointing to the $frames-th upper
- scope above the topic context.
+ scope above the scope pointed by the invocant.
This method can also be invoked as a class method, in which case it is
- equivalent to calling "up" on a Scope::Context object for the current
- context.
+ equivalent to calling "up" on a Scope::Context object representing the
+ current context.
If omitted, $frames defaults to 1.
}
}
- "sub [ $frames ]"
+ "sub"
+ my $sub_cxt = $cxt->sub;
+ my $sub_cxt = $cxt->sub($frames);
+ my $sub_cxt = Scope::Context->sub;
+
Returns a new Scope::Context object pointing to the $frames-th
- subroutine scope above the topic context.
+ subroutine scope above the scope pointed by the invocant.
This method can also be invoked as a class method, in which case it is
equivalent to calling "sub" on a Scope::Context object for the current
context.
If omitted, $frames defaults to 0, which results in the closest sub
- enclosing the topic context.
+ enclosing the scope pointed by the invocant.
outer();
}
sub inner {
- my $sub = Scope::Context->new->sub(1); # = Scope::Context->sub
+ my $sub = Scope::Context->new->sub(1); # = Scope::Context->sub(1)
# $sub points to the context for the outer() sub.
}
- "eval [ $frames ]"
+ "eval"
+ my $eval_cxt = $cxt->eval;
+ my $eval_cxt = $cxt->eval($frames);
+ my $eval_cxt = Scope::Context->eval;
+
Returns a new Scope::Context object pointing to the $frames-th "eval"
- scope above the topic context.
+ scope above the scope pointed by the invocant.
This method can also be invoked as a class method, in which case it is
equivalent to calling "eval" on a Scope::Context object for the current
context.
If omitted, $frames defaults to 0, which results in the closest eval
- enclosing the topic context.
+ enclosing the scope pointed by the invocant.
eval {
sub {
}->()
}
- "reap $code"
- Execute $code when the topic context ends.
+ "reap"
+ $cxt->reap($code);
+
+ Execute $code when the scope pointed by the invocant ends.
See "reap" in Scope::Upper for details.
- "localize $what, $value"
+ "localize"
+ $cxt->localize($what, $value);
+
Localize the variable described by $what to the value $value when the
- control flow returns to the scope pointed by the topic context.
+ control flow returns to the scope pointed by the invocant.
See "localize" in Scope::Upper for details.
- "localize_elem $what, $key, $value"
+ "localize_elem"
+ $cxt->localize_elem($what, $key, $value);
+
Localize the element $key of the variable $what to the value $value when
- the control flow returns to the scope pointed by the topic context.
+ the control flow returns to the scope pointed by the invocant.
See "localize_elem" in Scope::Upper for details.
- "localize_delete $what, $key"
+ "localize_delete"
+ $cxt->localize_delete($what, $key);
+
Delete the element $key from the variable $what when the control flow
- returns to the scope pointed by the topic context.
+ returns to the scope pointed by the invocant.
See "localize_delete" in Scope::Upper for details.
- "unwind @values"
+ "unwind"
+ $cxt->unwind(@values);
+
Immediately returns the scalars listed in @values from the closest
- subroutine enclosing the topic context.
+ subroutine enclosing the scope pointed by the invocant.
See "unwind" in Scope::Upper for details.
- "uplevel $code, @args"
+ "yield"
+ $cxt->yield(@values);
+
+ Immediately returns the scalars listed in @values from the scope pointed
+ by the invocant, whatever it may be (except a substitution eval
+ context).
+
+ See "yield" in Scope::Upper for details.
+
+ "uplevel"
+ my @ret = $cxt->uplevel($code, @args);
+
Executes the code reference $code with arguments @args in the same
- setting as the closest subroutine enclosing the topic context, then
- returns to the current scope the values returned by $code.
+ setting as the closest subroutine enclosing the scope pointed by the
+ invocant, then returns to the current scope the values returned by
+ $code.
See "uplevel" in Scope::Upper for details.
DEPENDENCIES
Carp (core module since perl 5), Scalar::Util (since 5.7.3).
- Scope::Upper 0.18.
+ Scope::Upper 0.21.
SEE ALSO
Scope::Upper.
perldoc Scope::Context
COPYRIGHT & LICENSE
- Copyright 2011 Vincent Pit, all rights reserved.
+ Copyright 2011,2012,2013 Vincent Pit, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
projects / perl / modules / Scope-Context.git / commitdiff