Carp::Assert::More - convenience wrappers around Carp::Assert

Version 1.12

    use Carp::Assert::More;

    my $obj = My::Object;
    assert_isa( $obj, 'My::Object', 'Got back a correct object' );

Carp::Assert::More is a set of wrappers around the Carp::Assert functions to make the habit of writing assertions even easier.

Everything in here is effectively syntactic sugar. There's no technical reason to use

    assert_isa( $foo, 'HTML::Lint' );

instead of

    assert( defined $foo );
    assert( ref($foo) eq 'HTML::Lint' );

other than readability and simplicity of the code.

My intent here is to make common assertions easy so that we as programmers have no excuse to not use them.

I haven't specifically done anything to make Carp::Assert::More be backwards compatible with anything besides Perl 5.6.1, much less back to 5.004. Perhaps someone with better testing resources in that area can help me out here.

Asserts that $string matches $match. Asserts that $string does NOT match $unmatch. Asserts that $string matches qr/regex/. Asserts that $this is defined. Asserts that $this is not blank and not a reference.

Asserts that $this is an integer, which may be zero or negative.

    assert_integer( 0 );    # pass
    assert_integer( -14 );  # pass
    assert_integer( '14.' );  # FAIL

    assert_nonzero( 0 );    # FAIL
    assert_nonzero( -14 );  # pass
    assert_nonzero( '14.' );  # pass

Asserts that the numeric value of $this is not zero. Asserts that the numeric value of $this is greater than zero.

    assert_positive( 0 );    # FAIL
    assert_positive( -14 );  # FAIL
    assert_positive( '14.' );  # pass

    assert_nonnegative( 0 );    # pass
    assert_nonnegative( -14 );  # FAIL
    assert_nonnegative( '14.' );  # pass
    assert_nonnegative( 'dog' );  # pass

    assert_negative( 0 );       # FAIL
    assert_negative( -14 );     # pass
    assert_negative( '14.' );   # FAIL

    assert_nonzero_integer( 0 );    # FAIL
    assert_nonzero_integer( -14 );  # pass
    assert_nonzero_integer( '14.' );  # FAIL

    assert_positive_integer( 0 );     # FAIL
    assert_positive_integer( -14 );   # FAIL
    assert_positive_integer( '14.' ); # FAIL
    assert_positive_integer( '14' );  # pass

    assert_nonnegative_integer( 0 );    # pass
    assert_nonnegative_integer( -14 );  # pass
    assert_nonnegative_integer( '14.' );  # FAIL

    assert_negative_integer( 0 );    # FAIL
    assert_negative_integer( -14 );  # pass
    assert_negative_integer( '14.' );  # FAIL

Asserts that $this is an object of type $type. $this must be a ref to either a hash or an array. Asserts that that collection contains at least 1 element. Will assert (with its own message, not $name) unless given a hash or array ref. It is OK if $this has been blessed into objecthood, but the semantics of checking an object to see if it has keys (for a hashref) or returns >0 in scalar context (for an array ref) may not be what you want.

    assert_nonempty( 0 );       # FAIL
    assert_nonempty( 'foo' );   # FAIL
    assert_nonempty( undef );   # FAIL
    assert_nonempty( {} );      # FAIL
    assert_nonempty( [] );      # FAIL
    assert_nonempty( {foo=>1} );# pass
    assert_nonempty( [1,2,3] ); # pass

NB: This method returns false for objects, even those whose underlying data is a hashref. This is as it should be, under the assumptions that:

(a)

you shouldn't rely on the underlying data structure of a particular class, and

(b)

you should use CWassert_isa instead. Asserts that $ref is defined, and is a reference to a (possibly empty) list.

NB: The same caveat about objects whose underlying structure is a hash (see CWassert_hashref) applies here; this method returns false even for objects whose underlying structure is an array.

Asserts that $string is defined and matches one of the elements of \@inlist.

\@inlist must be an array reference of defined strings.

Asserts that %hash is indeed a hash, and that $key exists in %hash, or that all of the keys in @keylist exist in %hash.

    assert_exists( \%custinfo, 'name', 'Customer has a name field' );

    assert_exists( \%custinfo, [qw( name addr phone )],
                            'Customer has name, address and phone' );

Asserts that %hash is indeed a hash, and that $key does NOT exist in %hash, or that none of the keys in @keylist exist in %hash.

    assert_lacks( \%users, 'root', 'Root is not in the user table' );

    assert_lacks( \%users, [qw( root admin nobody )], 'No bad usernames found' );

Assertion that always fails. CWassert_fail($msg) is exactly the same as calling CWassert(0,$msg), but it eliminates that case where you accidentally use CWassert($msg), which of course never fires.

Copyright (c) 2005 Andy Lester. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Thanks to Bob Diss, Pete Krawczyk, David Storrs, Dan Friedman, and Allard Hoeve for code and fixes.