X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=lib%2FScope%2FUpper.pm;h=104674dae43167fb3afd32fda5f2b9f04a2db6c7;hb=refs%2Ftags%2Fv0.08;hp=988254fa5016b804443464a1fbb23fb2067aa5d9;hpb=9a258ccdcca73cc6ca9470c06e7db103c3ba8193;p=perl%2Fmodules%2FScope-Upper.git diff --git a/lib/Scope/Upper.pm b/lib/Scope/Upper.pm index 988254f..104674d 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.05 +Version 0.08 =cut our $VERSION; BEGIN { - $VERSION = '0.05'; + $VERSION = '0.08'; } =head1 SYNOPSIS @@ -72,27 +72,41 @@ BEGIN { sub zap { try { return @things; # returns to try() and then outside zap() + # not reached } + # not reached } my @what = zap(); # @what contains @things =head1 DESCRIPTION -This module lets you defer actions that will take place when the control flow returns into an upper scope. -Currently, you can hook an upper scope end, or localize variables, array/hash values or deletions of elements in higher contexts. -You can also return to an upper level and know which context was in use then. +This module lets you defer actions I that will take place when the control flow returns into an upper scope. +Currently, you can: + +=over 4 + +=item * + +hook an upper scope end with L ; + +=item * + +localize variables, array/hash values or deletions of elements in higher contexts with respectively L, L and L ; + +=item * + +return values immediately to an upper level with L, and know which context was in use then with L. + +=back =head1 FUNCTIONS In all those functions, C<$context> refers to the target scope. -You have to use one or a combination of L to build the C<$context> to pass to these functions. +You have to use one or a combination of L to build the C<$context> passed to these functions. This is needed in order to ensure that the module still works when your program is ran in the debugger. -Don't try to use a raw value or things will get messy. - -The only thing you can assume is that it is an I indicator of the frame. -This means that you can safely store it at some point and use it when needed, and it will still denote the original scope. +The only thing you can assume is that it is an I indicator of the frame, which means that you can safely store it at some point and use it when needed, and it will still denote the original scope. =cut @@ -103,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 @@ -169,7 +183,7 @@ C<$key> is ignored. =head2 C -Returns C<@values> I the context pointed by C<$context>, i.e. from the subroutine, eval or format just above C<$context>. +Returns C<@values> I the context pointed by C<$context>, i.e. from the subroutine, eval or format just above C<$context>, and immediately restart the program flow at this point - thus effectively returning to (or from, depending on how you see it) an upper context. The upper context isn't coerced onto C<@values>, which is hence always evaluated in list context. This means that @@ -177,6 +191,7 @@ This means that my $num = sub { my @a = ('a' .. 'z'); unwind @a => HERE; + # not reached }->(); will set C<$num> to C<'z'>. @@ -191,6 +206,7 @@ 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>. @@ -219,10 +235,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 @@ -238,6 +256,64 @@ 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'>. @@ -278,11 +354,12 @@ Consider those examples: The first case is "solved" by moving the C before the C, and the second by using L instead of L. -L, L and L effects can't cross C blocks, hence calling those functions in C is deemed to be useless. +The effects of L, L and L can't cross C blocks, hence calling those functions in C is deemed to be useless. This is an hopeless case because C blocks are executed once while localizing constructs should do their job at each run. +However, it's possible to hook the end of the current scope compilation with L. Some rare oddities may still happen when running inside the debugger. -It may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some context fixes. +It may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some context-related fixes. =head1 DEPENDENCIES