Andy Lester > Carp-Assert-More > Carp::Assert::More

Download:
Carp-Assert-More-1.14.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.14   Source  

NAME ^

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

VERSION ^

Version 1.14

SYNOPSIS ^

A set of convenience functions for common assertions.

    use Carp::Assert::More;

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

DESCRIPTION ^

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.

CAVEATS ^

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.

SIMPLE ASSERTIONS ^

assert_is( $string, $match [,$name] )

Asserts that $string matches $match.

assert_isnt( $string, $unmatch [,$name] )

Asserts that $string does NOT match $unmatch.

assert_like( $string, qr/regex/ [,$name] )

Asserts that $string matches qr/regex/.

The assertion fails either the string or the regex are undef.

assert_unlike( $string, qr/regex/ [,$name] )

Asserts that $string matches qr/regex/.

The assertion fails if the regex is undef.

assert_defined( $this [, $name] )

Asserts that $this is defined.

assert_undefined( $this [, $name] )

Asserts that $this is not defined.

assert_nonblank( $this [, $name] )

Asserts that $this is not blank and not a reference.

NUMERIC ASSERTIONS ^

assert_integer( $this [, $name ] )

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_integer( '14.' );  # FAIL

assert_nonzero( $this [, $name ] )

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

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

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

assert_positive( $this [, $name ] )

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( $this [, $name ] )

Asserts that the numeric value of $this is greater than or equal to zero. Since non-numeric strings evaluate to zero, this means that any non-numeric string will pass.

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

assert_negative( $this [, $name ] )

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

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

assert_nonzero_integer( $this [, $name ] )

Asserts that the numeric value of $this is not zero, and that $this is an integer.

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

assert_positive_integer( $this [, $name ] )

Asserts that the numeric value of $this is greater than zero, and that $this is an integer.

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

assert_nonnegative_integer( $this [, $name ] )

Asserts that the numeric value of $this is not less than zero, and that $this is an integer.

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

assert_negative_integer( $this [, $name ] )

Asserts that the numeric value of $this is less than zero, and that $this is an integer.

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

REFERENCE ASSERTIONS ^

assert_isa( $this, $type [, $name ] )

Asserts that $this is an object of type $type.

assert_nonempty( $this [, $name ] )

$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

assert_nonref( $this [, $name ] )

Asserts that $this is not undef and not a reference.

assert_hashref( $ref [,$name] )

Asserts that $ref is defined, and is a reference to a (possibly empty) hash.

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 assert_isa instead.

assert_listref( $ref [,$name] )

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 assert_hashref) applies here; this method returns false even for objects whose underlying structure is an array.

SET AND HASH MEMBERSHIP ^

assert_in( $string, \@inlist [,$name] );

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

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

assert_exists( \%hash, $key [,$name] )

assert_exists( \%hash, \@keylist [,$name] )

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' );

assert_lacks( \%hash, $key [,$name] )

assert_lacks( \%hash, \@keylist [,$name] )

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' );

UTILITY ASSERTIONS ^

assert_fail( [$name] )

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

COPYRIGHT & LICENSE ^

Copyright 2005-2012 Andy Lester.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

ACKNOWLEDGEMENTS ^

Thanks to Bob Diss, Pete Krawczyk, David Storrs, Dan Friedman, Allard Hoeve, Thomas L. Shinnick, and Leland Johnson for code and fixes.

syntax highlighting: