1More(3)               User Contributed Perl Documentation              More(3)
2
3
4

NAME

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

VERSION

9       Version 1.20
10

SYNOPSIS

12       A set of convenience functions for common assertions.
13
14           use Carp::Assert::More;
15
16           my $obj = My::Object;
17           assert_isa( $obj, 'My::Object', 'Got back a correct object' );
18

DESCRIPTION

20       Carp::Assert::More is a set of wrappers around the Carp::Assert
21       functions to make the habit of writing assertions even easier.
22
23       Everything in here is effectively syntactic sugar.  There's no
24       technical reason to use
25
26           assert_isa( $foo, 'HTML::Lint' );
27
28       instead of
29
30           assert( defined $foo );
31           assert( ref($foo) eq 'HTML::Lint' );
32
33       other than readability and simplicity of the code.
34
35       My intent here is to make common assertions easy so that we as
36       programmers have no excuse to not use them.
37

CAVEATS

39       I haven't specifically done anything to make Carp::Assert::More be
40       backwards compatible with anything besides Perl 5.6.1, much less back
41       to 5.004.  Perhaps someone with better testing resources in that area
42       can help me out here.
43

SIMPLE ASSERTIONS

45   assert_is( $string, $match [,$name] )
46       Asserts that $string matches $match.
47
48   assert_isnt( $string, $unmatch [,$name] )
49       Asserts that $string does NOT match $unmatch.
50
51   assert_like( $string, qr/regex/ [,$name] )
52       Asserts that $string matches qr/regex/.
53
54       The assertion fails either the string or the regex are undef.
55
56   assert_unlike( $string, qr/regex/ [,$name] )
57       Asserts that $string matches qr/regex/.
58
59       The assertion fails if the regex is undef.
60
61   assert_defined( $this [, $name] )
62       Asserts that $this is defined.
63
64   assert_undefined( $this [, $name] )
65       Asserts that $this is not defined.
66
67   assert_nonblank( $this [, $name] )
68       Asserts that $this is not blank and not a reference.
69

NUMERIC ASSERTIONS

71   assert_numeric( $n [, $name] )
72       Asserts that $n looks like a number, according to
73       "Scalar::Util::looks_like_number".
74
75   assert_integer( $this [, $name ] )
76       Asserts that $this is an integer, which may be zero or negative.
77
78           assert_integer( 0 );      # pass
79           assert_integer( 14 );     # pass
80           assert_integer( -14 );    # pass
81           assert_integer( '14.' );  # FAIL
82
83   assert_nonzero( $this [, $name ] )
84       Asserts that the numeric value of $this is not zero.
85
86           assert_nonzero( 0 );    # FAIL
87           assert_nonzero( -14 );  # pass
88           assert_nonzero( '14.' );  # pass
89
90       Asserts that the numeric value of $this is not zero.
91
92   assert_positive( $this [, $name ] )
93       Asserts that the numeric value of $this is greater than zero.
94
95           assert_positive( 0 );    # FAIL
96           assert_positive( -14 );  # FAIL
97           assert_positive( '14.' );  # pass
98
99   assert_nonnegative( $this [, $name ] )
100       Asserts that the numeric value of $this is greater than or equal to
101       zero.  Since non-numeric strings evaluate to zero, this means that any
102       non-numeric string will pass.
103
104           assert_nonnegative( 0 );      # pass
105           assert_nonnegative( -14 );    # FAIL
106           assert_nonnegative( '14.' );  # pass
107           assert_nonnegative( 'dog' );  # pass
108
109   assert_negative( $this [, $name ] )
110       Asserts that the numeric value of $this is less than zero.
111
112           assert_negative( 0 );       # FAIL
113           assert_negative( -14 );     # pass
114           assert_negative( '14.' );   # FAIL
115
116   assert_nonzero_integer( $this [, $name ] )
117       Asserts that the numeric value of $this is not zero, and that $this is
118       an integer.
119
120           assert_nonzero_integer( 0 );      # FAIL
121           assert_nonzero_integer( -14 );    # pass
122           assert_nonzero_integer( '14.' );  # FAIL
123
124   assert_positive_integer( $this [, $name ] )
125       Asserts that the numeric value of $this is greater than zero, and that
126       $this is an integer.
127
128           assert_positive_integer( 0 );     # FAIL
129           assert_positive_integer( -14 );   # FAIL
130           assert_positive_integer( '14.' ); # FAIL
131           assert_positive_integer( '14' );  # pass
132
133   assert_nonnegative_integer( $this [, $name ] )
134       Asserts that the numeric value of $this is not less than zero, and that
135       $this is an integer.
136
137           assert_nonnegative_integer( 0 );      # pass
138           assert_nonnegative_integer( -14 );    # pass
139           assert_nonnegative_integer( '14.' );  # FAIL
140
141   assert_negative_integer( $this [, $name ] )
142       Asserts that the numeric value of $this is less than zero, and that
143       $this is an integer.
144
145           assert_negative_integer( 0 );      # FAIL
146           assert_negative_integer( -14 );    # pass
147           assert_negative_integer( '14.' );  # FAIL
148

REFERENCE ASSERTIONS

