/ 
Syntax-Keyword-Assert-0.01
River stage zero No dependents
/ Syntax::Keyword::Assert

NAME

Syntax::Keyword::Assert - debugging checks that throw exceptions

SYNOPSIS

use v5.14;
use Syntax::Keyword::Assert;

my @items;

...

sub get_next_item {
   assert(@items);
   return shift @items;
}

DESCRIPTION

This module provides a syntax plugin that implements a keyword which checks the truth of its expression, throwing an exception if it is false.

This is similar to the same keyword found in C and maybe other languages.

By default assertions are enabled, but they can be entirely disabled by setting the environment variable PERL_ASSERT_ENABLED to zero before the module is loaded.

$ PERL_ASSERT_ENABLED=0 perl ...

When disabled, the entire expression is skipped over at compiletime, meaning that it has exactly zero run-time performance effect. This can be useful for disabling such checks in high-performance production environments. Knowing that they will have no run-time effect in such cases, developers may be more willing to insert assertion checks into code that can reveal issues during development and testing in non-critical places.

Because of this disable mode, assertion expressions should not contain any side-effects as those effects will not happen when assertions are disabled.

KEYWORDS

assert

assert(EXPR);

The assert keyword evaluates its expression in scalar context. If it has a true value then nothing further happens. If it is false, then an exception is thrown.

If the expression is given as a numerical or string equality test, then the assertion prints the LHS and RHS values separately if it fails, giving a more useful failure message.

TODO

  • Customisable failure message.

  • Finer control of whether assertion checks are enabled. Per-package/scope/file?

  • Random 1-of-n sampling mode for enabling.

  • Inspection into other binary comparison operators.

  • Inspection of other assertions like reftype tests?

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>