2 Scope::Context - Object-oriented interface for inspecting or acting upon
14 # Create Scope::Context objects for different upper frames :
15 my ($block, $eval, $sub, $loop);
17 $block = Scope::Context->new;
18 $eval = $block->eval; # == $block->up
19 $sub = $block->sub; # == $block->up(2)
20 $loop = $sub->up; # == $block->up(3)
24 # This throws an exception, since $block has expired :
25 $block->localize('$x' => 1);
28 # This will print "hello" when the current eval block ends :
29 $eval->reap(sub { print "hello\n" });
31 # Ignore warnings just for the loop body :
32 $loop->localize_elem('%SIG', __WARN__ => sub { });
34 # Execute the callback as if it ran in place of the sub :
35 my @values = $sub->uplevel(sub {
38 # @values now contains (1, 2).
40 # Immediately return (1, 2, 3) from the sub, bypassing the eval :
41 $sub->unwind(@values, 3);
49 # unwind() returns here. "hello\n" was printed, and now warnings are
53 # $SIG{__WARN__} has been restored to its original value, warnings are no
57 This class provides an object-oriented interface to Scope::Upper's
58 functionalities. A Scope::Context object represents a currently active
59 dynamic scope (or context), and encapsulates the corresponding
60 Scope::Upper-compatible context identifier. All of Scope::Upper's
61 functions are then made available as methods. This gives you a prettier
62 and safer interface when you are not reaching for extreme performance,
63 but rest assured that the overhead of this module is minimal anyway.
65 The Scope::Context methods actually do more than their subroutine
66 counterparts from Scope::Upper : before each call, the target context
67 will be checked to ensure it is still active (which means that it is
68 still present in the current call stack), and an exception will be
69 thrown if you attempt to act on a context that has already expired. This
74 $cxt = Scope::Context->new;
76 $cxt->reap(sub { print "hello\n });
78 will croak when "reap" is called.
82 my $cxt = Scope::Context->new;
83 my $cxt = Scope::Context->new($scope_upper_cxt);
85 Creates a new immutable Scope::Context object from the
86 Scope::Upper-comptabile context identifier $context. If omitted,
87 $context defaults to the current context.
93 my $scope_upper_cxt = $cxt->cxt;
95 Read-only accessor to the Scope::Upper context identifier associated
101 Read-only accessor to the Scope::Upper unique identifier representing
102 the Scope::Upper context associated with the invocant.
104 This class also overloads the "==" operator, which will return true if
105 and only if its two operands are Scope::Context objects that have the
109 my $is_valid = $cxt->is_valid;
111 Returns true if and only if the invocant is still valid (that is, it
112 designates a scope that is higher on the call stack than the current
118 Throws an exception if the invocant has expired and is no longer valid.
119 Returns true otherwise.
124 Returns the namespace in use when the scope denoted by the invocant
130 Returns the name of the file where the scope denoted by the invocant
136 Returns the line number where the scope denoted by the invocant begins.
141 Returns the name of the subroutine called for this context, or "undef"
142 if this is not a subroutine context.
147 Returns a boolean indicating whether a new instance of @_ was set up for
148 this context, or "undef" if this is not a subroutine context.
153 Returns the context (in the sense of "perlfunc/wantarray" : "undef" for
154 void context, '' for scalar context, and true for list context) in which
155 the scope denoted by the invocant is executed.
160 Returns the contents of the string being compiled for this context, or
161 "undef" if this is not an eval context.
166 Returns a boolean indicating whether this eval context was created by
167 "require", or "undef" if this is not an eval context.
172 Returns the value of the lexical hints bit mask (available as $^H at
173 compile time) in use when the scope denoted by the invocant begins.
178 Returns the bit string representing the warnings (available as
179 "${^WARNING_BITS}" at compile time) in use when the scope denoted by the
185 Returns a reference to the lexical hints hash (available as "%^H" at
186 compile time) in use when the scope denoted by the invocant begins. This
187 method is available only on perl 5.10 and greater.
190 my $want = $cxt->want;
192 Returns the Perl context (in the sense of "perlfunc/wantarray") in which
193 is executed the closest subroutine, eval or format enclosing the scope
194 pointed by the invocant.
197 my $up_cxt = $cxt->up;
198 my $up_cxt = $cxt->up($frames);
199 my $up_cxt = Scope::Context->up;
201 Returns a new Scope::Context object pointing to the $frames-th upper
202 scope above the scope pointed by the invocant.
204 This method can also be invoked as a class method, in which case it is
205 equivalent to calling "up" on a Scope::Context object representing the
208 If omitted, $frames defaults to 1.
213 my $up = Scope::Context->new->up(2); # == Scope::Context->up(2)
214 # $up points two contextes above this one, which is the sub.
220 my $sub_cxt = $cxt->sub;
221 my $sub_cxt = $cxt->sub($frames);
222 my $sub_cxt = Scope::Context->sub;
224 Returns a new Scope::Context object pointing to the "$frames + 1"-th
225 subroutine scope above the scope pointed by the invocant.
227 This method can also be invoked as a class method, in which case it is
228 equivalent to calling "sub" on a Scope::Context object for the current
231 If omitted, $frames defaults to 0, which results in the closest sub
232 enclosing the scope pointed by the invocant.
241 my $sub = Scope::Context->new->sub(1); # == Scope::Context->sub(1)
242 # $sub points to the context for the outer() sub.
246 my $eval_cxt = $cxt->eval;
247 my $eval_cxt = $cxt->eval($frames);
248 my $eval_cxt = Scope::Context->eval;
250 Returns a new Scope::Context object pointing to the "$frames + 1"-th
251 "eval" scope above the scope pointed by the invocant.
253 This method can also be invoked as a class method, in which case it is
254 equivalent to calling "eval" on a Scope::Context object for the current
257 If omitted, $frames defaults to 0, which results in the closest eval
258 enclosing the scope pointed by the invocant.
262 my $eval = Scope::Context->new->eval; # == Scope::Context->eval
263 # $eval points to the eval context.
270 Executes $code when the scope pointed by the invocant ends.
272 See "reap" in Scope::Upper for details.
275 $cxt->localize($what, $value);
277 Localizes the variable described by $what to the value $value when the
278 control flow returns to the scope pointed by the invocant, until said
281 See "localize" in Scope::Upper for details.
284 $cxt->localize_elem($what, $key, $value);
286 Localizes the element $key of the variable $what to the value $value
287 when the control flow returns to the scope pointed by the invocant,
288 until said scope ends.
290 See "localize_elem" in Scope::Upper for details.
293 $cxt->localize_delete($what, $key);
295 Deletes the element $key from the variable $what when the control flow
296 returns to the scope pointed by the invocant, and restores it to its
297 original value when said scope ends.
299 See "localize_delete" in Scope::Upper for details.
302 $cxt->unwind(@values);
304 Immediately returns the scalars listed in @values from the closest
305 subroutine enclosing the scope pointed by the invocant.
307 See "unwind" in Scope::Upper for details.
310 $cxt->yield(@values);
312 Immediately returns the scalars listed in @values from the scope pointed
313 by the invocant, whatever it may be (except a substitution eval
316 See "yield" in Scope::Upper for details.
319 my @ret = $cxt->uplevel($code, @args);
321 Executes the code reference $code with arguments @args in the same
322 setting as the closest subroutine enclosing the scope pointed by the
323 invocant, then returns to the current scope the values returned by
326 See "uplevel" in Scope::Upper for details.
329 Carp (core module since perl 5), overload (since 5.2.0), Scalar::Util
337 Continuation::Escape.
340 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
342 You can contact me by mail or on "irc.perl.org" (vincent).
345 Please report any bugs or feature requests to "bug-scope-context at
346 rt.cpan.org", or through the web interface at
347 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Context>. I will
348 be notified, and then you'll automatically be notified of progress on
349 your bug as I make changes.
352 You can find documentation for this module with the perldoc command.
354 perldoc Scope::Context
357 Copyright 2011,2012,2013,2015 Vincent Pit, all rights reserved.
359 This program is free software; you can redistribute it and/or modify it
360 under the same terms as Perl itself.