2 Scope::Context - Object-oriented interface for inspecting or acting upon
14 # Create Scope::Context objects for different upper frames.
15 my ($block, $sub, $eval, $loop);
17 $block = Scope::Context->new;
18 $sub = $block->sub; # = $block->up
19 $eval = $block->eval; # = $block->up(2)
20 $loop = $eval->up; # = $block->up(3)
24 # This will throw an exception, since $block has expired.
25 $block->localize('$x' => 1);
28 # This prints "hello" when the eval block above ends.
29 $eval->reap(sub { print "hello\n" });
31 # Ignore $SIG{__DIE__} just for the loop body.
32 $loop->localize_delete('%SIG', '__DIE__');
34 # Execute the callback as if it ran in place of the sub.
35 my @values = $sub->uplevel(sub {
39 # Immediately return (1, 2, 3) from the sub, bypassing the eval.
40 $sub->unwind(@values, 3);
48 # unwind() returns here. "hello\n" was printed, and now
49 # $SIG{__DIE__} is undefined.
53 This class provides an object-oriented interface to Scope::Upper's
54 functionalities. A Scope::Context object represents a currently active
55 dynamic scope (or context), and encapsulates the corresponding
56 Scope::Upper-compatible context identifier. All of Scope::Upper's
57 functions are then made available as methods. This gives you a prettier
58 and safer interface when you are not reaching for extreme performance,
59 but rest assured that the overhead of this module is minimal anyway.
61 The Scope::Context methods actually do more than their subroutine
62 counterparts from Scope::Upper : before each call, the target context
63 will be checked to ensure it is still active (which means that it is
64 still present in the current call stack), and an exception will be
65 thrown if you attempt to act on a context that has already expired. This
70 $cxt = Scope::Context->new;
72 $cxt->reap(sub { print "hello\n });
74 will croak when "reap" is called.
78 my $cxt = Scope::Context->new;
79 my $cxt = Scope::Context->new($scope_upper_cxt);
81 Creates a new immutable Scope::Context object from the
82 Scope::Upper-comptabile context identifier $context. If omitted,
83 $context defaults to the current context.
89 my $scope_upper_cxt = $cxt->cxt;
91 Read-only accessor to the Scope::Upper context identifier associated
97 Read-only accessor to the Scope::Upper unique identifier representing
98 the Scope::Upper context associated with the invocant.
100 This class also overloads the "==" operator, which will return true if
101 and only if its two operands are Scope::Context objects that have the
105 my $is_valid = $cxt->is_valid;
107 Returns true if and only if the invocant is still valid (that is, it
108 designates a scope that is higher on the call stack than the current
114 Throws an exception if the invocant has expired and is no longer valid.
115 Returns true otherwise.
120 Returns the namespace in use when the scope denoted by the invocant
126 Returns the name of the file where the scope denoted by the invocant
132 Returns the line number where the scope denoted by the invocant begins.
137 Returns the name of the subroutine called for this context, or "undef"
138 if this is not a subroutine context.
143 Returns a boolean indicating whether a new instance of @_ was set up for
144 this context, or "undef" if this is not a subroutine context.
149 Returns the context (in the sense of "wantarray" in perlfunc) in which
150 the scope denoted by the invocant is executed.
155 Returns the contents of the string being compiled for this context, or
156 "undef" if this is not an eval context.
161 Returns a boolean indicating whether this eval context was created by
162 "require", or "undef" if this is not an eval context.
167 Returns the value of the lexical hints bit mask (available as $^H at
168 compile time) in use when the scope denoted by the invocant begins.
173 Returns the bit string representing the warnings (available as
174 "${^WARNING_BITS}" at compile time) in use when the scope denoted by the
180 Returns a reference to the lexical hints hash (available as "%^H" at
181 compile time) in use when the scope denoted by the invocant begins. This
182 method is available only on perl 5.10 and greater.
185 my $want = $cxt->want;
187 Returns the Perl context (in the sense of "wantarray" : "undef" for void
188 context, '' for scalar context, and true for list context) in which is
189 executed the scope pointed by the invocant.
192 my $up_cxt = $cxt->up;
193 my $up_cxt = $cxt->up($frames);
194 my $up_cxt = Scope::Context->up;
196 Returns a new Scope::Context object pointing to the $frames-th upper
197 scope above the scope pointed by the invocant.
199 This method can also be invoked as a class method, in which case it is
200 equivalent to calling "up" on a Scope::Context object representing the
203 If omitted, $frames defaults to 1.
208 my $up = Scope::Context->new->up(2); # = Scope::Context->up(2)
209 # $up points two contextes above this one, which is the sub.
215 my $sub_cxt = $cxt->sub;
216 my $sub_cxt = $cxt->sub($frames);
217 my $sub_cxt = Scope::Context->sub;
219 Returns a new Scope::Context object pointing to the $frames-th
220 subroutine scope above the scope pointed by the invocant.
222 This method can also be invoked as a class method, in which case it is
223 equivalent to calling "sub" on a Scope::Context object for the current
226 If omitted, $frames defaults to 0, which results in the closest sub
227 enclosing the scope pointed by the invocant.
236 my $sub = Scope::Context->new->sub(1); # = Scope::Context->sub(1)
237 # $sub points to the context for the outer() sub.
241 my $eval_cxt = $cxt->eval;
242 my $eval_cxt = $cxt->eval($frames);
243 my $eval_cxt = Scope::Context->eval;
245 Returns a new Scope::Context object pointing to the $frames-th "eval"
246 scope above the scope pointed by the invocant.
248 This method can also be invoked as a class method, in which case it is
249 equivalent to calling "eval" on a Scope::Context object for the current
252 If omitted, $frames defaults to 0, which results in the closest eval
253 enclosing the scope pointed by the invocant.
257 my $eval = Scope::Context->new->eval; # = Scope::Context->eval
258 # $eval points to the eval context.
265 Execute $code when the scope pointed by the invocant ends.
267 See "reap" in Scope::Upper for details.
270 $cxt->localize($what, $value);
272 Localize the variable described by $what to the value $value when the
273 control flow returns to the scope pointed by the invocant.
275 See "localize" in Scope::Upper for details.
278 $cxt->localize_elem($what, $key, $value);
280 Localize the element $key of the variable $what to the value $value when
281 the control flow returns to the scope pointed by the invocant.
283 See "localize_elem" in Scope::Upper for details.
286 $cxt->localize_delete($what, $key);
288 Delete the element $key from the variable $what when the control flow
289 returns to the scope pointed by the invocant.
291 See "localize_delete" in Scope::Upper for details.
294 $cxt->unwind(@values);
296 Immediately returns the scalars listed in @values from the closest
297 subroutine enclosing the scope pointed by the invocant.
299 See "unwind" in Scope::Upper for details.
302 $cxt->yield(@values);
304 Immediately returns the scalars listed in @values from the scope pointed
305 by the invocant, whatever it may be (except a substitution eval
308 See "yield" in Scope::Upper for details.
311 my @ret = $cxt->uplevel($code, @args);
313 Executes the code reference $code with arguments @args in the same
314 setting as the closest subroutine enclosing the scope pointed by the
315 invocant, then returns to the current scope the values returned by
318 See "uplevel" in Scope::Upper for details.
321 Carp (core module since perl 5), Scalar::Util (since 5.7.3).
328 Continuation::Escape.
331 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
333 You can contact me by mail or on "irc.perl.org" (vincent).
336 Please report any bugs or feature requests to "bug-scope-context at
337 rt.cpan.org", or through the web interface at
338 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Context>. I will
339 be notified, and then you'll automatically be notified of progress on
340 your bug as I make changes.
343 You can find documentation for this module with the perldoc command.
345 perldoc Scope::Context
348 Copyright 2011,2012,2013 Vincent Pit, all rights reserved.
350 This program is free software; you can redistribute it and/or modify it
351 under the same terms as Perl itself.