README

   1 NAME
   2     Scope::Upper - Act on upper scopes.
   3
   4 VERSION
   5     Version 0.03
   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 DESCRIPTION
  45     This module lets you defer actions that will take place when the control
  46     flow returns into an upper scope. Currently, you can hook an upper scope
  47     end, or localize variables, array/hash values or deletions of elements
  48     in higher contexts.
  49
  50 FUNCTIONS
  51   "reap $callback, $level"
  52     Add a destructor that calls $callback when the $level-th upper scope
  53     ends, where 0 corresponds to the current scope.
  54
  55   "localize $what, $value, $level"
  56     A "local" delayed to the time of first return into the $level-th upper
  57     scope. $what can be :
  58
  59     *   A glob, in which case $value can either be a glob or a reference.
  60         "localize" follows then the same syntax as "local *x = $value". For
  61         example, if $value is a scalar reference, then the "SCALAR" slot of
  62         the glob will be set to $$value - just like "local *x = \1" sets $x
  63         to 1.
  64
  65     *   A string beginning with a sigil, representing the symbol to localize
  66         and to assign to. If the sigil is '$', "localize" follows the same
  67         syntax as "local $x = $value", i.e. $value isn't dereferenced. For
  68         example,
  69
  70             localize '$x', \'foo' => 0;
  71
  72         will set $x to a reference to the string 'foo'. Other sigils ('@',
  73         '%', '&' and '*') require $value to be a reference of the
  74         corresponding type.
  75
  76         When the symbol is given by a string, it is resolved when the actual
  77         localization takes place and not when "localize" is called. This
  78         means that
  79
  80             sub tag { localize '$x', $_[0] => 1; }
  81
  82         will localize in the caller's namespace.
  83
  84   "localize_elem $what, $key, $value, $level"
  85     Similar to "localize" but for array and hash elements. If $what is a
  86     glob, the slot to fill is determined from which type of reference $value
  87     is ; otherwise it's inferred from the sigil. $key is either an array
  88     index or a hash key, depending of which kind of variable you localize.
  89
  90   "localize_delete $what, $key, $level"
  91     Similiar to "localize", but for deleting variables or array/hash
  92     elements. $what can be:
  93
  94     *   A glob, in which case $key is ignored and the call is equivalent to
  95         "local *x".
  96
  97     *   A string beginning with '@' or '%', for which the call is equivalent
  98         to respectiveley "local $a[$key]; delete $a[$key]" and "local
  99         $h{$key}; delete $h{$key}".
 100
 101     *   A string beginning with '&', which more or less does "undef &func"
 102         in the upper scope. It's actually more powerful, as &func won't even
 103         "exists" anymore. $key is ignored.
 104
 105   "TOPLEVEL"
 106     Returns the level that currently represents the highest scope.
 107
 108 EXPORT
 109     The functions "reap", "localize", "localize_elem", "localize_delete" and
 110     "TOPLEVEL" are only exported on request, either individually or by the
 111     tags ':funcs' and ':all'.
 112
 113 CAVEATS
 114     Be careful that local variables are restored in the reverse order in
 115     which they were localized. Consider those examples:
 116
 117         local $x = 0;
 118         {
 119          reap sub { print $x } => 0;
 120          local $x = 1;
 121          ...
 122         }
 123         # prints '0'
 124         ...
 125         {
 126          local $x = 1;
 127          reap sub { $x = 2 } => 0;
 128          ...
 129         }
 130         # $x is 0
 131
 132     The first case is "solved" by moving the "local" before the "reap", and
 133     the second by using "localize" instead of "reap".
 134
 135     "reap", "localize" and "localize_elem" effects can't cross "BEGIN"
 136     blocks, hence calling those functions in "import" is deemed to be
 137     useless. This is an hopeless case because "BEGIN" blocks are executed
 138     once while localizing constructs should do their job at each run.
 139
 140 DEPENDENCIES
 141     XSLoader (standard since perl 5.006).
 142
 143 SEE ALSO
 144     Alias, Hook::Scope, Scope::Guard, Guard.
 145
 146 AUTHOR
 147     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 148
 149     You can contact me by mail or on "irc.perl.org" (vincent).
 150
 151 BUGS
 152     Please report any bugs or feature requests to "bug-scope-upper at
 153     rt.cpan.org", or through the web interface at
 154     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper>. I will be
 155     notified, and then you'll automatically be notified of progress on your
 156     bug as I make changes.
 157
 158 SUPPORT
 159     You can find documentation for this module with the perldoc command.
 160
 161         perldoc Scope::Upper
 162
 163     Tests code coverage report is available at
 164     <http://www.profvince.com/perl/cover/Scope-Upper>.
 165
 166 ACKNOWLEDGEMENTS
 167     Inspired by Ricardo Signes.
 168
 169 COPYRIGHT & LICENSE
 170     Copyright 2008-2009 Vincent Pit, all rights reserved.
 171
 172     This program is free software; you can redistribute it and/or modify it
 173     under the same terms as Perl itself.
 174