150   assert_isa( $this, $type [, $name ] )
151       Asserts that $this is an object of type $type.
152
153   assert_isa_in( $obj, \@types [, $description] )
154       Assert that the blessed $obj isa one of the types in "\@types".
155
156           assert_isa_in( $obj, [ 'My::Foo', 'My::Bar' ], 'Must pass either a Foo or Bar object' );
157
158   assert_empty( $this [, $name ] )
159       $this must be a ref to either a hash or an array.  Asserts that that
160       collection contains no elements.  Will assert (with its own message,
161       not $name) unless given a hash or array ref.   It is OK if $this has
162       been blessed into objecthood, but the semantics of checking an object
163       to see if it does not have keys (for a hashref) or returns 0 in scalar
164       context (for an array ref) may not be what you want.
165
166           assert_empty( 0 );       # FAIL
167           assert_empty( 'foo' );   # FAIL
168           assert_empty( undef );   # FAIL
169           assert_empty( {} );      # pass
170           assert_empty( [] );      # pass
171           assert_empty( {foo=>1} );# FAIL
172           assert_empty( [1,2,3] ); # FAIL
173
174   assert_nonempty( $this [, $name ] )
175       $this must be a ref to either a hash or an array.  Asserts that that
176       collection contains at least 1 element.  Will assert (with its own
177       message, not $name) unless given a hash or array ref.   It is OK if
178       $this has been blessed into objecthood, but the semantics of checking
179       an object to see if it has keys (for a hashref) or returns >0 in scalar
180       context (for an array ref) may not be what you want.
181
182           assert_nonempty( 0 );       # FAIL
183           assert_nonempty( 'foo' );   # FAIL
184           assert_nonempty( undef );   # FAIL
185           assert_nonempty( {} );      # FAIL
186           assert_nonempty( [] );      # FAIL
187           assert_nonempty( {foo=>1} );# pass
188           assert_nonempty( [1,2,3] ); # pass
189
190   assert_nonref( $this [, $name ] )
191       Asserts that $this is not undef and not a reference.
192
193   assert_hashref( $ref [,$name] )
194       Asserts that $ref is defined, and is a reference to a (possibly empty)
195       hash.
196
197       NB: This method returns false for objects, even those whose underlying
198       data is a hashref. This is as it should be, under the assumptions that:
199
200       (a) you shouldn't rely on the underlying data structure of a particular
201           class, and
202
203       (b) you should use "assert_isa" instead.
204
205   assert_arrayref( $ref [, $name] )
206   assert_listref( $ref [,$name] )
207       Asserts that $ref is defined, and is a reference to a (possibly empty)
208       list.
209
210       NB: The same caveat about objects whose underlying structure is a hash
211       (see "assert_hashref") applies here; this method returns false even for
212       objects whose underlying structure is an array.
213
214       "assert_listref" is an alias for "assert_arrayref" and may go away in
215       the future.  Use "assert_arrayref" instead.
216
217   assert_aoh( $ref [, $name ] )
218       Verifies that $array is an arrayref, and that every element is a
219       hashref.
220
221       The array $array can be an empty arraref and the assertion will pass.
222
223   assert_coderef( $ref [,$name] )
224       Asserts that $ref is defined, and is a reference to a closure.
225

TYPE-SPECIFIC ASSERTIONS

227   assert_datetime( $date )
228       Asserts that $date is a DateTime object.
229

SET AND HASH MEMBERSHIP

231   assert_in( $string, \@inlist [,$name] );
232       Asserts that $string is defined and matches one of the elements of
233       \@inlist.
234
235       \@inlist must be an array reference of defined strings.
236
237   assert_exists( \%hash, $key [,$name] )
238   assert_exists( \%hash, \@keylist [,$name] )
239       Asserts that %hash is indeed a hash, and that $key exists in %hash, or
240       that all of the keys in @keylist exist in %hash.
241
242           assert_exists( \%custinfo, 'name', 'Customer has a name field' );
243
244           assert_exists( \%custinfo, [qw( name addr phone )],
245                                   'Customer has name, address and phone' );
246
247   assert_lacks( \%hash, $key [,$name] )
248   assert_lacks( \%hash, \@keylist [,$name] )
249       Asserts that %hash is indeed a hash, and that $key does NOT exist in
250       %hash, or that none of the keys in @keylist exist in %hash.
251
252           assert_lacks( \%users, 'root', 'Root is not in the user table' );
253
254           assert_lacks( \%users, [qw( root admin nobody )], 'No bad usernames found' );
255
256   assert_all_keys_in( \%hash, \@names [, $name ] )
257       Asserts that each key in %hash is in the list of @names.
258
259       This is used to ensure that there are no extra keys in a given hash.
260
261           assert_all_keys_in( $obj, [qw( height width depth )], '$obj can only contain height, width and depth keys' );
262

UTILITY ASSERTIONS

264   assert_fail( [$name] )
265       Assertion that always fails.  "assert_fail($msg)" is exactly the same
266       as calling "assert(0,$msg)", but it eliminates that case where you
267       accidentally use "assert($msg)", which of course never fires.
268
270       Copyright 2005-2019 Andy Lester.
271
272       This program is free software; you can redistribute it and/or modify it
273       under the terms of the Artistic License version 2.0.
274

ACKNOWLEDGEMENTS

276       Thanks to Eric A. Zarko, Bob Diss, Pete Krawczyk, David Storrs, Dan
277       Friedman, Allard Hoeve, Thomas L. Shinnick, and Leland Johnson for code
278       and fixes.
279
280
281
282perl v5.32.0                      2020-07-28                           More(3)
Impressum