11 sub _syntax_error ($$) {
14 Carp::croak("syntax error on assertion filter '$expr' ($why)");
19 if (warnings::enabled('assertions')) {
27 my @tokens=split / \s*
36 # print STDERR "tokens: -", join('-',@tokens), "-\n";
42 next if (!defined $t or $t eq '');
51 and _syntax_error $expr, 'consecutive operators';
56 and _syntax_error $expr, 'consecutive operators';
62 _syntax_error $expr, 'unbalanced parens';
64 _syntax_error $expr, "key missing after operator '$op[0]'";
70 unless ($^H{assertions} & $seen_hint) {
71 _carp "assertion status '_' referenced but not previously defined";
73 $t=($^H{assertions} & $hint) ? 1 : 0;
75 elsif ($t ne '0' and $t ne '1') {
76 $t = ( grep { ref $_ eq 'Regexp'
79 } @{^ASSERTING} ) ? 1 : 0;
83 _syntax_error $expr, 'operator expected';
85 if ($op[0] eq 'start') {
88 elsif ($op[0] eq '||') {
98 @now==1 or _syntax_error $expr, 'unbalanced parens';
99 defined $op[0] and _syntax_error $expr, "expression ends on operator '$op[0]'";
106 # print STDERR "\@_=", join("|", @_), "\n";
108 @_=(scalar(caller)) unless @_;
109 foreach my $expr (@_) {
110 unless (_calc_expr $expr) {
111 # print STDERR "assertions deactived";
112 $^H{assertions} &= ~$hint;
113 $^H{assertions} |= $seen_hint;
117 # print STDERR "assertions actived";
118 $^H{assertions} |= $hint|$seen_hint;
123 and _carp($_[0]."->unimport arguments are being ignored");
124 $^H{assertions} &= ~$hint;
130 $^H{assertions} |= $hint;
133 $^H{assertions} &= ~$hint;
135 $^H{assertions} |= $seen_hint;
137 return $^H{assertions} & $hint ? 1 : 0;
143 $^H{assertions} |= $seen_hint;
146 $^H{assertions} &= ~$seen_hint;
149 return $^H{assertions} & $seen_hint ? 1 : 0;
159 assertions - select assertions in blocks of code
163 sub assert (&) : assertion { &{$_[0]}() }
165 use assertions 'foo';
166 assert { print "asserting 'foo'\n" };
169 use assertions qw( foo bar );
170 assert { print "asserting 'foo' and 'bar'\n" };
174 use assertions qw( bar );
175 assert { print "asserting only 'bar'\n" };
179 use assertions '_ && bar';
180 assert { print "asserting 'foo' && 'bar'\n" };
183 assert { print "asserting 'foo' again\n" };
187 *** WARNING: assertion support is only available from perl version
188 *** 5.9.0 and upwards. Check assertions::compat (also available from
189 *** this package) for an alternative backwards compatible module.
191 The C<assertions> pragma specifies the tags used to enable and disable
192 the execution of assertion subroutines.
194 An assertion subroutine is declared with the C<:assertion> attribute.
195 This subroutine is not normally executed: it's optimized away by perl
198 The C<assertions> pragma associates to its lexical scope one or
199 several assertion tags. Then, to activate the execution of the
200 assertions subroutines in this scope, these tags must be given to perl
201 via the B<-A> command-line option. For instance, if...
203 use assertions 'foobar';
205 is used, assertions on the same lexical scope will only be executed
206 when perl is called as...
208 perl -A=foobar script.pl
210 Regular expressions can also be used within the -A
211 switch. For instance...
213 perl -A='foo.*' script.pl
215 will activate assertions tagged as C<foo>, C<foobar>, C<foofoo>, etc.
217 =head2 Selecting assertions
219 Selecting which tags are required to activate assertions inside a
220 lexical scope, is done with the arguments passed on the C<use
221 assertions> sentence.
223 If no arguments are given, the package name is used as the assertion tag:
229 use assertions __PACKAGE__;
231 When several tags are given, all of them have to be activated via the
232 C<-A> switch to activate assertion execution on that lexical scope,
235 use assertions qw(Foo Bar);
237 Constants C<1> and C<0> can be used to force unconditional activation
238 or deactivation respectively:
243 Operators C<&&> and C<||> and parenthesis C<(...)> can be used to
244 construct logical expressions:
246 use assertions 'foo && bar';
247 use assertions 'foo || bar';
248 use assertions 'foo && (bar || doz)';
250 (note that the logical operators and the parens have to be included
251 inside the quoted string).
253 Finally, the special tag C<_> refers to the current assertion
256 use assertions 'foo';
257 use assertions '_ && bar;
261 use assertions 'foo && bar';
263 =head2 Handling assertions your own way
265 The C<assertions> module also provides a set of low level functions to
266 allow for custom assertion handling modules.
268 Those functions are not exported and have to be fully qualified with
269 the package name when called, for instance:
272 assertions::enabled(1);
274 (note that C<assertions> is loaded with the C<require> keyword
275 to avoid calling C<assertions::import()>).
277 Those functions have to be called at compile time (they are
284 activates or deactivates assertion execution. For instance:
286 package assertions::always;
289 sub import { assertions::enabled(1) }
293 This function calls C<assertion::seen(1)> also (see below).
297 returns a true value when assertion execution is active.
301 A warning is generated when an assertion subroutine is found before
302 any assertion selection code. This function is used to just tell perl
303 that assertion selection code has been seen and that the warning is
304 not required for the currently compiling lexical scope.
308 returns true if any assertion selection module (or code) has been
309 called before on the currently compiling lexical scope.
315 Support for assertions is only available in perl from version 5.9. On
316 previous perl versions this module will do nothing, though it will not
319 L<assertions::compat> provides an alternative way to use assertions
320 compatible with lower versions of perl.
325 L<perlrun>, L<assertions::activate>, L<assertions::compat>.
329 Salvador FandiE<ntilde>o, E<lt>sfandino@yahoo.comE<gt>
331 =head1 COPYRIGHT AND LICENSE
333 Copyright 2002, 2005 by Salvador FandiE<ntilde>o
335 This library is free software; you can redistribute it and/or modify
336 it under the same terms as Perl itself.