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.