README

   1 NAME
   2     Scope::Upper - Act on upper scopes.
   3
   4 VERSION
   5     Version 0.04
   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.
  69
  70 FUNCTIONS
  71   "reap $callback, $level"
  72     Add a destructor that calls $callback when the $level-th upper scope
  73     ends, where 0 corresponds to the current scope.
  74
  75   "localize $what, $value, $level"
  76     A "local" delayed to the time of first return into the $level-th upper
  77     scope. $what can be :
  78
  79     *   A glob, in which case $value can either be a glob or a reference.
  80         "localize" follows then the same syntax as "local *x = $value". For
  81         example, if $value is a scalar reference, then the "SCALAR" slot of
  82         the glob will be set to $$value - just like "local *x = \1" sets $x
  83         to 1.
  84
  85     *   A string beginning with a sigil, representing the symbol to localize
  86         and to assign to. If the sigil is '$', "localize" follows the same
  87         syntax as "local $x = $value", i.e. $value isn't dereferenced. For
  88         example,
  89
  90             localize '$x', \'foo' => 0;
  91
  92         will set $x to a reference to the string 'foo'. Other sigils ('@',
  93         '%', '&' and '*') require $value to be a reference of the
  94         corresponding type.
  95
  96         When the symbol is given by a string, it is resolved when the actual
  97         localization takes place and not when "localize" is called. This
  98         means that
  99
 100             sub tag { localize '$x', $_[0] => 1; }
 101
 102         will localize in the caller's namespace.
 103
 104   "localize_elem $what, $key, $value, $level"
 105     Similar to "localize" but for array and hash elements. If $what is a
 106     glob, the slot to fill is determined from which type of reference $value
 107     is ; otherwise it's inferred from the sigil. $key is either an array
 108     index or a hash key, depending of which kind of variable you localize.
 109
 110   "localize_delete $what, $key, $level"
 111     Similiar to "localize", but for deleting variables or array/hash
 112     elements. $what can be:
 113
 114     *   A glob, in which case $key is ignored and the call is equivalent to
 115         "local *x".
 116
 117     *   A string beginning with '@' or '%', for which the call is equivalent
 118         to respectiveley "local $a[$key]; delete $a[$key]" and "local
 119         $h{$key}; delete $h{$key}".
 120
 121     *   A string beginning with '&', which more or less does "undef &func"
 122         in the upper scope. It's actually more powerful, as &func won't even
 123         "exists" anymore. $key is ignored.
 124
 125   "unwind @values, $level"
 126     Returns @values *from* the context indicated by $level, i.e. from the
 127     subroutine, eval or format just above $level. The upper level isn't
 128     coerced onto @values, which is hence always evaluated in list context.
 129
 130   "want_at $level"
 131     Like "wantarray", but for the subroutine/eval/format context just above
 132     $level.
 133
 134 WORDS
 135   "TOP"
 136     Returns the level that currently represents the highest scope.
 137
 138   "HERE"
 139     The current level - i.e. 0.
 140
 141   "UP $from"
 142     The level of the scope just above $from.
 143
 144   "DOWN $from"
 145     The level of the scope just below $from.
 146
 147   "SUB $from"
 148     The level of the closest subroutine context above $from.
 149
 150   "EVAL $from"
 151     The level of the closest eval context above $from.
 152
 153     If $from is omitted in any of those functions, the current level is used
 154     as the reference level.
 155
 156   "CALLER $stack"
 157     The level corresponding to the stack referenced by "caller $stack".
 158
 159 EXPORT
 160     The functions "reap", "localize", "localize_elem", "localize_delete",
 161     "unwind" and "want_at" are only exported on request, either individually
 162     or by the tags ':funcs' and ':all'.
 163
 164     Same goes for the words "TOP", "HERE", "UP", "DOWN", "SUB", "EVAL" and
 165     "CALLER" that are only exported on request, individually or by the tags
 166     ':words' and ':all'.
 167
 168 CAVEATS
 169     Be careful that local variables are restored in the reverse order in
 170     which they were localized. Consider those examples:
 171
 172         local $x = 0;
 173         {
 174          reap sub { print $x } => 0;
 175          local $x = 1;
 176          ...
 177         }
 178         # prints '0'
 179         ...
 180         {
 181          local $x = 1;
 182          reap sub { $x = 2 } => 0;
 183          ...
 184         }
 185         # $x is 0
 186
 187     The first case is "solved" by moving the "local" before the "reap", and
 188     the second by using "localize" instead of "reap".
 189
 190     "reap", "localize" and "localize_elem" effects can't cross "BEGIN"
 191     blocks, hence calling those functions in "import" is deemed to be
 192     useless. This is an hopeless case because "BEGIN" blocks are executed
 193     once while localizing constructs should do their job at each run.
 194
 195 DEPENDENCIES
 196     XSLoader (standard since perl 5.006).
 197
 198 SEE ALSO
 199     Alias, Hook::Scope, Scope::Guard, Guard.
 200
 201 AUTHOR
 202     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 203
 204     You can contact me by mail or on "irc.perl.org" (vincent).
 205
 206 BUGS
 207     Please report any bugs or feature requests to "bug-scope-upper at
 208     rt.cpan.org", or through the web interface at
 209     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper>. I will be
 210     notified, and then you'll automatically be notified of progress on your
 211     bug as I make changes.
 212
 213 SUPPORT
 214     You can find documentation for this module with the perldoc command.
 215
 216         perldoc Scope::Upper
 217
 218     Tests code coverage report is available at
 219     <http://www.profvince.com/perl/cover/Scope-Upper>.
 220
 221 ACKNOWLEDGEMENTS
 222     Inspired by Ricardo Signes.
 223
 224 COPYRIGHT & LICENSE
 225     Copyright 2008-2009 Vincent Pit, all rights reserved.
 226
 227     This program is free software; you can redistribute it and/or modify it
 228     under the same terms as Perl itself.
 229