.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "More 3pm"
.TH More 3pm 2024-03-09 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Carp::Assert::More \- Convenience assertions for common situations
.SH VERSION
.IX Header "VERSION"
Version 2.4.0
.SH SYNOPSIS
.IX Header "SYNOPSIS"
A set of convenience functions for common assertions.
.PP
.Vb 1
\&    use Carp::Assert::More;
\&
\&    my $obj = My::Object;
\&    assert_isa( $obj, \*(AqMy::Object\*(Aq, \*(AqGot back a correct object\*(Aq );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Carp::Assert::More is a convenient set of assertions to make the habit
of writing assertions even easier.
.PP
Everything in here is effectively syntactic sugar.  There's no technical
difference between calling one of these functions:
.PP
.Vb 2
\&    assert_datetime( $foo );
\&    assert_isa( $foo, \*(AqDateTime\*(Aq );
.Ve
.PP
that are provided by Carp::Assert::More and calling these assertions
from Carp::Assert
.PP
.Vb 2
\&    assert( defined $foo );
\&    assert( ref($foo) eq \*(AqDateTime\*(Aq );
.Ve
.PP
My intent here is to make common assertions easy so that we as programmers
have no excuse to not use them.
.SH "SIMPLE ASSERTIONS"
.IX Header "SIMPLE ASSERTIONS"
.ie n .SS "assert_is( $string, $match [,$name] )"
.el .SS "assert_is( \f(CW$string\fP, \f(CW$match\fP [,$name] )"
.IX Subsection "assert_is( $string, $match [,$name] )"
Asserts that \fR\f(CI$string\fR\fI\fR is the same string value as \fI\fR\f(CI$match\fR\fI\fR.
.PP
\&\f(CW\*(C`undef\*(C'\fR is not converted to an empty string. If both strings are
\&\f(CW\*(C`undef\*(C'\fR, they match. If only one string is \f(CW\*(C`undef\*(C'\fR, they don't match.
.ie n .SS "assert_isnt( $string, $unmatch [,$name] )"
.el .SS "assert_isnt( \f(CW$string\fP, \f(CW$unmatch\fP [,$name] )"
.IX Subsection "assert_isnt( $string, $unmatch [,$name] )"
Asserts that \fR\f(CI$string\fR\fI\fR does NOT have the same string value as \fI\fR\f(CI$unmatch\fR\fI\fR.
.PP
\&\f(CW\*(C`undef\*(C'\fR is not converted to an empty string.
.ie n .SS "assert_cmp( $x, $op, $y [,$name] )"
.el .SS "assert_cmp( \f(CW$x\fP, \f(CW$op\fP, \f(CW$y\fP [,$name] )"
.IX Subsection "assert_cmp( $x, $op, $y [,$name] )"
Asserts that the relation \f(CW\*(C`$x $op $y\*(C'\fR is true. It lets you know why
the comparsison failed, rather than simply that it did fail, by giving
better diagnostics than a plain \f(CWassert()\fR, as well as showing the
operands in the stacktrace.
.PP
Plain \f(CWassert()\fR:
.PP
.Vb 1
\&    assert( $nitems <= 10, \*(AqTen items or fewer in the express lane\*(Aq );
\&
\&    Assertion (Ten items or fewer in the express lane) failed!
\&    Carp::Assert::assert("", "Ten items or fewer in the express lane") called at foo.pl line 12
.Ve
.PP
With \f(CWassert_cmp()\fR:
.PP
.Vb 1
\&    assert_cmp( $nitems, \*(Aq<=\*(Aq, 10, \*(AqTen items or fewer in the express lane\*(Aq );
\&
\&    Assertion (Ten items or fewer in the express lane) failed!
\&    Failed: 14 <= 10
\&    Carp::Assert::More::assert_cmp(14, "<=", 10, "Ten items or fewer in the express lane") called at foo.pl line 11
.Ve
.PP
The following operators are supported:
.IP \(bu 4
== numeric equal
.IP \(bu 4
!= numeric not equal
.IP \(bu 4
> numeric greater than
.IP \(bu 4
>= numeric greater than or equal
.IP \(bu 4
< numeric less than
.IP \(bu 4
<= numeric less than or equal
.IP \(bu 4
lt string less than
.IP \(bu 4
le string less than or equal
.IP \(bu 4
gt string less than
.IP \(bu 4
ge string less than or equal
.PP
There is no support for \f(CW\*(C`eq\*(C'\fR or \f(CW\*(C`ne\*(C'\fR because those already have
\&\f(CW\*(C`assert_is\*(C'\fR and \f(CW\*(C`assert_isnt\*(C'\fR, respectively.
.PP
If either \f(CW$x\fR or \f(CW$y\fR is undef, the assertion will fail.
.PP
If the operator is numeric, and \f(CW$x\fR or \f(CW$y\fR are not numbers, the assertion will fail.
.ie n .SS "assert_like( $string, qr/regex/ [,$name] )"
.el .SS "assert_like( \f(CW$string\fP, qr/regex/ [,$name] )"
.IX Subsection "assert_like( $string, qr/regex/ [,$name] )"
Asserts that \fR\f(CI$string\fR\fI\fR matches \fIqr/regex/\fR.
.PP
The assertion fails either the string or the regex are undef.
.ie n .SS "assert_unlike( $string, qr/regex/ [,$name] )"
.el .SS "assert_unlike( \f(CW$string\fP, qr/regex/ [,$name] )"
.IX Subsection "assert_unlike( $string, qr/regex/ [,$name] )"
Asserts that \fR\f(CI$string\fR\fI\fR matches \fIqr/regex/\fR.
.PP
The assertion fails if the regex is undef.
.ie n .SS "assert_defined( $this [, $name] )"
.el .SS "assert_defined( \f(CW$this\fP [, \f(CW$name\fP] )"
.IX Subsection "assert_defined( $this [, $name] )"
Asserts that \fR\f(CI$this\fR\fI\fR is defined.
.ie n .SS "assert_undefined( $this [, $name] )"
.el .SS "assert_undefined( \f(CW$this\fP [, \f(CW$name\fP] )"
.IX Subsection "assert_undefined( $this [, $name] )"
Asserts that \fR\f(CI$this\fR\fI\fR is not defined.
.ie n .SS "assert_nonblank( $this [, $name] )"
.el .SS "assert_nonblank( \f(CW$this\fP [, \f(CW$name\fP] )"
.IX Subsection "assert_nonblank( $this [, $name] )"
Asserts that \fR\f(CI$this\fR\fI\fR is not a reference and is not an empty string.
.SH "NUMERIC ASSERTIONS"
.IX Header "NUMERIC ASSERTIONS"
.ie n .SS "assert_numeric( $n [, $name] )"
.el .SS "assert_numeric( \f(CW$n\fP [, \f(CW$name\fP] )"
.IX Subsection "assert_numeric( $n [, $name] )"
Asserts that \f(CW$n\fR looks like a number, according to \f(CW\*(C`Scalar::Util::looks_like_number\*(C'\fR.
\&\f(CW\*(C`undef\*(C'\fR will always fail.
.ie n .SS "assert_integer( $this [, $name ] )"
.el .SS "assert_integer( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_integer( $this [, $name ] )"
Asserts that \fR\f(CI$this\fR\fI\fR is an integer, which may be zero or negative.
.PP
.Vb 4
\&    assert_integer( 0 );      # pass
\&    assert_integer( 14 );     # pass
\&    assert_integer( \-14 );    # pass
\&    assert_integer( \*(Aq14.\*(Aq );  # FAIL
.Ve
.ie n .SS "assert_nonzero( $this [, $name ] )"
.el .SS "assert_nonzero( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_nonzero( $this [, $name ] )"
Asserts that the numeric value of \fR\f(CI$this\fR\fI\fR is defined and is not zero.
.PP
.Vb 3
\&    assert_nonzero( 0 );    # FAIL
\&    assert_nonzero( \-14 );  # pass
\&    assert_nonzero( \*(Aq14.\*(Aq );  # pass
.Ve
.ie n .SS "assert_positive( $this [, $name ] )"
.el .SS "assert_positive( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_positive( $this [, $name ] )"
Asserts that \fR\f(CI$this\fR\fI\fR is defined, numeric and greater than zero.
.PP
.Vb 3
\&    assert_positive( 0 );    # FAIL
\&    assert_positive( \-14 );  # FAIL
\&    assert_positive( \*(Aq14.\*(Aq );  # pass
.Ve
.ie n .SS "assert_nonnegative( $this [, $name ] )"
.el .SS "assert_nonnegative( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_nonnegative( $this [, $name ] )"
Asserts that \fR\f(CI$this\fR\fI\fR is defined, numeric and greater than or equal
to zero.
.PP
.Vb 4
\&    assert_nonnegative( 0 );      # pass
\&    assert_nonnegative( \-14 );    # FAIL
\&    assert_nonnegative( \*(Aq14.\*(Aq );  # pass
\&    assert_nonnegative( \*(Aqdog\*(Aq );  # pass
.Ve
.ie n .SS "assert_negative( $this [, $name ] )"
.el .SS "assert_negative( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_negative( $this [, $name ] )"
Asserts that the numeric value of \fR\f(CI$this\fR\fI\fR is defined and less than zero.
.PP
.Vb 3
\&    assert_negative( 0 );       # FAIL
\&    assert_negative( \-14 );     # pass
\&    assert_negative( \*(Aq14.\*(Aq );   # FAIL
.Ve
.ie n .SS "assert_nonzero_integer( $this [, $name ] )"
.el .SS "assert_nonzero_integer( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_nonzero_integer( $this [, $name ] )"
Asserts that the numeric value of \fR\f(CI$this\fR\fI\fR is defined, an integer, and not zero.
.PP
.Vb 3
\&    assert_nonzero_integer( 0 );      # FAIL
\&    assert_nonzero_integer( \-14 );    # pass
\&    assert_nonzero_integer( \*(Aq14.\*(Aq );  # FAIL
.Ve
.ie n .SS "assert_positive_integer( $this [, $name ] )"
.el .SS "assert_positive_integer( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_positive_integer( $this [, $name ] )"
Asserts that the numeric value of \fR\f(CI$this\fR\fI\fR is defined, an integer and greater than zero.
.PP
.Vb 4
\&    assert_positive_integer( 0 );     # FAIL
\&    assert_positive_integer( \-14 );   # FAIL
\&    assert_positive_integer( \*(Aq14.\*(Aq ); # FAIL
\&    assert_positive_integer( \*(Aq14\*(Aq );  # pass
.Ve
.ie n .SS "assert_nonnegative_integer( $this [, $name ] )"
.el .SS "assert_nonnegative_integer( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_nonnegative_integer( $this [, $name ] )"
Asserts that the numeric value of \fR\f(CI$this\fR\fI\fR is defined, an integer, and not less than zero.
.PP
.Vb 3
\&    assert_nonnegative_integer( 0 );      # pass
\&    assert_nonnegative_integer( \-14 );    # FAIL
\&    assert_nonnegative_integer( \*(Aq14.\*(Aq );  # FAIL
.Ve
.ie n .SS "assert_negative_integer( $this [, $name ] )"
.el .SS "assert_negative_integer( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_negative_integer( $this [, $name ] )"
Asserts that the numeric value of \fR\f(CI$this\fR\fI\fR is defined, an integer, and less than zero.
.PP
.Vb 3
\&    assert_negative_integer( 0 );      # FAIL
\&    assert_negative_integer( \-14 );    # pass
\&    assert_negative_integer( \*(Aq14.\*(Aq );  # FAIL
.Ve
.SH "REFERENCE ASSERTIONS"
.IX Header "REFERENCE ASSERTIONS"
.ie n .SS "assert_isa( $this, $type [, $name ] )"
.el .SS "assert_isa( \f(CW$this\fP, \f(CW$type\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_isa( $this, $type [, $name ] )"
Asserts that \fR\f(CI$this\fR\fI\fR is an object of type \fI\fR\f(CI$type\fR\fI\fR.
.ie n .SS "assert_isa_in( $obj, \e@types [, $description] )"
.el .SS "assert_isa_in( \f(CW$obj\fP, \e@types [, \f(CW$description\fP] )"
.IX Subsection "assert_isa_in( $obj, @types [, $description] )"
Assert that the blessed \f(CW$obj\fR isa one of the types in \f(CW\*(C`\e@types\*(C'\fR.
.PP
.Vb 1
\&    assert_isa_in( $obj, [ \*(AqMy::Foo\*(Aq, \*(AqMy::Bar\*(Aq ], \*(AqMust pass either a Foo or Bar object\*(Aq );
.Ve
.ie n .SS "assert_empty( $this [, $name ] )"
.el .SS "assert_empty( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_empty( $this [, $name ] )"
\&\fR\f(CI$this\fR\fI\fR must be a ref to either a hash or an array.  Asserts that that
collection contains no elements.  Will assert (with its own message,
not \fI\fR\f(CI$name\fR\fI\fR) unless given a hash or array ref.   It is OK if \fI\fR\f(CI$this\fR\fI\fR has
been blessed into objecthood, but the semantics of checking an object to see
if it does not have keys (for a hashref) or returns 0 in scalar context (for
an array ref) may not be what you want.
.PP
.Vb 7
\&    assert_empty( 0 );       # FAIL
\&    assert_empty( \*(Aqfoo\*(Aq );   # FAIL
\&    assert_empty( undef );   # FAIL
\&    assert_empty( {} );      # pass
\&    assert_empty( [] );      # pass
\&    assert_empty( {foo=>1} );# FAIL
\&    assert_empty( [1,2,3] ); # FAIL
.Ve
.ie n .SS "assert_nonempty( $this [, $name ] )"
.el .SS "assert_nonempty( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_nonempty( $this [, $name ] )"
\&\fR\f(CI$this\fR\fI\fR 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 \fI\fR\f(CI$name\fR\fI\fR) unless given a hash or array ref.   It is OK if \fI\fR\f(CI$this\fR\fI\fR 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.
.PP
.Vb 7
\&    assert_nonempty( 0 );       # FAIL
\&    assert_nonempty( \*(Aqfoo\*(Aq );   # FAIL
\&    assert_nonempty( undef );   # FAIL
\&    assert_nonempty( {} );      # FAIL
\&    assert_nonempty( [] );      # FAIL
\&    assert_nonempty( {foo=>1} );# pass
\&    assert_nonempty( [1,2,3] ); # pass
.Ve
.ie n .SS "assert_nonref( $this [, $name ] )"
.el .SS "assert_nonref( \f(CW$this\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_nonref( $this [, $name ] )"
Asserts that \fR\f(CI$this\fR\fI\fR is not undef and not a reference.
.ie n .SS "assert_hashref( $ref [,$name] )"
.el .SS "assert_hashref( \f(CW$ref\fP [,$name] )"
.IX Subsection "assert_hashref( $ref [,$name] )"
Asserts that \fR\f(CI$ref\fR\fI\fR is defined, and is a reference to a (possibly empty) hash.
.PP
\&\fBNB:\fR This method returns \fIfalse\fR for objects, even those whose underlying
data is a hashref. This is as it should be, under the assumptions that:
.IP (a) 4
.IX Item "(a)"
you shouldn't rely on the underlying data structure of a particular class, and
.IP (b) 4
.IX Item "(b)"
you should use \f(CW\*(C`assert_isa\*(C'\fR instead.
.ie n .SS "assert_hashref_nonempty( $ref [,$name] )"
.el .SS "assert_hashref_nonempty( \f(CW$ref\fP [,$name] )"
.IX Subsection "assert_hashref_nonempty( $ref [,$name] )"
Asserts that \fR\f(CI$ref\fR\fI\fR is defined and is a reference to a hash with at
least one key/value pair.
.ie n .SS "assert_arrayref( $ref [, $name] )"
.el .SS "assert_arrayref( \f(CW$ref\fP [, \f(CW$name\fP] )"
.IX Subsection "assert_arrayref( $ref [, $name] )"
.ie n .SS "assert_listref( $ref [,$name] )"
.el .SS "assert_listref( \f(CW$ref\fP [,$name] )"
.IX Subsection "assert_listref( $ref [,$name] )"
Asserts that \fR\f(CI$ref\fR\fI\fR is defined, and is a reference to an array, which
may or may not be empty.
.PP
\&\fBNB:\fR The same caveat about objects whose underlying structure is a
hash (see \f(CW\*(C`assert_hashref\*(C'\fR) applies here; this method returns false
even for objects whose underlying structure is an array.
.PP
\&\f(CW\*(C`assert_listref\*(C'\fR is an alias for \f(CW\*(C`assert_arrayref\*(C'\fR and may go away in
the future.  Use \f(CW\*(C`assert_arrayref\*(C'\fR instead.
.ie n .SS "assert_arrayref_nonempty( $ref [, $name] )"
.el .SS "assert_arrayref_nonempty( \f(CW$ref\fP [, \f(CW$name\fP] )"
.IX Subsection "assert_arrayref_nonempty( $ref [, $name] )"
Asserts that \fR\f(CI$ref\fR\fI\fR is reference to an array that has at least one element in it.
.ie n .SS "assert_arrayref_of( $ref, $type [, $name] )"
.el .SS "assert_arrayref_of( \f(CW$ref\fP, \f(CW$type\fP [, \f(CW$name\fP] )"
.IX Subsection "assert_arrayref_of( $ref, $type [, $name] )"
Asserts that \fR\f(CI$ref\fR\fI\fR is reference to an array that has at least one
element in it, and every one of those elements is of type \fI\fR\f(CI$type\fR\fI\fR.
.PP
For example:
.PP
.Vb 2
\&    my @users = get_users();
\&    assert_arrayref_of( \e@users, \*(AqMy::User\*(Aq );
.Ve
.ie n .SS "assert_arrayref_all( $aref, $sub [, $name] )"
.el .SS "assert_arrayref_all( \f(CW$aref\fP, \f(CW$sub\fP [, \f(CW$name\fP] )"
.IX Subsection "assert_arrayref_all( $aref, $sub [, $name] )"
Asserts that \fR\f(CI$aref\fR\fI\fR is reference to an array that has at least one
element in it. Each element of the array is passed to subroutine \fI\fR\f(CI$sub\fR\fI\fR
which is assumed to be an assertion.
.PP
For example:
.PP
.Vb 2
\&    my $aref_of_counts = get_counts();
\&    assert_arrayref_all( $aref, \e&assert_positive_integer, \*(AqCounts are positive\*(Aq );
.Ve
.PP
Whatever is passed as \fR\f(CI$name\fR\fI\fR, a string saying "Element #N" will be
appended, where N is the zero-based index of the array.
.ie n .SS "assert_aoh( $ref [, $name ] )"
.el .SS "assert_aoh( \f(CW$ref\fP [, \f(CW$name\fP ] )"
.IX Subsection "assert_aoh( $ref [, $name ] )"
Verifies that \f(CW$array\fR is an arrayref, and that every element is a hashref.
.PP
The array \f(CW$array\fR can be an empty arraref and the assertion will pass.
.ie n .SS "assert_coderef( $ref [,$name] )"
.el .SS "assert_coderef( \f(CW$ref\fP [,$name] )"
.IX Subsection "assert_coderef( $ref [,$name] )"
Asserts that \fR\f(CI$ref\fR\fI\fR is defined, and is a reference to a closure.
.SH "TYPE-SPECIFIC ASSERTIONS"
.IX Header "TYPE-SPECIFIC ASSERTIONS"
.ie n .SS "assert_datetime( $date )"
.el .SS "assert_datetime( \f(CW$date\fP )"
.IX Subsection "assert_datetime( $date )"
Asserts that \f(CW$date\fR is a DateTime object.
.SH "SET AND HASH MEMBERSHIP"
.IX Header "SET AND HASH MEMBERSHIP"
.ie n .SS "assert_in( $string, \e@inlist [,$name] );"
.el .SS "assert_in( \f(CW$string\fP, \e@inlist [,$name] );"
.IX Subsection "assert_in( $string, @inlist [,$name] );"
Asserts that \fR\f(CI$string\fR\fI\fR matches one of the elements of \fI\e@inlist\fR.
\&\fI\fR\f(CI$string\fR\fI\fR may be undef.
.PP
\&\fI\e@inlist\fR must be an array reference of non-ref strings.  If any
element is a reference, the assertion fails.
.ie n .SS "assert_exists( \e%hash, $key [,$name] )"
.el .SS "assert_exists( \e%hash, \f(CW$key\fP [,$name] )"
.IX Subsection "assert_exists( %hash, $key [,$name] )"
.SS "assert_exists( \e%hash, \e@keylist [,$name] )"
.IX Subsection "assert_exists( %hash, @keylist [,$name] )"
Asserts that \fR\f(CI%hash\fR\fI\fR is indeed a hash, and that \fI\fR\f(CI$key\fR\fI\fR exists in
\&\fI\fR\f(CI%hash\fR\fI\fR, or that all of the keys in \fI\fR\f(CI@keylist\fR\fI\fR exist in \fI\fR\f(CI%hash\fR\fI\fR.
.PP
.Vb 1
\&    assert_exists( \e%custinfo, \*(Aqname\*(Aq, \*(AqCustomer has a name field\*(Aq );
\&
\&    assert_exists( \e%custinfo, [qw( name addr phone )],
\&                            \*(AqCustomer has name, address and phone\*(Aq );
.Ve
.ie n .SS "assert_lacks( \e%hash, $key [,$name] )"
.el .SS "assert_lacks( \e%hash, \f(CW$key\fP [,$name] )"
.IX Subsection "assert_lacks( %hash, $key [,$name] )"
.SS "assert_lacks( \e%hash, \e@keylist [,$name] )"
.IX Subsection "assert_lacks( %hash, @keylist [,$name] )"
Asserts that \fR\f(CI%hash\fR\fI\fR is indeed a hash, and that \fI\fR\f(CI$key\fR\fI\fR does NOT exist
in \fI\fR\f(CI%hash\fR\fI\fR, or that none of the keys in \fI\fR\f(CI@keylist\fR\fI\fR exist in \fI\fR\f(CI%hash\fR\fI\fR.
The list \f(CW@keylist\fR cannot be empty.
.PP
.Vb 1
\&    assert_lacks( \e%users, \*(Aqroot\*(Aq, \*(AqRoot is not in the user table\*(Aq );
\&
\&    assert_lacks( \e%users, [qw( root admin nobody )], \*(AqNo bad usernames found\*(Aq );
.Ve
.ie n .SS "assert_all_keys_in( \e%hash, \e@names [, $name ] )"
.el .SS "assert_all_keys_in( \e%hash, \e@names [, \f(CW$name\fP ] )"
.IX Subsection "assert_all_keys_in( %hash, @names [, $name ] )"
Asserts that each key in \f(CW%hash\fR is in the list of \f(CW@names\fR.
.PP
This is used to ensure that there are no extra keys in a given hash.
.PP
.Vb 1
\&    assert_all_keys_in( $obj, [qw( height width depth )], \*(Aq$obj can only contain height, width and depth keys\*(Aq );
.Ve
.PP
You can pass an empty list of \f(CW@names\fR.
.ie n .SS "assert_keys_are( \e%hash, \e@keys [, $name ] )"
.el .SS "assert_keys_are( \e%hash, \e@keys [, \f(CW$name\fP ] )"
.IX Subsection "assert_keys_are( %hash, @keys [, $name ] )"
Asserts that the keys for \f(CW%hash\fR are exactly \f(CW@keys\fR, no more and no less.
.SH "CONTEXT ASSERTIONS"
.IX Header "CONTEXT ASSERTIONS"
.SS "assert_context_nonvoid( [$name] )"
.IX Subsection "assert_context_nonvoid( [$name] )"
Verifies that the function currently being executed has not been called
in void context.  This is to ensure the calling function is not ignoring
the return value of the executing function.
.PP
Given this function:
.PP
.Vb 2
\&    sub something {
\&        ...
\&
\&        assert_context_scalar();
\&
\&        return $important_value;
\&    }
.Ve
.PP
These calls to \f(CW\*(C`something\*(C'\fR will pass:
.PP
.Vb 2
\&    my $val = something();
\&    my @things = something();
.Ve
.PP
but this will fail:
.PP
.Vb 1
\&    something();
.Ve
.PP
If the \f(CW$name\fR argument is not passed, a default message of "<funcname>
must not be called in void context" is provided.
.SS "assert_context_scalar( [$name] )"
.IX Subsection "assert_context_scalar( [$name] )"
Verifies that the function currently being executed has been called in
scalar context.  This is to ensure the calling function is not ignoring
the return value of the executing function.
.PP
Given this function:
.PP
.Vb 2
\&    sub something {
\&        ...
\&
\&        assert_context_scalar();
\&
\&        return $important_value;
\&    }
.Ve
.PP
This call to \f(CW\*(C`something\*(C'\fR will pass:
.PP
.Vb 1
\&    my $val = something();
.Ve
.PP
but these will fail:
.PP
.Vb 2
\&    something();
\&    my @things = something();
.Ve
.PP
If the \f(CW$name\fR argument is not passed, a default message of "<funcname>
must be called in scalar context" is provided.
.SH "UTILITY ASSERTIONS"
.IX Header "UTILITY ASSERTIONS"
.SS "assert_fail( [$name] )"
.IX Subsection "assert_fail( [$name] )"
Assertion that always fails.  \f(CWassert_fail($msg)\fR is exactly the same
as calling \f(CW\*(C`assert(0,$msg)\*(C'\fR, but it eliminates that case where you
accidentally use \f(CWassert($msg)\fR, which of course never fires.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2005\-2023 Andy Lester
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the Artistic License version 2.0.
.SH ACKNOWLEDGEMENTS
.IX Header "ACKNOWLEDGEMENTS"
Thanks to
Eric A. Zarko,
Bob Diss,
Pete Krawczyk,
David Storrs,
Dan Friedman,
Allard Hoeve,
Thomas L. Shinnick,
and Leland Johnson
for code and fixes.