view release on metacpan or  search on metacpan

lib/Assert/Conditional.pm  view on Meta::CPAN

    my $signo = WTERMSIG($wstat);
    my $sigmsg = _signum_message($signo);
    _WIFCORED($wstat)           || botch "exit value $wstat indicates signal $sigmsg but no core dump";
}

sub assert_no_coredump(;$)
    :Assert( qw[process] )
{
    my($wstat) = @_ ? $_[0] : $?;
    my $cored = $wstat & 128;   # not standard; too hard to fish from real sys/wait.h
    return unless _WIFCORED($wstat);
    return unless $cored;
    my $signo  = WTERMSIG($wstat);
    my $sigmsg = _signum_message($signo);
    botch "exit value $wstat shows process died of a $sigmsg and dumped core";
}

sub assert_exited(;$)
    :Assert( qw[process] )
{
    &assert_legal_exit_status;
    my($wstat) = @_ ? $_[0] : $?;
    return if WIFEXITED($wstat);
    &assert_signalled;
    my $signo  = WTERMSIG($wstat);
    my $sigmsg = _signum_message($signo);
    my $cored  = _coredump_message($wstat);
    botch "exit value $wstat shows process did not exit but rather died of $sigmsg$cored";
}

sub assert_happy_exit(;$)
    :Assert( qw[process] )
{
    &assert_exited;
    my($wstat) = @_ ? $_[0] : $?;
    my $exit = WEXITSTATUS($wstat);
    $exit == 0                  || botch "exit status $exit is not a happy exit";
}

sub assert_sad_exit(;$)
    :Assert( qw[process] )
{
    &assert_exited;
    my($wstat) = @_ ? $_[0] : $?;
    my $exit = WEXITSTATUS($wstat);
    $exit != 0                  || botch "exit status 0 is an unexpectedly happy exit";
}

# If you actually *execute*(!) this module as though it were a perl
# script rather than merely require or compile it, it dumps out its
# export table like the pmexp tool from the pmtools distribution does.
# If moreover the ASSERT_CONDITIONAL_BUILD_POD envariable is true, then
# this actually generates pod you can use directly. This is used by the
# etc/generate-exporter-pod script from the source directory; this
# script is not installed, and is just a helper.

exit !dump_exports(@ARGV) unless his_is_require(-1);

# This can't execute at the "normal" time or else
# namespace::autoclean's call Sub::Identify freaks:
UNITCHECK { close(DATA) if defined fileno(DATA) }

1;


# This has to be __DATA__ not __END__ for the self-executing
# trick to work right.
__DATA__

=encoding utf8

=head1 NAME

Assert::Conditional - conditionally-compiled code assertions

=head1 SYNOPSIS

    # use them all unconditionally
    use Assert::Conditional qw(:all -if 1);

    # Use them based on some external conditional available
    # at compile time.
    use Assert::Conditional qw(:all)
        => -if => ( $ENV{DEBUG} && ! $ENV{NDEBUG} );

    # Use them based on some external conditional available
    # at compile time.
    use Assert::Conditional qw(:all)
        => -unless => $ENV{RUNTIME} eq "production";

    # Method that should be called in list context with two array refs
    # as arguments, and which should have both a "cross_product" and
    # a "cross_tees" method available to it.

    sub some_method {
        assert_list_context();
        assert_object_method();

        assert_argc(3);
        my($self, $left, $right) = @_;

        assert_arrayref($left);
        assert_arrayref($right);

        assert_can($self, "cross_product", "cross_tees");

        ...

        assert_happy_code { $i > $j };

        ...
    }

=head1 DESCRIPTION

C programmers have always had F<assert.h> to conditionally compile
assertions into their programs, but options available for Perl programmers
are not so convenient.

Several assertion modules related to assertions exist on CPAN, but none
works quite like this one does, probably due to differing design goals.

lib/Assert/Conditional.pm  view on Meta::CPAN

The L<Assert::Conditional::Utils> module provides some semi-standalone utility
functions.

