README

   1 NAME
   2     Scope::Context - Object-oriented interface for inspecting or acting upon
   3     upper scope frames.
   4
   5 VERSION
   6     Version 0.01
   7
   8 SYNOPSIS
   9         use Scope::Context;
  10
  11         for (1 .. 5) {
  12          sub {
  13           eval {
  14            # create Scope::Context objects
  15            my ($block, $sub, $eval, $loop);
  16            {
  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)
  21            }
  22
  23            eval {
  24             # This will throw an exception, since $block has expired.
  25             $block->localize('$x' => 1);
  26            };
  27
  28            # This prints "hello" when the eval block above ends.
  29            $eval->reap(sub { print "hello\n" });
  30
  31            # Ignore $SIG{__DIE__} just for the loop.
  32            $loop->localize_delete('%SIG', '__DIE__');
  33
  34            # Execute the callback as if it ran in place of the sub.
  35            my @values = $sub->uplevel(sub {
  36             return @_, 2;
  37            }, 1);
  38
  39            # Immediately return (1, 2, 3) from the sub, bypassing the eval.
  40            $sub->unwind(@values, 3);
  41           }
  42          }->();
  43         }
  44
  45 DESCRIPTION
  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.
  53
  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
  59     means that :
  60
  61         my $sc;
  62         {
  63          $sc = Scope::Context->new;
  64         }
  65         $sc->reap(sub { print "hello\n });
  66
  67     will croak when "reap" is called.
  68
  69 METHODS
  70   "new [ $context ]"
  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.
  74
  75   "here"
  76     A synonym for "new".
  77
  78   "cxt"
  79     Read-only accessor to the Scope::Upper context corresponding to the
  80     topic Scope::Context object.
  81
  82   "uid"
  83     Read-only accessor to the Scope::Upper UID of the topic Scope::Context
  84     object.
  85
  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
  88     same UID.
  89
  90   "is_valid"
  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
  93     stack).
  94
  95   "assert_valid"
  96     Throws an exception if the topic context has expired and is no longer
  97     valid. Returns true otherwise.
  98
  99   "want"
 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.
 103
 104   "up [ $frames ]"
 105     Returns a new Scope::Context object pointing to the $frames-th upper
 106     scope above the topic context.
 107
 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
 110     context.
 111
 112     If omitted, $frames defaults to 1.
 113
 114         sub {
 115          {
 116           {
 117            my $up = Scope::Context->new->up(2); # = Scope::Context->up(2)
 118            # $up points two contextes above this one, which is the sub.
 119           }
 120          }
 121         }
 122
 123   "sub [ $frames ]"
 124     Returns a new Scope::Context object pointing to the $frames-th
 125     subroutine scope above the topic context.
 126
 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
 129     context.
 130
 131     If omitted, $frames defaults to 0, which results in the closest sub
 132     enclosing the topic context.
 133
 134         outer();
 135
 136         sub outer {
 137          inner();
 138         }
 139
 140         sub inner {
 141          my $sub = Scope::Context->new->sub(1); # = Scope::Context->sub
 142          # $sub points to the context for the outer() sub.
 143         }
 144
 145   "eval [ $frames ]"
 146     Returns a new Scope::Context object pointing to the $frames-th "eval"
 147     scope above the topic context.
 148
 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
 151     context.
 152
 153     If omitted, $frames defaults to 0, which results in the closest eval
 154     enclosing the topic context.
 155
 156         eval {
 157          sub {
 158           my $eval = Scope::Context->new->eval; # = Scope::Context->eval
 159           # $eval points to the eval context.
 160          }->()
 161         }
 162
 163   "reap $code"
 164     Execute $code when the topic context ends.
 165
 166     See "reap" in Scope::Upper for details.
 167
 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.
 171
 172     See "localize" in Scope::Upper for details.
 173
 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.
 177
 178     See "localize_elem" in Scope::Upper for details.
 179
 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.
 183
 184     See "localize_delete" in Scope::Upper for details.
 185
 186   "unwind @values"
 187     Immediately returns the scalars listed in @values from the closest
 188     subroutine enclosing the topic context.
 189
 190     See "unwind" in Scope::Upper for details.
 191
 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.
 196
 197     See "uplevel" in Scope::Upper for details.
 198
 199 DEPENDENCIES
 200     Carp (core module since perl 5), Scalar::Util (since 5.7.3).
 201
 202     Scope::Upper 0.18.
 203
 204 SEE ALSO
 205     Scope::Upper.
 206
 207     Continuation::Escape.
 208
 209 AUTHOR
 210     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 211
 212     You can contact me by mail or on "irc.perl.org" (vincent).
 213
 214 BUGS
 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.
 220
 221 SUPPORT
 222     You can find documentation for this module with the perldoc command.
 223
 224         perldoc Scope::Context
 225
 226 COPYRIGHT & LICENSE
 227     Copyright 2011 Vincent Pit, all rights reserved.
 228
 229     This program is free software; you can redistribute it and/or modify it
 230     under the same terms as Perl itself.
 231