Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
More(3)		      User Contributed Perl Documentation	       More(3)

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

VERSION
       Version 1.26

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_hashref_nonempty( $ref [,$name] )
       Asserts that $ref is defined and	is a reference to a hash with at least
       one key/value pair.

   assert_arrayref( $ref [, $name] )
   assert_listref( $ref	[,$name] )
       Asserts that $ref is defined, and is a reference	to an array, which may
       or may not be empty.

       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_arrayref_nonempty( $ref [, $name] )
       Asserts that $ref is reference to an array that has at least one
       element in it.

   assert_aoh( $ref [, $name ] )
       Verifies	that $array is an arrayref, and	that every element is a
       hashref.

       The array $array	can be an empty	arraref	and the	assertion will pass.

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

TYPE-SPECIFIC ASSERTIONS
   assert_datetime( $date )
       Asserts that $date is a DateTime	object.

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

   assert_keys_are( \%hash, \@keys [, $name ] )
       Asserts that the	keys for %hash are exactly @keys, no more and no less.

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-2020 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.

perl v5.32.1			  2020-12-26			       More(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CAVEATS | SIMPLE ASSERTIONS | NUMERIC ASSERTIONS | REFERENCE ASSERTIONS | TYPE-SPECIFIC ASSERTIONS | SET AND HASH MEMBERSHIP | UTILITY ASSERTIONS | COPYRIGHT & LICENSE | ACKNOWLEDGEMENTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Carp::Assert::More&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help