/ 
assertions-0.03
River stage zero No dependents
/ assertions

NAME

assertions - select assertions in blocks of code

SYNOPSIS

sub assert (&) : assertion { &{$_[0]}() }

use assertions 'foo';
assert { print "asserting 'foo'\n" };

{
    use assertions qw( foo bar );
    assert { print "asserting 'foo' and 'bar'\n" };
}

{
    use assertions qw( bar );
    assert { print "asserting only 'bar'\n" };
}

{
    use assertions '_ && bar';
    assert { print "asserting 'foo' && 'bar'\n" };
}

assert { print "asserting 'foo' again\n" };

DESCRIPTION

*** WARNING: assertion support is only available from perl version
*** 5.9.0 and upwards. Check assertions::compat (also available from
*** this package) for an alternative backwards compatible module.

The assertions pragma specifies the tags used to enable and disable the execution of assertion subroutines.

An assertion subroutine is declared with the :assertion attribute. This subroutine is not normally executed: it's optimized away by perl at compile-time.

The assertions pragma associates to its lexical scope one or several assertion tags. Then, to activate the execution of the assertions subroutines in this scope, these tags must be given to perl via the -A command-line option. For instance, if...

use assertions 'foobar';

is used, assertions on the same lexical scope will only be executed when perl is called as...

perl -A=foobar script.pl

Regular expressions can also be used within the -A switch. For instance...

perl -A='foo.*' script.pl

will activate assertions tagged as foo, foobar, foofoo, etc.

Selecting assertions

Selecting which tags are required to activate assertions inside a lexical scope, is done with the arguments passed on the use assertions sentence.

If no arguments are given, the package name is used as the assertion tag:

use assertions;

is equivalent to

use assertions __PACKAGE__;

When several tags are given, all of them have to be activated via the -A switch to activate assertion execution on that lexical scope, i.e.:

use assertions qw(Foo Bar);

Constants 1 and 0 can be used to force unconditional activation or deactivation respectively:

use assertions '0';
use assertions '1';

Operators && and || and parenthesis (...) can be used to construct logical expressions:

use assertions 'foo && bar';
use assertions 'foo || bar';
use assertions 'foo && (bar || doz)';

(note that the logical operators and the parens have to be included inside the quoted string).

Finally, the special tag _ refers to the current assertion activation state:

use assertions 'foo';
use assertions '_ && bar;

is equivalent to

use assertions 'foo && bar';

Handling assertions your own way

The assertions module also provides a set of low level functions to allow for custom assertion handling modules.

Those functions are not exported and have to be fully qualified with the package name when called, for instance:

require assertions;
assertions::enabled(1);

(note that assertions is loaded with the require keyword to avoid calling assertions::import()).

Those functions have to be called at compile time (they are useless at runtime).

enabled($on)

activates or deactivates assertion execution. For instance:

package assertions::always;

require assertions;
sub import { assertions::enabled(1) }

1;

This function calls assertion::seen(1) also (see below).

enabled()

returns a true value when assertion execution is active.

seen($on)

A warning is generated when an assertion subroutine is found before any assertion selection code. This function is used to just tell perl that assertion selection code has been seen and that the warning is not required for the currently compiling lexical scope.

seen()

returns true if any assertion selection module (or code) has been called before on the currently compiling lexical scope.

COMPATIBILITY

Support for assertions is only available in perl from version 5.9. On previous perl versions this module will do nothing, though it will not harm either.

assertions::compat provides an alternative way to use assertions compatible with lower versions of perl.

SEE ALSO

perlrun, assertions::activate, assertions::compat.

AUTHOR

Salvador Fandiño, <sfandino@yahoo.com>

COPYRIGHT AND LICENSE

Copyright 2002, 2005 by Salvador Fandiño

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.