X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=lib%2FScope%2FUpper.pm;h=30f94547df8d937db1481de5b8bfdfa76e1ea1c0;hb=fe22a6565e85581207e3f4222eae26bc268223e4;hp=988254fa5016b804443464a1fbb23fb2067aa5d9;hpb=9a258ccdcca73cc6ca9470c06e7db103c3ba8193;p=perl%2Fmodules%2FScope-Upper.git diff --git a/lib/Scope/Upper.pm b/lib/Scope/Upper.pm index 988254f..30f9454 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.10 =cut our $VERSION; BEGIN { - $VERSION = '0.05'; + $VERSION = '0.10'; } =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,9 +206,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 @@ -219,10 +241,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,10 +262,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 @@ -250,8 +334,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 ]; @@ -278,11 +363,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 @@ -292,6 +378,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. @@ -318,7 +407,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.