X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=lib%2FScope%2FUpper.pm;h=84de02eea6ebf8befe98320881ff7d27f3d421fa;hb=44bbbdcdafa5707a753abb9de5c5d01cd7388880;hp=5f28c4fc78b522ad4c7418f26be9fbbfb1c41f8a;hpb=b18283efb4680da84e05ce1b3b45dc3f345f4c5a;p=perl%2Fmodules%2FScope-Upper.git diff --git a/lib/Scope/Upper.pm b/lib/Scope/Upper.pm index 5f28c4f..84de02e 100644 --- a/lib/Scope/Upper.pm +++ b/lib/Scope/Upper.pm @@ -9,13 +9,13 @@ Scope::Upper - Act on upper scopes. =head1 VERSION -Version 0.06 +Version 0.10 =cut our $VERSION; BEGIN { - $VERSION = '0.06'; + $VERSION = '0.10'; } =head1 SYNOPSIS @@ -72,7 +72,9 @@ BEGIN { sub zap { try { return @things; # returns to try() and then outside zap() + # not reached } + # not reached } my @what = zap(); # @what contains @things @@ -115,7 +117,7 @@ BEGIN { =head2 C -Add a destructor that calls C<$callback> when the upper scope represented by C<$context> ends. +Add a destructor that calls C<$callback> (in void context) when the upper scope represented by C<$context> ends. =head2 C @@ -142,11 +144,27 @@ will set C<$x> to a reference to the string C<'foo'>. Other sigils (C<'@'>, C<'%'>, C<'&'> and C<'*'>) require C<$value> to be a reference of the corresponding type. When the symbol is given by a string, it is resolved when the actual localization takes place and not when C is called. -This means that +Thus, if the symbol name is not qualified, it will refer to the variable in the package where the localization actually takes place and not in the one where the C call was compiled. +For example, - sub tag { localize '$x', $_[0] => UP } + { + package Scope; + sub new { localize '$tag', $_[0] => UP } + } -will localize in the caller's namespace. + { + package Tool; + { + Scope->new; + ... + } + } + +will localize C<$Tool::tag> and not C<$Scope::tag>. + +Note that if C<$what> is a string denoting a variable that wasn't declared beforehand, the relevant slot will be vivified as needed and won't be deleted from the glob when the localization ends. +This situation never arises with C because it only compiles when the localized variable is already declared. +Although I believe it shouldn't be a problem as glob slots definedness is pretty much an implementation detail, this behaviour may change in the future if proved harmful. =back @@ -156,6 +174,8 @@ Similar to L but for array and hash elements. If C<$what> is a glob, the slot to fill is determined from which type of reference C<$value> is ; otherwise it's inferred from the sigil. C<$key> is either an array index or a hash key, depending of which kind of variable you localize. +Just like for L, when C<$what> is a string pointing to an undeclared variable, it will be vivified but the variable itself will be empty when the localization ends (although it will still exist in its parent glob). + =head2 C Similiar to L, but for deleting variables or array/hash elements. @@ -189,6 +209,7 @@ This means that my $num = sub { my @a = ('a' .. 'z'); unwind @a => HERE; + # not reached }->(); will set C<$num> to C<'z'>. @@ -203,9 +224,16 @@ The previous example can then be "corrected" : my $num = sub { my @a = ('a' .. 'z'); unwind +(want_at(HERE) ? @a : scalar @a) => HERE; + # not reached }->(); -will righteously set C<$num> to C<26>. +will rightfully set C<$num> to C<26>. + +=head1 CONSTANTS + +=head2 C + +True iff the module could have been built when thread-safety features. =head1 WORDS @@ -231,10 +259,12 @@ The context of the scope just above C<$from>. =head3 C The context of the closest subroutine above C<$from>. +Note that C<$from> is returned if it is already a subroutine context ; hence C. =head3 C The context of the closest eval above C<$from>. +Note that C<$from> is returned if it is already an eval context ; hence C. =head2 Getting a context from a level @@ -250,10 +280,70 @@ The C<$level>-th upper context, regardless of its type. The context of the C<$level>-th upper subroutine/eval/format. It kind of corresponds to the context represented by C, but while e.g. C refers to the caller context, C will refer to the top scope in the current context. +=head2 Examples + +Where L fires depending on the C<$cxt> : + + sub { + eval { + sub { + { + reap \&cleanup => $cxt; + ... + } # $cxt = SCOPE(0), or HERE + ... + }->(); # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0) + ... + }; # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1) + ... + }->(); # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2) + ... + +Where L, L and L act depending on the C<$cxt> : + + sub { + eval { + sub { + { + localize '$x' => 1 => $cxt; + # $cxt = SCOPE(0), or HERE + ... + } + # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0) + ... + }->(); + # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1) + ... + }; + # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2) + ... + }->(); + # $cxt = SCOPE(4), UP SUB UP SUB, or UP SUB EVAL, or UP CALLER(2), or TOP + ... + +Where L and L point to depending on the C<$cxt>: + + sub { + eval { + sub { + { + unwind @things => $cxt; + ... + } + ... + }->(); # $cxt = SCOPE(0 .. 1), or HERE, or UP, or SUB, or CALLER(0) + ... + }; # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1) + ... + }->(); # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2) + ... + =head1 EXPORT The functions L, L, L, L, L and L are only exported on request, either individually or by the tags C<':funcs'> and C<':all'>. +The constant L is also only exported on request, individually or by the tags C<':consts'> and C<':all'>. + Same goes for the words L, L, L, L, L, L and L that are only exported on request, individually or by the tags C<':words'> and C<':all'>. =cut @@ -262,8 +352,9 @@ use base qw/Exporter/; our @EXPORT = (); our %EXPORT_TAGS = ( - funcs => [ qw/reap localize localize_elem localize_delete unwind want_at/ ], - words => [ qw/TOP HERE UP SUB EVAL SCOPE CALLER/ ], + funcs => [ qw/reap localize localize_elem localize_delete unwind want_at/ ], + words => [ qw/TOP HERE UP SUB EVAL SCOPE CALLER/ ], + consts => [ qw/SU_THREADSAFE/ ], ); our @EXPORT_OK = map { @$_ } values %EXPORT_TAGS; $EXPORT_TAGS{'all'} = [ @EXPORT_OK ]; @@ -305,6 +396,9 @@ L (standard since perl 5.006). L, L, L, L. +L is a thin wrapper around L that gives you a continuation passing style interface to L. +It's easier to use, but it requires you to have control over the scope where you want to return. + =head1 AUTHOR Vincent Pit, C<< >>, L. @@ -313,7 +407,8 @@ You can contact me by mail or on C (vincent). =head1 BUGS -Please report any bugs or feature requests to C, or through the web interface at L. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. +Please report any bugs or feature requests to C, or through the web interface at L. +I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. =head1 SUPPORT @@ -331,7 +426,7 @@ Thanks to Shawn M. Moore for motivation. =head1 COPYRIGHT & LICENSE -Copyright 2008-2009 Vincent Pit, all rights reserved. +Copyright 2008,2009,2010 Vincent Pit, all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.