README

   1 NAME
   2     Scope::Context - Object-oriented interface for inspecting or acting upon
   3     upper scope frames.
   4
   5 VERSION
   6     Version 0.02
   7
   8 SYNOPSIS
   9         use Scope::Context;
  10
  11         for (1 .. 5) {
  12          sub {
  13           eval {
  14            # Create Scope::Context objects for different upper frames.
  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 body.
  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            # Not reached.
  43           }
  44
  45           # Not reached.
  46          }->();
  47
  48          # unwind() returns here. "hello\n" was printed, and now
  49          # $SIG{__DIE__} is undefined.
  50         }
  51
  52 DESCRIPTION
  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.
  60
  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
  66     means that :
  67
  68         my $cxt;
  69         {
  70          $cxt = Scope::Context->new;
  71         }
  72         $cxt->reap(sub { print "hello\n });
  73
  74     will croak when "reap" is called.
  75
  76 METHODS
  77   "new"
  78         my $cxt = Scope::Context->new;
  79         my $cxt = Scope::Context->new($scope_upper_cxt);
  80
  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.
  84
  85   "here"
  86     A synonym for "new".
  87
  88   "cxt"
  89         my $scope_upper_cxt = $cxt->cxt;
  90
  91     Read-only accessor to the Scope::Upper context identifier associated
  92     with the invocant.
  93
  94   "uid"
  95         my $uid = $cxt->uid;
  96
  97     Read-only accessor to the Scope::Upper unique identifier representing
  98     the Scope::Upper context associated with the invocant.
  99
 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
 102     same UID.
 103
 104   "is_valid"
 105         my $is_valid = $cxt->is_valid;
 106
 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
 109     scope).
 110
 111   "assert_valid"
 112         $cxt->assert_valid;
 113
 114     Throws an exception if the invocant has expired and is no longer valid.
 115     Returns true otherwise.
 116
 117   "package"
 118         $cxt->package;
 119
 120     Returns the namespace in use when the scope denoted by the invocant
 121     begins.
 122
 123   "file"
 124         $cxt->file;
 125
 126     Returns the name of the file where the scope denoted by the invocant
 127     belongs to.
 128
 129   "line"
 130         $cxt->line;
 131
 132     Returns the line number where the scope denoted by the invocant begins.
 133
 134   "sub_name"
 135         $cxt->sub_name;
 136
 137     Returns the name of the subroutine called for this context, or "undef"
 138     if this is not a subroutine context.
 139
 140   "sub_has_args"
 141         $cxt->sub_has_args;
 142
 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.
 145
 146   "gimme"
 147         $cxt->gimme;
 148
 149     Returns the context (in the sense of "wantarray" in perlfunc) in which
 150     the scope denoted by the invocant is executed.
 151
 152   "eval_text"
 153         $cxt->eval_text;
 154
 155     Returns the contents of the string being compiled for this context, or
 156     "undef" if this is not an eval context.
 157
 158   "is_require"
 159         $cxt->is_require;
 160
 161     Returns a boolean indicating whether this eval context was created by
 162     "require", or "undef" if this is not an eval context.
 163
 164   "hints_bits"
 165         $cxt->hints_bits;
 166
 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.
 169
 170   "warnings_bits"
 171         $cxt->warnings_bits;
 172
 173     Returns the bit string representing the warnings (available as
 174     "${^WARNING_BITS}" at compile time) in use when the scope denoted by the
 175     invocant begins.
 176
 177   "hints_hash"
 178         $cxt->hints_hash;
 179
 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.
 183
 184   "want"
 185         my $want = $cxt->want;
 186
 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.
 190
 191   "up"
 192         my $up_cxt = $cxt->up;
 193         my $up_cxt = $cxt->up($frames);
 194         my $up_cxt = Scope::Context->up;
 195
 196     Returns a new Scope::Context object pointing to the $frames-th upper
 197     scope above the scope pointed by the invocant.
 198
 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
 201     current context.
 202
 203     If omitted, $frames defaults to 1.
 204
 205         sub {
 206          {
 207           {
 208            my $up = Scope::Context->new->up(2); # = Scope::Context->up(2)
 209            # $up points two contextes above this one, which is the sub.
 210           }
 211          }
 212         }
 213
 214   "sub"
 215         my $sub_cxt = $cxt->sub;
 216         my $sub_cxt = $cxt->sub($frames);
 217         my $sub_cxt = Scope::Context->sub;
 218
 219     Returns a new Scope::Context object pointing to the $frames-th
 220     subroutine scope above the scope pointed by the invocant.
 221
 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
 224     context.
 225
 226     If omitted, $frames defaults to 0, which results in the closest sub
 227     enclosing the scope pointed by the invocant.
 228
 229         outer();
 230
 231         sub outer {
 232          inner();
 233         }
 234
 235         sub inner {
 236          my $sub = Scope::Context->new->sub(1); # = Scope::Context->sub(1)
 237          # $sub points to the context for the outer() sub.
 238         }
 239
 240   "eval"
 241         my $eval_cxt = $cxt->eval;
 242         my $eval_cxt = $cxt->eval($frames);
 243         my $eval_cxt = Scope::Context->eval;
 244
 245     Returns a new Scope::Context object pointing to the $frames-th "eval"
 246     scope above the scope pointed by the invocant.
 247
 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
 250     context.
 251
 252     If omitted, $frames defaults to 0, which results in the closest eval
 253     enclosing the scope pointed by the invocant.
 254
 255         eval {
 256          sub {
 257           my $eval = Scope::Context->new->eval; # = Scope::Context->eval
 258           # $eval points to the eval context.
 259          }->()
 260         }
 261
 262   "reap"
 263         $cxt->reap($code);
 264
 265     Execute $code when the scope pointed by the invocant ends.
 266
 267     See "reap" in Scope::Upper for details.
 268
 269   "localize"
 270         $cxt->localize($what, $value);
 271
 272     Localize the variable described by $what to the value $value when the
 273     control flow returns to the scope pointed by the invocant.
 274
 275     See "localize" in Scope::Upper for details.
 276
 277   "localize_elem"
 278         $cxt->localize_elem($what, $key, $value);
 279
 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.
 282
 283     See "localize_elem" in Scope::Upper for details.
 284
 285   "localize_delete"
 286         $cxt->localize_delete($what, $key);
 287
 288     Delete the element $key from the variable $what when the control flow
 289     returns to the scope pointed by the invocant.
 290
 291     See "localize_delete" in Scope::Upper for details.
 292
 293   "unwind"
 294         $cxt->unwind(@values);
 295
 296     Immediately returns the scalars listed in @values from the closest
 297     subroutine enclosing the scope pointed by the invocant.
 298
 299     See "unwind" in Scope::Upper for details.
 300
 301   "yield"
 302         $cxt->yield(@values);
 303
 304     Immediately returns the scalars listed in @values from the scope pointed
 305     by the invocant, whatever it may be (except a substitution eval
 306     context).
 307
 308     See "yield" in Scope::Upper for details.
 309
 310   "uplevel"
 311         my @ret = $cxt->uplevel($code, @args);
 312
 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
 316     $code.
 317
 318     See "uplevel" in Scope::Upper for details.
 319
 320 DEPENDENCIES
 321     Carp (core module since perl 5), Scalar::Util (since 5.7.3).
 322
 323     Scope::Upper 0.21.
 324
 325 SEE ALSO
 326     Scope::Upper.
 327
 328     Continuation::Escape.
 329
 330 AUTHOR
 331     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 332
 333     You can contact me by mail or on "irc.perl.org" (vincent).
 334
 335 BUGS
 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.
 341
 342 SUPPORT
 343     You can find documentation for this module with the perldoc command.
 344
 345         perldoc Scope::Context
 346
 347 COPYRIGHT & LICENSE
 348     Copyright 2011,2012,2013 Vincent Pit, all rights reserved.
 349
 350     This program is free software; you can redistribute it and/or modify it
 351     under the same terms as Perl itself.
 352