README

   1 NAME
   2     Scope::Upper - Act on upper scopes.
   3
   4 VERSION
   5     Version 0.06
   6
   7 SYNOPSIS
   8         package X;
   9
  10         use Scope::Upper qw/reap localize localize_elem localize_delete :words/;
  11
  12         sub desc { shift->{desc} }
  13
  14         sub set_tag {
  15          my ($desc) = @_;
  16
  17          # First localize $x so that it gets destroyed last
  18          localize '$x' => bless({ desc => $desc }, __PACKAGE__) => UP; # one scope up
  19
  20          reap sub {
  21           my $pkg = caller;
  22           my $x = do { no strict 'refs'; ${$pkg.'::x'} }; # Get the $x in the scope
  23           print $x->desc . ": done\n";
  24          } => SCOPE 1; # same as UP here
  25
  26          localize_elem '%SIG', '__WARN__' => sub {
  27           my $pkg = caller;
  28           my $x = do { no strict 'refs'; ${$pkg.'::x'} }; # Get the $x in the scope
  29           CORE::warn($x->desc . ': ' . join('', @_));
  30          } => UP CALLER 0; # same as UP here
  31
  32          # delete last @ARGV element
  33          localize_delete '@ARGV', -1 => UP SUB HERE; # same as UP here
  34         }
  35
  36         package Y;
  37
  38         {
  39          X::set_tag('pie');
  40          # $x is now a X object, and @ARGV has one element less
  41          warn 'what'; # warns "pie: what at ..."
  42          ...
  43         } # "pie: done" is printed
  44
  45         package Z;
  46
  47         use Scope::Upper qw/unwind want_at :words/;
  48
  49         sub try (&) {
  50          my @result = shift->();
  51          my $cx = SUB UP SUB;
  52          unwind +(want_at($cx) ? @result : scalar @result) => $cx;
  53         }
  54
  55         ...
  56
  57         sub zap {
  58          try {
  59           return @things; # returns to try() and then outside zap()
  60          }
  61         }
  62
  63         my @what = zap(); # @what contains @things
  64
  65 DESCRIPTION
  66     This module lets you defer actions that will take place when the control
  67     flow returns into an upper scope. Currently, you can hook an upper scope
  68     end, or localize variables, array/hash values or deletions of elements
  69     in higher contexts. You can also return to an upper level and know which
  70     context was in use then.
  71
  72 FUNCTIONS
  73     In all those functions, $context refers to the target scope.
  74
  75     You have to use one or a combination of "WORDS" to build the $context to
  76     pass to these functions. This is needed in order to ensure that the
  77     module still works when your program is ran in the debugger. Don't try
  78     to use a raw value or things will get messy.
  79
  80     The only thing you can assume is that it is an *absolute* indicator of
  81     the frame. This means that you can safely store it at some point and use
  82     it when needed, and it will still denote the original scope.
  83
  84   "reap $callback, $context"
  85     Add a destructor that calls $callback when the upper scope represented
  86     by $context ends.
  87
  88   "localize $what, $value, $context"
  89     A "local" delayed to the time of first return into the upper scope
  90     denoted by $context. $what can be :
  91
  92     *   A glob, in which case $value can either be a glob or a reference.
  93         "localize" follows then the same syntax as "local *x = $value". For
  94         example, if $value is a scalar reference, then the "SCALAR" slot of
  95         the glob will be set to $$value - just like "local *x = \1" sets $x
  96         to 1.
  97
  98     *   A string beginning with a sigil, representing the symbol to localize
  99         and to assign to. If the sigil is '$', "localize" follows the same
 100         syntax as "local $x = $value", i.e. $value isn't dereferenced. For
 101         example,
 102
 103             localize '$x', \'foo' => HERE;
 104
 105         will set $x to a reference to the string 'foo'. Other sigils ('@',
 106         '%', '&' and '*') require $value to be a reference of the
 107         corresponding type.
 108
 109         When the symbol is given by a string, it is resolved when the actual
 110         localization takes place and not when "localize" is called. This
 111         means that
 112
 113             sub tag { localize '$x', $_[0] => UP }
 114
 115         will localize in the caller's namespace.
 116
 117   "localize_elem $what, $key, $value, $context"
 118     Similar to "localize" but for array and hash elements. If $what is a
 119     glob, the slot to fill is determined from which type of reference $value
 120     is ; otherwise it's inferred from the sigil. $key is either an array
 121     index or a hash key, depending of which kind of variable you localize.
 122
 123   "localize_delete $what, $key, $context"
 124     Similiar to "localize", but for deleting variables or array/hash
 125     elements. $what can be:
 126
 127     *   A glob, in which case $key is ignored and the call is equivalent to
 128         "local *x".
 129
 130     *   A string beginning with '@' or '%', for which the call is equivalent
 131         to respectiveley "local $a[$key]; delete $a[$key]" and "local
 132         $h{$key}; delete $h{$key}".
 133
 134     *   A string beginning with '&', which more or less does "undef &func"
 135         in the upper scope. It's actually more powerful, as &func won't even
 136         "exists" anymore. $key is ignored.
 137
 138   "unwind @values, $context"
 139     Returns @values *from* the context pointed by $context, i.e. from the
 140     subroutine, eval or format just above $context.
 141
 142     The upper context isn't coerced onto @values, which is hence always
 143     evaluated in list context. This means that
 144
 145         my $num = sub {
 146          my @a = ('a' .. 'z');
 147          unwind @a => HERE;
 148         }->();
 149
 150     will set $num to 'z'. You can use "want_at" to handle these cases.
 151
 152   "want_at $context"
 153     Like "wantarray", but for the subroutine/eval/format just above
 154     $context.
 155
 156     The previous example can then be "corrected" :
 157
 158         my $num = sub {
 159          my @a = ('a' .. 'z');
 160          unwind +(want_at(HERE) ? @a : scalar @a) => HERE;
 161         }->();
 162
 163     will righteously set $num to 26.
 164
 165 WORDS
 166   Constants
 167    "TOP"
 168     Returns the context that currently represents the highest scope.
 169
 170    "HERE"
 171     The context of the current scope.
 172
 173   Getting a context from a context
 174     For any of those functions, $from is expected to be a context. When
 175     omitted, it defaults to the the current context.
 176
 177    "UP $from"
 178     The context of the scope just above $from.
 179
 180    "SUB $from"
 181     The context of the closest subroutine above $from.
 182
 183    "EVAL $from"
 184     The context of the closest eval above $from.
 185
 186   Getting a context from a level
 187     Here, $level should denote a number of scopes above the current one.
 188     When omitted, it defaults to 0 and those functions return the same
 189     context as "HERE".
 190
 191    "SCOPE $level"
 192     The $level-th upper context, regardless of its type.
 193
 194    "CALLER $level"
 195     The context of the $level-th upper subroutine/eval/format. It kind of
 196     corresponds to the context represented by "caller $level", but while
 197     e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
 198     the top scope in the current context.
 199
 200 EXPORT
 201     The functions "reap", "localize", "localize_elem", "localize_delete",
 202     "unwind" and "want_at" are only exported on request, either individually
 203     or by the tags ':funcs' and ':all'.
 204
 205     Same goes for the words "TOP", "HERE", "UP", "SUB", "EVAL", "SCOPE" and
 206     "CALLER" that are only exported on request, individually or by the tags
 207     ':words' and ':all'.
 208
 209 CAVEATS
 210     Be careful that local variables are restored in the reverse order in
 211     which they were localized. Consider those examples:
 212
 213         local $x = 0;
 214         {
 215          reap sub { print $x } => HERE;
 216          local $x = 1;
 217          ...
 218         }
 219         # prints '0'
 220         ...
 221         {
 222          local $x = 1;
 223          reap sub { $x = 2 } => HERE;
 224          ...
 225         }
 226         # $x is 0
 227
 228     The first case is "solved" by moving the "local" before the "reap", and
 229     the second by using "localize" instead of "reap".
 230
 231     "reap", "localize" and "localize_elem" effects can't cross "BEGIN"
 232     blocks, hence calling those functions in "import" is deemed to be
 233     useless. This is an hopeless case because "BEGIN" blocks are executed
 234     once while localizing constructs should do their job at each run.
 235
 236     Some rare oddities may still happen when running inside the debugger. It
 237     may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some
 238     context fixes.
 239
 240 DEPENDENCIES
 241     XSLoader (standard since perl 5.006).
 242
 243 SEE ALSO
 244     Alias, Hook::Scope, Scope::Guard, Guard.
 245
 246 AUTHOR
 247     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 248
 249     You can contact me by mail or on "irc.perl.org" (vincent).
 250
 251 BUGS
 252     Please report any bugs or feature requests to "bug-scope-upper at
 253     rt.cpan.org", or through the web interface at
 254     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper>. I will be
 255     notified, and then you'll automatically be notified of progress on your
 256     bug as I make changes.
 257
 258 SUPPORT
 259     You can find documentation for this module with the perldoc command.
 260
 261         perldoc Scope::Upper
 262
 263     Tests code coverage report is available at
 264     <http://www.profvince.com/perl/cover/Scope-Upper>.
 265
 266 ACKNOWLEDGEMENTS
 267     Inspired by Ricardo Signes.
 268
 269     Thanks to Shawn M. Moore for motivation.
 270
 271 COPYRIGHT & LICENSE
 272     Copyright 2008-2009 Vincent Pit, all rights reserved.
 273
 274     This program is free software; you can redistribute it and/or modify it
 275     under the same terms as Perl itself.
 276