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>

