.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "More 3pm"
.TH More 3pm "2017-11-05" "perl v5.26.1" "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 wrappers around Carp::Assert
.SH "VERSION"
.IX Header "VERSION"
Version 1.16
.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 set of wrappers around the Carp::Assert functions
to make the habit of writing assertions even easier.
.PP
Everything in here is effectively syntactic sugar.  There's no technical
reason to use
.PP
.Vb 1
\&    assert_isa( $foo, \*(AqHTML::Lint\*(Aq );
.Ve
.PP
instead of
.PP
.Vb 2
\&    assert( defined $foo );
\&    assert( ref($foo) eq \*(AqHTML::Lint\*(Aq );
.Ve
.PP
other than readability and simplicity of the code.
.PP
My intent here is to make common assertions easy so that we as programmers
have no excuse to not use them.
.SH "CAVEATS"
.IX Header "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.
.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 \fI\f(CI$string\fI\fR matches \fI\f(CI$match\fI\fR.
.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 \fI\f(CI$string\fI\fR does \s-1NOT\s0 match \fI\f(CI$unmatch\fI\fR.
.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 \fI\f(CI$string\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 \fI\f(CI$string\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 \fI\f(CI$this\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 \fI\f(CI$this\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 \fI\f(CI$this\fI\fR is not blank and not a reference.
.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.
.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 \fI\f(CI$this\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 \fI\f(CI$this\fI\fR is not zero.
.PP
.Vb 3
\&    assert_nonzero( 0 );    # FAIL
\&    assert_nonzero( \-14 );  # pass
\&    assert_nonzero( \*(Aq14.\*(Aq );  # pass
.Ve
.PP
Asserts that the numeric value of \fI\f(CI$this\fI\fR is not zero.
.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 the numeric value of \fI\f(CI$this\fI\fR is 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 the numeric value of \fI\f(CI$this\fI\fR is greater than or equal
to zero.  Since non-numeric strings evaluate to zero, this means that
any non-numeric string will pass.
.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 \fI\f(CI$this\fI\fR is 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 \fI\f(CI$this\fI\fR is not zero, and that \fI\f(CI$this\fI\fR
is an integer.
.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 \fI\f(CI$this\fI\fR is greater than zero, and
that \fI\f(CI$this\fI\fR is an integer.
.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 \fI\f(CI$this\fI\fR is not less than zero, and
that \fI\f(CI$this\fI\fR is an integer.
.PP
.Vb 3
\&    assert_nonnegative_integer( 0 );      # pass
\&    assert_nonnegative_integer( \-14 );    # pass
\&    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 \fI\f(CI$this\fI\fR is less than zero, and that
\&\fI\f(CI$this\fI\fR is an integer.
.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 \fI\f(CI$this\fI\fR is an object of type \fI\f(CI$type\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 ] )"
\&\fI\f(CI$this\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\f(CI$name\fI\fR) unless given a hash or array ref.   It is \s-1OK\s0 if \fI\f(CI$this\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 ] )"
\&\fI\f(CI$this\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\f(CI$name\fI\fR) unless given a hash or array ref.   It is \s-1OK\s0 if \fI\f(CI$this\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 \fI\f(CI$this\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 \fI\f(CI$ref\fI\fR is defined, and is a reference to a (possibly empty) hash.
.PP
\&\fB\s-1NB:\s0\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_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 \fI\f(CI$ref\fI\fR is defined, and is a reference to a (possibly empty) list.
.PP
\&\fB\s-1NB:\s0\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_coderef( $ref [,$name] )"
.el .SS "assert_coderef( \f(CW$ref\fP [,$name] )"
.IX Subsection "assert_coderef( $ref [,$name] )"
Asserts that \fI\f(CI$ref\fI\fR is defined, and is a reference to a closure.
.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 \fI\f(CI$string\fI\fR is defined and matches one of the elements
of \fI\e@inlist\fR.
.PP
\&\fI\e@inlist\fR must be an array reference of defined strings.
.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 \fI\f(CI%hash\fI\fR is indeed a hash, and that \fI\f(CI$key\fI\fR exists in
\&\fI\f(CI%hash\fI\fR, or that all of the keys in \fI\f(CI@keylist\fI\fR exist in \fI\f(CI%hash\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 \fI\f(CI%hash\fI\fR is indeed a hash, and that \fI\f(CI$key\fI\fR does \s-1NOT\s0 exist
in \fI\f(CI%hash\fI\fR, or that none of the keys in \fI\f(CI@keylist\fI\fR exist in \fI\f(CI%hash\fI\fR.
.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
.SH "UTILITY ASSERTIONS"
.IX Header "UTILITY ASSERTIONS"
.SS "assert_fail( [$name] )"
.IX Subsection "assert_fail( [$name] )"
Assertion that always fails.  \f(CW\*(C`assert_fail($msg)\*(C'\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(CW\*(C`assert($msg)\*(C'\fR, which of course never fires.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2005\-2017 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.