README

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