README

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