X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=lib%2FScope%2FUpper.pm;h=6e02d2cc7d83004c609b9ff98f89a3d683aea727;hb=1e8a530156ab09a816d8afc37692d1b46032eb32;hp=06ee4876df492c52e1009bcd8d0d9eeb34751045;hpb=31cdfcd5881e5f9b5a49646d5c9a7f75a7c12a15;p=perl%2Fmodules%2FScope-Upper.git diff --git a/lib/Scope/Upper.pm b/lib/Scope/Upper.pm index 06ee487..6e02d2c 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.09 +Version 0.10 =cut our $VERSION; BEGIN { - $VERSION = '0.09'; + $VERSION = '0.10'; } =head1 SYNOPSIS @@ -117,11 +117,11 @@ BEGIN { =head2 C -Add a destructor that calls C<$callback> (in void context) when the upper scope represented by C<$context> ends. +Adds a destructor that calls C<$callback> (in void context) when the upper scope represented by C<$context> ends. =head2 C -A C delayed to the time of first return into the upper scope denoted by C<$context>. +Introduces a C delayed to the time of first return into the upper scope denoted by C<$context>. C<$what> can be : =over 4 @@ -144,23 +144,42 @@ 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, + + { + package Scope; + sub new { localize '$tag', $_[0] => UP } + } + + { + package Tool; + { + Scope->new; + ... + } + } - sub tag { localize '$x', $_[0] => UP } +will localize C<$Tool::tag> and not C<$Scope::tag>. +If you want the other behaviour, you just have to specify C<$what> as a glob or a qualified name. -will localize in the caller's namespace. +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 =head2 C -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. +Introduces a C or C delayed to the time of first return into the upper scope denoted by C<$context>. +Just like for L, the type of localization is determined from which kind of reference C<$value> is when C<$what> is a glob, and from the sigil when it's a string. C<$key> is either an array index or a hash key, depending of which kind of variable you localize. +If C<$what> is a string pointing to an undeclared variable, the variable will be vivified as soon as the localization occurs and emptied when it ends, although it will still exist in its glob. + =head2 C -Similiar to L, but for deleting variables or array/hash elements. +Introduces the deletion of a variable or an array/hash element delayed to the time of first return into the upper scope denoted by C<$context>. C<$what> can be: =over 4 @@ -183,7 +202,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>, and immediately restart the program flow at this point - thus effectively returning to (or from, depending on how you see it) an upper context. +Returns C<@values> I the context pointed by C<$context>, i.e. from the subroutine, eval or format at or just above C<$context>, and immediately restart the program flow at this point - thus effectively returning to an upper scope. The upper context isn't coerced onto C<@values>, which is hence always evaluated in list context. This means that @@ -199,7 +218,7 @@ You can use L to handle these cases. =head2 C -Like C, but for the subroutine/eval/format just above C<$context>. +Like C, but for the subroutine/eval/format at or just above C<$context>. The previous example can then be "corrected" : @@ -378,6 +397,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. @@ -386,7 +408,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 @@ -404,7 +427,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.