=back

=head1 CAVEATS AND PROVISOS

This is a beta release.

=head1 BUGS AND LIMITATIONS

Under versions of Perl previous to v5.12.1, Attribute::Handlers
blows up with an internal error about a symbol going missing.

=head1 HISTORY

 0.001    6 June 2015 23:28 MDT
        - Initial alpha release

 0.002    J June 2015 22:35 MDT
        - MONGOLIAN VOWEL SEPARATOR is no longer whitespace in Unicode, so removed from test.

 0.003    Tue Jun 30 05:47:16 MDT 2015
        - Added assert_hash_keys_required and assert_hash_keys_allowed.
        - Fixed some tests.
        - Added bug report about Attribute::Handlers bug prior to 5.12.

 0.004    11 Feb 2018 11:18 MST
        - Suppress overloading in botch messages for object-related assertions (but not others).
        - Don't carp if we're throwing an exception and exceptions are trapped.
        - Support more than one word in ASSERT_CONDITIONAL (eg: "carp,always").
        - If ASSERT_CONDITIONAL contains "handlers", don't block @SIG{__{WARN,DIE}__}.
        - Don't let assert_isa die prematurely on an unblessed ref.

 0.005   Sun May 20 20:40:25 CDT 2018
       - Initial beta release.
       - Reworked the hash key checkers into a simpler set: assert_keys, assert_min_keys, assert_max_keys, assert_minmax_keys.
       - Added invocant-specific assertions: assert_{object,class}_{isa,ainta,can,cant}.
       - Added assertions for ties, overloads, and locked hashes.
       - Made assert_private_method work despite Moose wrappers.
       - Added assert_protected_method that works despite Moose wrappers and roles.
       - Improved the looks of the uncompiled code for assert_happy_code.
       - Fixed botch() to identify the most distant stack frame not the nearest for the name of the failed assertion.
       - Improved the reporting of some assertion failures.

 0.006   Mon May 21 07:45:43 CDT 2018
       - Use hash_{,un}locked not hashref_{,un}locked to support pre-5.16 perls.
       - Unhid assert_unblessed_ref swallowed up by stray pod.

 0.007   Mon May 21 19:13:58 CDT 2018
       - Add missing Hash::Util version requirement for old perls to get hashref_unlock imported.

 0.008   Tue May 22 11:51:37 CDT 2018
       - Rewrite hash_unlocked missing till 5.16 as !hash_locked
       - Add omitted etc/generate-exporter-pod to MANIFEST

 0.009   Tue Aug 21 06:29:56 MDT 2018
       - Delay slow calls to uca_sort till you really need them, credit Larry Leszczynski.

 0.010   Sun Jul 19 13:52:00 MDT 2020
       - Fix coredump in perl 5.12 by replacing UNITCHECK in Assert::Conditional::Util with normal execution at botton.
       - Make perls below 5.18 work again by setting Hash::Util prereq in Makefile.PL to 0 because it's in the core only, never cpan.
       - Only provide assert_locked and assert_unlocked if core Hash::Util v0.15 is there (starting perl v5.17).
       - Bump version req of parent class Exporter::ConditionalSubs to v1.11.1 so we don't break Devel::Cover.
       - Normalize Export sub attribute tracing so either $Exporter::Verbose=1 or env ASSERT_CONDITIONAL_DEBUG=1 work for both Assert::Conditional{,::Utils}.
       - Mentioned $Exporter::Verbose support.

=head1 AUTHOR

Tom Christiansen C<< <tchrist53147@gmail.com> >>

Thanks to Larry Leszczynski at Grant Street Group for making this module
possible.  Without it, my programs would be much slower, since before I
added his module to my old and pre-existing assertion system, the
assertions alone were taking up far too much CPU time.

=head1 LICENCE AND COPYRIGHT

Copyright (c) 2015-2018, Tom Christiansen C<< <tchrist@perl.com> >>.
All Rights Reserved.

This module is free software; you can redistribute it and/or