/ 
TUI-Vision-v2.0.1
/ PerlX::Assert::PP

NAME

PerlX::Assert::PP - Pure Perl assert keyword as a drop-in sub for PerlX::Assert

SYNOPSIS

use PerlX::Assert::PP -check;

# Basic anonymous assertion:
assert { $value > 0 };

# Named assertion:
assert "value must be positive" { $value > 0 };

# Assertions are active if -check is used or if one of the following
# environment variables is set:
#
#   PERL_STRICT
#   EXTENDED_TESTING
#   AUTHOR_TESTING
#   RELEASE_TESTING
#
# Example:
#   $ PERL_STRICT=1 perl script.pl

DESCRIPTION

PerlX::Assert::PP provides a lightweight, pure-Perl assertion mechanism inspired by PerlX::Assert. It supports the following assertion forms:

assert EXPR;
assert { BLOCK };
assert "name", EXPR;
assert "name" { BLOCK };

A named assertion includes its name in the error message on failure. Anonymous assertions are automatically deparsed, producing a compact representation of the failing code.

Assertions are enabled when either the -check import flag is used or when one of the environment variables listed above is set. This makes it easy to enable assertions in development, CI, or testing, while keeping them disabled in production.

FILTER BEHAVIOUR

The environment variable PERLX_ASSERT_PP_FILTER enables or disables a source filter for block-style assertions.

By default, PerlX::Assert::PP operates in a fast, lightweight mode: only the expression-style assertions are supported:

assert EXPR;
assert "name", EXPR;

In this mode, no source filter is loaded. This avoids the compile-time overhead associated with Filter::Simple and Text::Balanced, and is suitable for large code bases or performance-sensitive environments.

If the environment variable PERLX_ASSERT_PP_FILTER is set to a true value, the module activates its source filter. This enables the block assertion syntax:

assert { BLOCK };
assert "name" { BLOCK };

When enabled, block assertions are rewritten at compile time into:

assert "name", do { BLOCK };

Only executable code is scanned (FILTER_ONLY executable). Strings and comments are masked beforehand so that occurrences of the word assert within them are never touched, matched, or executed.

The filter relies on Text::Balanced to extract one quoted assertion name ('', "", q(...), or qq(...)) and one balanced block { ... }. Nested blocks are fully supported. Quote-like operators such as qw(...), qr(...), qx(...), s///, and m// are intentionally not treated as assertion names.

The filter is robust for normal Perl code, including nested blocks and structures. However, as with all source filters, complex quoting constructs, macro-like expansions, or heavy syntax extensions may cause unexpected behaviour. If a stable, filter-free solution is required, consider using the original XS-based PerlX::Assert by Toby Inkster.

Note: that enabling the filter introduces additional compile-time cost, because the filter inspects and rewrites the source code. For this reason, it is disabled by default.

Examples:

$ perl script.pl                            # fast mode, no block assertions
$ PERLX_ASSERT_PP_FILTER=1 perl script.pl   # block assertions supported

LIMITATIONS

The original PerlX::Assert uses Exporter::Tiny and provides a highly flexible import system. This pure-Perl implementation instead exports assert directly into the caller's namespace and performs a compile-time source rewrite.

The assertion name must be a single-quoted string, a double-quoted string, or a q(...)/qq(...) expression. Other quote-like operators (qr, qx, qw, s///, m//, etc.) are not treated as assertion names.

Assertions are implemented as normal subroutine calls. The call itself cannot be eliminated. However, if assertions are disabled, the block is not evaluated in block syntax and the overhead is minimal. In expression syntax, however, the expression is evaluated completely before it is passed to the assert subroutine.

REQUIRES

SEE ALSO

AUTHOR

J. Schneider <brickpool@cpan.org>

CONTRIBUTOR

Toby Inkster <tobyink@cpan.org>

LICENSE

Copyright (c) 2013-2014, 2026 the "AUTHOR" and "CONTRIBUTOR" listed above.

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