README

   1 NAME
   2     Scope::Context - Object-oriented interface for inspecting or acting upon
   3     upper scope frames.
   4
   5 VERSION
   6     Version 0.03
   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, $eval, $sub, $loop);
  16            {
  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)
  21            }
  22
  23            eval {
  24             # This throws an exception, since $block has expired :
  25             $block->localize('$x' => 1);
  26            };
  27
  28            # This will print "hello" when the current eval block ends :
  29            $eval->reap(sub { print "hello\n" });
  30
  31            # Ignore warnings just for the loop body :
  32            $loop->localize_elem('%SIG', __WARN__ => sub { });
  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            # @values now contains (1, 2).
  39
  40            # Immediately return (1, 2, 3) from the sub, bypassing the eval :
  41            $sub->unwind(@values, 3);
  42
  43            # Not reached.
  44           }
  45
  46           # Not reached.
  47          }->();
  48
  49          # unwind() returns here. "hello\n" was printed, and now warnings are
  50          # ignored.
  51         }
  52
  53         # $SIG{__WARN__} has been restored to its original value, warnings are no
  54         # longer ignored.
  55
  56 DESCRIPTION
  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.
  64
  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
  70     means that :
  71
  72         my $cxt;
  73         {
  74          $cxt = Scope::Context->new;
  75         }
  76         $cxt->reap(sub { print "hello\n });
  77
  78     will croak when "reap" is called.
  79
  80 METHODS
  81   "new"
  82         my $cxt = Scope::Context->new;
  83         my $cxt = Scope::Context->new($scope_upper_cxt);
  84
  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.
  88
  89   "here"
  90     A synonym for "new".
  91
  92   "cxt"
  93         my $scope_upper_cxt = $cxt->cxt;
  94
  95     Read-only accessor to the Scope::Upper context identifier associated
  96     with the invocant.
  97
  98   "uid"
  99         my $uid = $cxt->uid;
 100
 101     Read-only accessor to the Scope::Upper unique identifier representing
 102     the Scope::Upper context associated with the invocant.
 103
 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
 106     same UID.
 107
 108   "is_valid"
 109         my $is_valid = $cxt->is_valid;
 110
 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
 113     scope).
 114
 115   "assert_valid"
 116         $cxt->assert_valid;
 117
 118     Throws an exception if the invocant has expired and is no longer valid.
 119     Returns true otherwise.
 120
 121   "package"
 122         $cxt->package;
 123
 124     Returns the namespace in use when the scope denoted by the invocant
 125     begins.
 126
 127   "file"
 128         $cxt->file;
 129
 130     Returns the name of the file where the scope denoted by the invocant
 131     belongs to.
 132
 133   "line"
 134         $cxt->line;
 135
 136     Returns the line number where the scope denoted by the invocant begins.
 137
 138   "sub_name"
 139         $cxt->sub_name;
 140
 141     Returns the name of the subroutine called for this context, or "undef"
 142     if this is not a subroutine context.
 143
 144   "sub_has_args"
 145         $cxt->sub_has_args;
 146
 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.
 149
 150   "gimme"
 151         $cxt->gimme;
 152
 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.
 156
 157   "eval_text"
 158         $cxt->eval_text;
 159
 160     Returns the contents of the string being compiled for this context, or
 161     "undef" if this is not an eval context.
 162
 163   "is_require"
 164         $cxt->is_require;
 165
 166     Returns a boolean indicating whether this eval context was created by
 167     "require", or "undef" if this is not an eval context.
 168
 169   "hints_bits"
 170         $cxt->hints_bits;
 171
 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.
 174
 175   "warnings_bits"
 176         $cxt->warnings_bits;
 177
 178     Returns the bit string representing the warnings (available as
 179     "${^WARNING_BITS}" at compile time) in use when the scope denoted by the
 180     invocant begins.
 181
 182   "hints_hash"
 183         $cxt->hints_hash;
 184
 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.
 188
 189   "want"
 190         my $want = $cxt->want;
 191
 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.
 195
 196   "up"
 197         my $up_cxt = $cxt->up;
 198         my $up_cxt = $cxt->up($frames);
 199         my $up_cxt = Scope::Context->up;
 200
 201     Returns a new Scope::Context object pointing to the $frames-th upper
 202     scope above the scope pointed by the invocant.
 203
 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
 206     current context.
 207
 208     If omitted, $frames defaults to 1.
 209
 210         sub {
 211          {
 212           {
 213            my $up = Scope::Context->new->up(2); # == Scope::Context->up(2)
 214            # $up points two contextes above this one, which is the sub.
 215           }
 216          }
 217         }
 218
 219   "sub"
 220         my $sub_cxt = $cxt->sub;
 221         my $sub_cxt = $cxt->sub($frames);
 222         my $sub_cxt = Scope::Context->sub;
 223
 224     Returns a new Scope::Context object pointing to the "$frames + 1"-th
 225     subroutine scope above the scope pointed by the invocant.
 226
 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
 229     context.
 230
 231     If omitted, $frames defaults to 0, which results in the closest sub
 232     enclosing the scope pointed by the invocant.
 233
 234         outer();
 235
 236         sub outer {
 237          inner();
 238         }
 239
 240         sub inner {
 241          my $sub = Scope::Context->new->sub(1); # == Scope::Context->sub(1)
 242          # $sub points to the context for the outer() sub.
 243         }
 244
 245   "eval"
 246         my $eval_cxt = $cxt->eval;
 247         my $eval_cxt = $cxt->eval($frames);
 248         my $eval_cxt = Scope::Context->eval;
 249
 250     Returns a new Scope::Context object pointing to the "$frames + 1"-th
 251     "eval" scope above the scope pointed by the invocant.
 252
 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
 255     context.
 256
 257     If omitted, $frames defaults to 0, which results in the closest eval
 258     enclosing the scope pointed by the invocant.
 259
 260         eval {
 261          sub {
 262           my $eval = Scope::Context->new->eval; # == Scope::Context->eval
 263           # $eval points to the eval context.
 264          }->()
 265         }
 266
 267   "reap"
 268         $cxt->reap($code);
 269
 270     Executes $code when the scope pointed by the invocant ends.
 271
 272     See "reap" in Scope::Upper for details.
 273
 274   "localize"
 275         $cxt->localize($what, $value);
 276
 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
 279     scope ends.
 280
 281     See "localize" in Scope::Upper for details.
 282
 283   "localize_elem"
 284         $cxt->localize_elem($what, $key, $value);
 285
 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.
 289
 290     See "localize_elem" in Scope::Upper for details.
 291
 292   "localize_delete"
 293         $cxt->localize_delete($what, $key);
 294
 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.
 298
 299     See "localize_delete" in Scope::Upper for details.
 300
 301   "unwind"
 302         $cxt->unwind(@values);
 303
 304     Immediately returns the scalars listed in @values from the closest
 305     subroutine enclosing the scope pointed by the invocant.
 306
 307     See "unwind" in Scope::Upper for details.
 308
 309   "yield"
 310         $cxt->yield(@values);
 311
 312     Immediately returns the scalars listed in @values from the scope pointed
 313     by the invocant, whatever it may be (except a substitution eval
 314     context).
 315
 316     See "yield" in Scope::Upper for details.
 317
 318   "uplevel"
 319         my @ret = $cxt->uplevel($code, @args);
 320
 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
 324     $code.
 325
 326     See "uplevel" in Scope::Upper for details.
 327
 328 DEPENDENCIES
 329     Carp (core module since perl 5), overload (since 5.2.0), Scalar::Util
 330     (since 5.7.3).
 331
 332     Scope::Upper 0.21.
 333
 334 SEE ALSO
 335     Scope::Upper.
 336
 337     Continuation::Escape.
 338
 339 AUTHOR
 340     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 341
 342     You can contact me by mail or on "irc.perl.org" (vincent).
 343
 344 BUGS
 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.
 350
 351 SUPPORT
 352     You can find documentation for this module with the perldoc command.
 353
 354         perldoc Scope::Context
 355
 356 COPYRIGHT & LICENSE
 357     Copyright 2011,2012,2013,2015 Vincent Pit, all rights reserved.
 358
 359     This program is free software; you can redistribute it and/or modify it
 360     under the same terms as Perl itself.
 361