Provided by: libcarp-assert-more-perl_1.16-1_all bug

NAME

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

VERSION

       Version 1.16

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_numeric( $n [, $name] )
       Asserts that $n looks like a number, according to "Scalar::Util::looks_like_number".

   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 );    # pass
           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_isa_in( $obj, \@types [, $description] )
       Assert that the blessed $obj isa one of the types in "\@types".

           assert_isa_in( $obj, [ 'My::Foo', 'My::Bar' ], 'Must pass either a Foo or Bar object' );

   assert_empty( $this [, $name ] )
       $this 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 $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 does not have keys (for a hashref) or returns 0 in scalar context
       (for an array ref) may not be what you want.

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

   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_arrayref( $ref [, $name] )
   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.

       "assert_listref" is an alias for "assert_arrayref" and may go away in the future.  Use
       "assert_arrayref" instead.

   assert_coderef( $ref [,$name] )
       Asserts that $ref is defined, and is a reference to a closure.

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

   assert_all_keys_in( \%hash, \@names [, $name ] )
       Asserts that each key in %hash is in the list of @names.

       This is used to ensure that there are no extra keys in a given hash.

           assert_all_keys_in( $obj, [qw( height width depth )], '$obj can only contain height, width and depth keys' );

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-2017 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 Eric A. Zarko, Bob Diss, Pete Krawczyk, David Storrs, Dan Friedman, Allard
       Hoeve, Thomas L. Shinnick, and Leland Johnson for code and fixes.