/ 
assertions-0.03
River stage zero No dependents
/ assertions::compat

NAME

assertions::compat - assertions for pre-5.9 versions of perl

SYNOPSIS

# add support for 'assertion' attribute:
use base 'assertions::compat';
sub assert_foo : assertion { ... };

# then, maybe in another module:
package Foo::Bar;

# define sub 'asserting' with the assertion status:
use assertions::compat;
asserting and assert_foo(1,2,3,4);

# or
use assertions::compat ASST => 'Foo::Bar::doz';
ASST and assert_foo('dozpera');

DESCRIPTION

assertions::compat allows to use assertions on perl versions prior to 5.9.0 (that is the first one to natively support them). Though, it's not magic, do not expect it to allow for conditionally executed subroutines.

This module provides support for two different functionalities:

The assertion attribute handler

The subroutine attribute assertion is not recognised on perls without assertion support. This module provides a MODIFY_CODE_ATTRIBUTES handler for this attribute. It must be used via inheritance:

use base 'assertions::compat';

sub assert_foo : assertion { ... }

Be aware that the handler just discards the attribute, so subroutines declared as assertions will be unconditionally called on perl without native support for them.

This module also provides the supported function to check if assertions are supported or not:

my $supported = assertions::compat::supported();

Assertion execution status as a constant

assertions::compat also allows to create constant subs whose value is the assertion execution status. That allows checking explicitly and efficiently when assertions have to be executed on perls without native assertion support.

For instance...

use assertions::compat ASST => 'Foo::Bar';

exports constant subroutine ASST. Its value is true when assertions tagged as Foo::Bar has been activated via assertions::activate; usually done with the -A switch from the command line on perls supporting it...

perl -A=Foo::Bar my_script.pl

or alternatively with...

perl -Massertions::activate=Foo::Bar my_script.pl

on pre-5.9.0 versions of perl.

The constant sub defined can be used following this idiom:

use assertions::compat ASST => 'Foo::Bar';
...
ASST and assert_foo();

When ASST is false, the perl interpreter optimizes away the rest of the and statement at compile time.

If no assertion selection tags are passed to use assertions::compat, the current module name is used as the selection tag, so...

use assertions::compat 'ASST';

is equivalent to...

use assertions::compat ASST => __PACKAGE__;

If the name of the constant subroutine is also omitted, asserting is used.

This module will not emit a warning when the constant is redefined. this is done on purpose to allow for code like that:

use assertions::compat ASST => 'Foo';
ASST and assert_foo();

use assertions::compat ASST => 'Bar';
ASST and assert_bar();

Finally, be aware that while assertion execution status is lexical scoped, the defined constants are not. You should be careful on that to not write inconsistent code. For instance...

package Foo;

use MyAssertions qw(assert_foo);

use assertions::compat ASST => 'Foo::Out'
{
  use assertions::compat ASST => 'Foo::In';
  ASST and assert_foo(); # ok!
}

ASST and assert_foo()   # bad usage!
# ASST refers to tag Foo::In while assert_foo() is
# called only when Foo::Out has been activated.
# This is not what you want!!!

SEE ALSO

perlrun, assertions, assertions::activate, attributes.

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright 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.