/ 
Sub-Assert-1.23
River stage one • 2 direct dependents • 2 total dependents
/ Sub::Assert

NAME

Sub::Assert - Subroutine pre- and postconditions, etc.

SYNOPSIS

use Sub::Assert;

sub squareroot {
    my $x = shift;
    return $x**0.5;
}

assert
       pre     => {
          # named assertion:
         'parameter larger than one' => '$PARAM[0] >= 1',
       },
       post    => '$VOID or $RETURN <= $PARAM[0]', # unnamed assertion
       sub     => 'squareroot',
       context => 'novoid',
       action  => 'carp';

print squareroot(2), "\n";  # prints 1.41421 and so on
print squareroot(-1), "\n"; # warns
                            # "Precondition 1 for main::squareroot failed."
squareroot(2);              # warns
                            # "main::squareroot called in void context."

sub faultysqrt {
    my $x = shift;
    return $x**2;
}

assert
       pre    => '$PARAM[0] >= 1',
       post   => '$RETURN <= $PARAM[0]',
       sub    => 'faultysqrt';

print faultysqrt(2), "\n";  # dies with 
                            # "Postcondition 1 for main::squareroot failed."

DESCRIPTION

The Sub::Assert module implements subroutine pre- and postconditions. Furthermore, it allows restricting the subroutine's calling context.

There's one big gotcha with this: It's slow. For every call to subroutines you use assert() with, you pay for the error checking with an extra subroutine call, some memory and some additional code that's executed.

Fortunately, there's a workaround for mature software which does not require you to edit a lot of your code. Instead of use()ing Sub::Assert, you simply use Sub::Assert::Nothing and leave the assertions intact. While you still suffer the calls to assert() once, you won't pay the run-time penalty usually associated with subroutine pre- and postconditions. Of course, you lose the benefits, too, but as stated previously, this is a workaround in case you want the verification at development time, but prefer speed in production without refactoring your code.

assert

The assert subroutine takes a key/value list of named parameters.

sub

The only required parameter is the 'sub' parameter that specifies which subroutine (in the current package) to replace with the assertion wrapper. The 'sub' parameter may either be a string in which case the current packages subroutine of that name is replaced, or it may be a subroutine reference. In the latter case, assert() returns the assertion wrapper as a subroutine reference.

pre

This parameter specifies one or more preconditions that the data passed to the transformed subroutine must match. The preconditions may either be a string in case there's only one, unnamed precondition, an array (reference) of strings in case there's many unnamed preconditions, or a hash reference of name/condition pairs for named preconditions.

There are several special variables in the scope in which these preconditions are evaluated. Most importantly, @PARAM will hold the list of arguments as passed to the subroutine. Furthermore, there is the scalar $SUBROUTINEREF which holds the reference to the subroutine that does the actual work. I am mentioning this variable because I don't want you to muck with it.

post

This parameter specifies one or more postconditions that the data returned from the subroutine must match. Syntax is identical to that of the preconditions except that there are more special vars:

In scalar context, $RETURN holds the return value of the subroutine and $RETURN[0] does, too. $VOID is undefined.

In list context, @RETURN holds all return values of the subroutine and $RETURN holds the first. $VOID is undefined.

In void context, $RETURN is undefined and @RETURN is empty. $VOID, however, is true.

Note the behaviour in void context. May be a bug or a feature. I'd appreciate feedback and suggestions on how to solve is more elegantly.

context

Optionally, you may restrict the calling context of the subroutine. The context parameter may be any of the following and defaults to no restrictions ('any'):

any

This means that there is no restriction on the calling context of the subroutine. Please refer to the documentation of the 'post' parameter for a gotcha with void context.

scalar

This means that the assertion wrapper will throw an error of the calling context of the subroutine is not scalar context.

list

This means that the assertion wrapper will throw an error of the calling context of the subroutine is not list context.

void

This means that the assertion wrapper will throw an error of the calling context of the subroutine is not void context. Please refer to the documentation of the 'post' parameter for a gotcha with void context.

novoid

This restricts the calling context to any but void context.

action

By default, the assertion wrapper croaks when encountering an error. You may override this behaviour by supplying an action parameter. This parameter is to be the name of a function to handle the error. This function will then be passed the error string. Please note that the immediate predecessor of the subroutine on the call stack is the code evaluation. Thus, for a helpful error message, you'd want to use 'carp' and 'croak' instead of the analogeous 'warn' and 'die'. Your own error handling functions need to be aware of this, too. Please refer to the documentation of the Carp module and the caller() function. Examples:

action => 'carp',
action => 'my_function_that_handles_the_error',
action => '$anon_sub->',  # works only in the lexical scope of $anon_sub!

EXPORT

Exports the 'assert' subroutine to the caller's namespace.

AUTHOR

Steffen Mueller <smueller@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2003-2009 Steffen Mueller

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

SEE ALSO

Sub::Assert::Nothing

Look for new versions of this module on CPAN or at http://steffen-mueller.net