2 Scope::Context - Object-oriented interface for inspecting or acting upon
14 # create Scope::Context objects
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.
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);
46 This class provides an object-oriented interface to Scope::Upper's
47 functionalities. A Scope::Context object represents a currently active
48 dynamic scope (or context), and encapsulates the corresponding
49 Scope::Upper-compatible context identifier. All of Scope::Upper's
50 functions are then made available as methods. This gives you a prettier
51 and safer interface when you are not reaching for extreme performance,
52 but rest assured that the overhead of this module is minimal anyway.
54 The Scope::Context methods actually do more than their subroutine
55 counterparts from Scope::Upper : before each call, the target context
56 will be checked to ensure it is still active (which means that it is
57 still present in the current call stack), and an exception will be
58 thrown if you attempt to act on a context that has already expired. This
63 $sc = Scope::Context->new;
65 $sc->reap(sub { print "hello\n });
67 will croak when "reap" is called.
71 Creates a new immutable Scope::Context object from the
72 Scope::Upper-comptabile context $context. If omitted, $context defaults
73 to the current context.
79 Read-only accessor to the Scope::Upper context corresponding to the
80 topic Scope::Context object.
83 Read-only accessor to the Scope::Upper UID of the topic Scope::Context
86 This class also overloads the "==" operator, which will return true if
87 and only if its two operands are Scope::Context objects that have the
91 Returns true if and only if the topic context is still valid (that is,
92 it designates a scope that is higher than the topic context in the call
96 Throws an exception if the topic context has expired and is no longer
97 valid. Returns true otherwise.
100 Returns the Perl context (in the sense of "wantarray" : "undef" for void
101 context, '' for scalar context, and true for list context) in which is
102 executed the scope corresponding to the topic Scope::Context object.
105 Returns a new Scope::Context object pointing to the $frames-th upper
106 scope above the topic context.
108 This method can also be invoked as a class method, in which case it is
109 equivalent to calling "up" on a Scope::Context object for the current
112 If omitted, $frames defaults to 1.
117 my $up = Scope::Context->new->up(2); # = Scope::Context->up(2)
118 # $up points two contextes above this one, which is the sub.
124 Returns a new Scope::Context object pointing to the $frames-th
125 subroutine scope above the topic context.
127 This method can also be invoked as a class method, in which case it is
128 equivalent to calling "sub" on a Scope::Context object for the current
131 If omitted, $frames defaults to 0, which results in the closest sub
132 enclosing the topic context.
141 my $sub = Scope::Context->new->sub(1); # = Scope::Context->sub
142 # $sub points to the context for the outer() sub.
146 Returns a new Scope::Context object pointing to the $frames-th "eval"
147 scope above the topic context.
149 This method can also be invoked as a class method, in which case it is
150 equivalent to calling "eval" on a Scope::Context object for the current
153 If omitted, $frames defaults to 0, which results in the closest eval
154 enclosing the topic context.
158 my $eval = Scope::Context->new->eval; # = Scope::Context->eval
159 # $eval points to the eval context.
164 Execute $code when the topic context ends.
166 See "reap" in Scope::Upper for details.
168 "localize $what, $value"
169 Localize the variable described by $what to the value $value when the
170 control flow returns to the scope pointed by the topic context.
172 See "localize" in Scope::Upper for details.
174 "localize_elem $what, $key, $value"
175 Localize the element $key of the variable $what to the value $value when
176 the control flow returns to the scope pointed by the topic context.
178 See "localize_elem" in Scope::Upper for details.
180 "localize_delete $what, $key"
181 Delete the element $key from the variable $what when the control flow
182 returns to the scope pointed by the topic context.
184 See "localize_delete" in Scope::Upper for details.
187 Immediately returns the scalars listed in @values from the closest
188 subroutine enclosing the topic context.
190 See "unwind" in Scope::Upper for details.
192 "uplevel $code, @args"
193 Executes the code reference $code with arguments @args in the same
194 setting as the closest subroutine enclosing the topic context, then
195 returns to the current scope the values returned by $code.
197 See "uplevel" in Scope::Upper for details.
200 Carp (core module since perl 5), Scalar::Util (since 5.7.3).
207 Continuation::Escape.
210 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
212 You can contact me by mail or on "irc.perl.org" (vincent).
215 Please report any bugs or feature requests to "bug-scope-context at
216 rt.cpan.org", or through the web interface at
217 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Context>. I will
218 be notified, and then you'll automatically be notified of progress on
219 your bug as I make changes.
222 You can find documentation for this module with the perldoc command.
224 perldoc Scope::Context
227 Copyright 2011 Vincent Pit, all rights reserved.
229 This program is free software; you can redistribute it and/or modify it
230 under the same terms as Perl itself.