]> git.vpit.fr Git - perl/modules/Scope-Upper.git/blob - lib/Scope/Upper.pm
Introduce want_at()
[perl/modules/Scope-Upper.git] / lib / Scope / Upper.pm
1 package Scope::Upper;
2
3 use strict;
4 use warnings;
5
6 =head1 NAME
7
8 Scope::Upper - Act on upper scopes.
9
10 =head1 VERSION
11
12 Version 0.03
13
14 =cut
15
16 our $VERSION;
17 BEGIN {
18  $VERSION = '0.03';
19 }
20
21 =head1 SYNOPSIS
22
23     package X;
24
25     use Scope::Upper qw/reap localize localize_elem localize_delete/;
26
27     sub desc { shift->{desc} }
28
29     sub set_tag {
30      my ($desc) = @_;
31
32      # First localize $x so that it gets destroyed last
33      localize '$x' => bless({ desc => $desc }, __PACKAGE__) => 1;
34
35      reap sub {
36       my $pkg = caller;
37       my $x = do { no strict 'refs'; ${$pkg.'::x'} }; # Get the $x in the scope
38       print $x->desc . ": done\n";
39      } => 1;
40
41      localize_elem '%SIG', '__WARN__' => sub {
42       my $pkg = caller;
43       my $x = do { no strict 'refs'; ${$pkg.'::x'} }; # Get the $x in the scope
44       CORE::warn($x->desc . ': ' . join('', @_));
45      } => 1;
46
47      localize_delete '@ARGV', $#ARGV => 1; # delete last @ARGV element
48     }
49
50     package Y;
51
52     {
53      X::set_tag('pie');
54      # $x is now a X object, and @ARGV has one element less
55      warn 'what'; # warns "pie: what at ..."
56      ...
57     } # "pie: done" is printed
58
59 =head1 DESCRIPTION
60
61 This module lets you defer actions that will take place when the control flow returns into an upper scope.
62 Currently, you can hook an upper scope end, or localize variables, array/hash values or deletions of elements in higher contexts.
63
64 =head1 FUNCTIONS
65
66 =cut
67
68 BEGIN {
69  require XSLoader;
70  XSLoader::load(__PACKAGE__, $VERSION);
71 }
72
73 =head2 C<reap $callback, $level>
74
75 Add a destructor that calls C<$callback> when the C<$level>-th upper scope ends, where C<0> corresponds to the current scope.
76
77 =head2 C<localize $what, $value, $level>
78
79 A C<local> delayed to the time of first return into the C<$level>-th upper scope.
80 C<$what> can be :
81
82 =over 4
83
84 =item *
85
86 A glob, in which case C<$value> can either be a glob or a reference.
87 L</localize> follows then the same syntax as C<local *x = $value>.
88 For example, if C<$value> is a scalar reference, then the C<SCALAR> slot of the glob will be set to C<$$value> - just like C<local *x = \1> sets C<$x> to C<1>.
89
90 =item *
91
92 A string beginning with a sigil, representing the symbol to localize and to assign to.
93 If the sigil is C<'$'>, L</localize> follows the same syntax as C<local $x = $value>, i.e. C<$value> isn't dereferenced.
94 For example,
95
96     localize '$x', \'foo' => 0;
97
98 will set C<$x> to a reference to the string C<'foo'>.
99 Other sigils (C<'@'>, C<'%'>, C<'&'> and C<'*'>) require C<$value> to be a reference of the corresponding type.
100
101 When the symbol is given by a string, it is resolved when the actual localization takes place and not when C<localize> is called.
102 This means that
103
104     sub tag { localize '$x', $_[0] => 1; }
105
106 will localize in the caller's namespace.
107
108 =back
109
110 =head2 C<localize_elem $what, $key, $value, $level>
111
112 Similar to L</localize> but for array and hash elements.
113 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.
114 C<$key> is either an array index or a hash key, depending of which kind of variable you localize.
115
116 =head2 C<localize_delete $what, $key, $level>
117
118 Similiar to L</localize>, but for deleting variables or array/hash elements.
119 C<$what> can be:
120
121 =over 4
122
123 =item *
124
125 A glob, in which case C<$key> is ignored and the call is equivalent to C<local *x>.
126
127 =item *
128
129 A string beginning with C<'@'> or C<'%'>, for which the call is equivalent to respectiveley C<local $a[$key]; delete $a[$key]> and C<local $h{$key}; delete $h{$key}>.
130
131 =item *
132
133 A string beginning with C<'&'>, which more or less does C<undef &func> in the upper scope.
134 It's actually more powerful, as C<&func> won't even C<exists> anymore.
135 C<$key> is ignored.
136
137 =back
138
139 =head2 C<unwind @values, $level>
140
141 Returns C<@values> I<from> the context indicated by C<$level>, i.e. from the subroutine, eval or format just above C<$level>.
142 The upper level isn't coerced onto C<@values>, which is hence always evaluated in list context.
143
144 =head2 C<want_at $level>
145
146 Like C<wantarray>, but for the subroutine/eval/format context just above C<$level>.
147
148 =head1 WORDS
149
150 =head2 C<TOP>
151
152 Returns the level that currently represents the highest scope.
153
154 =head2 C<HERE>
155
156 The current level - i.e. C<0>.
157
158 =head2 C<UP $from>
159
160 The level of the scope just above C<$from>.
161
162 =head2 C<DOWN $from>
163
164 The level of the scope just below C<$from>.
165
166 =head2 C<SUB $from>
167
168 The level of the closest subroutine context above C<$from>.
169
170 =head2 C<EVAL $from>
171
172 The level of the closest eval context above C<$from>.
173
174 If C<$from> is omitted in any of those functions, the current level is used as the reference level.
175
176 =head2 C<CALLER $stack>
177
178 The level corresponding to the stack referenced by C<caller $stack>.
179
180 =head1 EXPORT
181
182 The functions L</reap>, L</localize>, L</localize_elem>, L</localize_delete>,  L</unwind> and L</want_at> are only exported on request, either individually or by the tags C<':funcs'> and C<':all'>.
183
184 Same goes for the words L</TOP>, L</HERE>, L</UP>, L</DOWN>, L</SUB>, L</EVAL> and L</CALLER> that are only exported on request, individually or by the tags C<':words'> and C<':all'>.
185
186 =cut
187
188 use base qw/Exporter/;
189
190 our @EXPORT      = ();
191 our %EXPORT_TAGS = (
192  funcs => [ qw/reap localize localize_elem localize_delete unwind want_at/ ],
193  words => [ qw/TOP HERE UP DOWN SUB EVAL CALLER/ ],
194 );
195 our @EXPORT_OK   = map { @$_ } values %EXPORT_TAGS;
196 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
197
198 =head1 CAVEATS
199
200 Be careful that local variables are restored in the reverse order in which they were localized.
201 Consider those examples:
202
203     local $x = 0;
204     {
205      reap sub { print $x } => 0;
206      local $x = 1;
207      ...
208     }
209     # prints '0'
210     ...
211     {
212      local $x = 1;
213      reap sub { $x = 2 } => 0;
214      ...
215     }
216     # $x is 0
217
218 The first case is "solved" by moving the C<local> before the C<reap>, and the second by using L</localize> instead of L</reap>.
219
220 L</reap>, L</localize> and L</localize_elem> effects can't cross C<BEGIN> blocks, hence calling those functions in C<import> is deemed to be useless.
221 This is an hopeless case because C<BEGIN> blocks are executed once while localizing constructs should do their job at each run.
222
223 =head1 DEPENDENCIES
224
225 L<XSLoader> (standard since perl 5.006).
226
227 =head1 SEE ALSO
228
229 L<Alias>, L<Hook::Scope>, L<Scope::Guard>, L<Guard>.
230
231 =head1 AUTHOR
232
233 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
234
235 You can contact me by mail or on C<irc.perl.org> (vincent).
236
237 =head1 BUGS
238
239 Please report any bugs or feature requests to C<bug-scope-upper at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper>.  I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
240
241 =head1 SUPPORT
242
243 You can find documentation for this module with the perldoc command.
244
245     perldoc Scope::Upper
246
247 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Scope-Upper>.
248
249 =head1 ACKNOWLEDGEMENTS
250
251 Inspired by Ricardo Signes.
252
253 =head1 COPYRIGHT & LICENSE
254
255 Copyright 2008-2009 Vincent Pit, all rights reserved.
256
257 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
258
259 =cut
260
261 1; # End of Scope::Upper