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 <[email protected]>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.