README

   1 NAME
   2     Scope::Upper - Act on upper scopes.
   3
   4 VERSION
   5     Version 0.01
   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 assign to. If the sigil is '$', then $value isn't dereferenced,
  64         that is
  65
  66             localize '$x', \'foo' => 0;
  67
  68         will set $x to a reference to the string 'foo'. Other sigils behave
  69         as if a glob was passed.
  70
  71         The symbol is resolved when the actual localization takes place and
  72         not when "localize" is called. This means that
  73
  74             sub tag { localize '$x', $_[0] => 1; }
  75
  76         will localize in the caller's namespace.
  77
  78   "localize_elem $what, $key, $value, $level"
  79     Similar to "localize" but for array and hash elements. If $what is a
  80     glob, the slot to fill is determined from which type of reference $value
  81     is ; otherwise it's inferred from the sigil. $key is either an array
  82     index or a hash key, depending of which kind of variable you localize.
  83
  84   "TOPLEVEL"
  85     Returns the level that currently represents the highest scope.
  86
  87 EXPORT
  88     The functions "reap", "localize", "localize_elem" and "TOPLEVEL" are
  89     only exported on request, either individually or by the tags ':funcs'
  90     and ':all'.
  91
  92 DEPENDENCIES
  93     XSLoader (standard since perl 5.006).
  94
  95 SEE ALSO
  96     Alias, Hook::Scope, Scope::Guard, Guard.
  97
  98 AUTHOR
  99     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 100
 101     You can contact me by mail or on "irc.perl.org" (vincent).
 102
 103 BUGS
 104     Please report any bugs or feature requests to "bug-scope-upper at
 105     rt.cpan.org", or through the web interface at
 106     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper>. I will be
 107     notified, and then you'll automatically be notified of progress on your
 108     bug as I make changes.
 109
 110 SUPPORT
 111     You can find documentation for this module with the perldoc command.
 112
 113         perldoc Scope::Upper
 114
 115 ACKNOWLEDGEMENTS
 116     Inspired by Ricardo Signes.
 117
 118 COPYRIGHT & LICENSE
 119     Copyright 2008 Vincent Pit, all rights reserved.
 120
 121     This program is free software; you can redistribute it and/or modify it
 122     under the same terms as Perl itself.
 123