README.md
1# Carp::Assert::More
2
3[![Build Status](https://github.com/petdance/carp-assert-more/workflows/testsuite/badge.svg?branch=dev)](https://github.com/petdance/carp-assert-more/actions?query=workflow%3Atestsuite+branch%3Adev)
4
5# NAME
6
7Carp::Assert::More - Convenience assertions for common situations
8
9# VERSION
10
11Version 2.0.0
12
13# SYNOPSIS
14
15A set of convenience functions for common assertions.
16
17 use Carp::Assert::More;
18
19 my $obj = My::Object;
20 assert_isa( $obj, 'My::Object', 'Got back a correct object' );
21
22# DESCRIPTION
23
24Carp::Assert::More is a convenient set of assertions to make the habit
25of writing assertions even easier.
26
27Everything in here is effectively syntactic sugar. There's no technical
28difference between calling
29
30 assert_isa( $foo, 'DateTime' );
31
32or
33 assert\_datetime( $foo );
34
35that are provided by Carp::Assert::More and calling these assertions
36from Carp::Assert
37
38 assert( defined $foo );
39 assert( ref($foo) eq 'DateTime' );
40
41My intent here is to make common assertions easy so that we as programmers
42have no excuse to not use them.
43
44# SIMPLE ASSERTIONS
45
46## assert\_is( $string, $match \[,$name\] )
47
48Asserts that _$string_ matches _$match_.
49
50## assert\_isnt( $string, $unmatch \[,$name\] )
51
52Asserts that _$string_ does NOT match _$unmatch_.
53
54## assert\_like( $string, qr/regex/ \[,$name\] )
55
56Asserts that _$string_ matches _qr/regex/_.
57
58The assertion fails either the string or the regex are undef.
59
60## assert\_unlike( $string, qr/regex/ \[,$name\] )
61
62Asserts that _$string_ matches _qr/regex/_.
63
64The assertion fails if the regex is undef.
65
66## assert\_defined( $this \[, $name\] )
67
68Asserts that _$this_ is defined.
69
70## assert\_undefined( $this \[, $name\] )
71
72Asserts that _$this_ is not defined.
73
74## assert\_nonblank( $this \[, $name\] )
75
76Asserts that _$this_ is not a reference and is not an empty string.
77
78# NUMERIC ASSERTIONS
79
80## assert\_numeric( $n \[, $name\] )
81
82Asserts that `$n` looks like a number, according to `Scalar::Util::looks_like_number`.
83`undef` will always fail.
84
85## assert\_integer( $this \[, $name \] )
86
87Asserts that _$this_ is an integer, which may be zero or negative.
88
89 assert_integer( 0 ); # pass
90 assert_integer( 14 ); # pass
91 assert_integer( -14 ); # pass
92 assert_integer( '14.' ); # FAIL
93
94## assert\_nonzero( $this \[, $name \] )
95
96Asserts that the numeric value of _$this_ is defined and is not zero.
97
98 assert_nonzero( 0 ); # FAIL
99 assert_nonzero( -14 ); # pass
100 assert_nonzero( '14.' ); # pass
101
102## assert\_positive( $this \[, $name \] )
103
104Asserts that _$this_ is defined, numeric and greater than zero.
105
106 assert_positive( 0 ); # FAIL
107 assert_positive( -14 ); # FAIL
108 assert_positive( '14.' ); # pass
109
110## assert\_nonnegative( $this \[, $name \] )
111
112Asserts that _$this_ is defined, numeric and greater than or equal
113to zero.
114
115 assert_nonnegative( 0 ); # pass
116 assert_nonnegative( -14 ); # FAIL
117 assert_nonnegative( '14.' ); # pass
118 assert_nonnegative( 'dog' ); # pass
119
120## assert\_negative( $this \[, $name \] )
121
122Asserts that the numeric value of _$this_ is defined and less than zero.
123
124 assert_negative( 0 ); # FAIL
125 assert_negative( -14 ); # pass
126 assert_negative( '14.' ); # FAIL
127
128## assert\_nonzero\_integer( $this \[, $name \] )
129
130Asserts that the numeric value of _$this_ is defined, an integer, and not zero.
131
132 assert_nonzero_integer( 0 ); # FAIL
133 assert_nonzero_integer( -14 ); # pass
134 assert_nonzero_integer( '14.' ); # FAIL
135
136## assert\_positive\_integer( $this \[, $name \] )
137
138Asserts that the numeric value of _$this_ is defined, an integer and greater than zero.
139
140 assert_positive_integer( 0 ); # FAIL
141 assert_positive_integer( -14 ); # FAIL
142 assert_positive_integer( '14.' ); # FAIL
143 assert_positive_integer( '14' ); # pass
144
145## assert\_nonnegative\_integer( $this \[, $name \] )
146
147Asserts that the numeric value of _$this_ is defined, an integer, and not less than zero.
148
149 assert_nonnegative_integer( 0 ); # pass
150 assert_nonnegative_integer( -14 ); # FAIL
151 assert_nonnegative_integer( '14.' ); # FAIL
152
153## assert\_negative\_integer( $this \[, $name \] )
154
155Asserts that the numeric value of _$this_ is defined, an integer, and less than zero.
156
157 assert_negative_integer( 0 ); # FAIL
158 assert_negative_integer( -14 ); # pass
159 assert_negative_integer( '14.' ); # FAIL
160
161# REFERENCE ASSERTIONS
162
163## assert\_isa( $this, $type \[, $name \] )
164
165Asserts that _$this_ is an object of type _$type_.
166
167## assert\_isa\_in( $obj, \\@types \[, $description\] )
168
169Assert that the blessed `$obj` isa one of the types in `\@types`.
170
171 assert_isa_in( $obj, [ 'My::Foo', 'My::Bar' ], 'Must pass either a Foo or Bar object' );
172
173## assert\_empty( $this \[, $name \] )
174
175_$this_ must be a ref to either a hash or an array. Asserts that that
176collection contains no elements. Will assert (with its own message,
177not _$name_) unless given a hash or array ref. It is OK if _$this_ has
178been blessed into objecthood, but the semantics of checking an object to see
179if it does not have keys (for a hashref) or returns 0 in scalar context (for
180an array ref) may not be what you want.
181
182 assert_empty( 0 ); # FAIL
183 assert_empty( 'foo' ); # FAIL
184 assert_empty( undef ); # FAIL
185 assert_empty( {} ); # pass
186 assert_empty( [] ); # pass
187 assert_empty( {foo=>1} );# FAIL
188 assert_empty( [1,2,3] ); # FAIL
189
190## assert\_nonempty( $this \[, $name \] )
191
192_$this_ must be a ref to either a hash or an array. Asserts that that
193collection contains at least 1 element. Will assert (with its own message,
194not _$name_) unless given a hash or array ref. It is OK if _$this_ has
195been blessed into objecthood, but the semantics of checking an object to see
196if it has keys (for a hashref) or returns >0 in scalar context (for an array
197ref) may not be what you want.
198
199 assert_nonempty( 0 ); # FAIL
200 assert_nonempty( 'foo' ); # FAIL
201 assert_nonempty( undef ); # FAIL
202 assert_nonempty( {} ); # FAIL
203 assert_nonempty( [] ); # FAIL
204 assert_nonempty( {foo=>1} );# pass
205 assert_nonempty( [1,2,3] ); # pass
206
207## assert\_nonref( $this \[, $name \] )
208
209Asserts that _$this_ is not undef and not a reference.
210
211## assert\_hashref( $ref \[,$name\] )
212
213Asserts that _$ref_ is defined, and is a reference to a (possibly empty) hash.
214
215**NB:** This method returns _false_ for objects, even those whose underlying
216data is a hashref. This is as it should be, under the assumptions that:
217
218- (a)
219
220 you shouldn't rely on the underlying data structure of a particular class, and
221
222- (b)
223
224 you should use `assert_isa` instead.
225
226## assert\_hashref\_nonempty( $ref \[,$name\] )
227
228Asserts that _$ref_ is defined and is a reference to a hash with at
229least one key/value pair.
230
231## assert\_arrayref( $ref \[, $name\] )
232
233## assert\_listref( $ref \[,$name\] )
234
235Asserts that _$ref_ is defined, and is a reference to an array, which
236may or may not be empty.
237
238**NB:** The same caveat about objects whose underlying structure is a
239hash (see `assert_hashref`) applies here; this method returns false
240even for objects whose underlying structure is an array.
241
242`assert_listref` is an alias for `assert_arrayref` and may go away in
243the future. Use `assert_arrayref` instead.
244
245## assert\_arrayref\_nonempty( $ref \[, $name\] )
246
247Asserts that _$ref_ is reference to an array that has at least one element in it.
248
249## assert\_aoh( $ref \[, $name \] )
250
251Verifies that `$array` is an arrayref, and that every element is a hashref.
252
253The array `$array` can be an empty arraref and the assertion will pass.
254
255## assert\_coderef( $ref \[,$name\] )
256
257Asserts that _$ref_ is defined, and is a reference to a closure.
258
259# TYPE-SPECIFIC ASSERTIONS
260
261## assert\_datetime( $date )
262
263Asserts that `$date` is a DateTime object.
264
265# SET AND HASH MEMBERSHIP
266
267## assert\_in( $string, \\@inlist \[,$name\] );
268
269Asserts that _$string_ matches one of the elements of _\\@inlist_.
270_$string_ may be undef.
271
272_\\@inlist_ must be an array reference of non-ref strings. If any
273element is a reference, the assertion fails.
274
275## assert\_exists( \\%hash, $key \[,$name\] )
276
277## assert\_exists( \\%hash, \\@keylist \[,$name\] )
278
279Asserts that _%hash_ is indeed a hash, and that _$key_ exists in
280_%hash_, or that all of the keys in _@keylist_ exist in _%hash_.
281
282 assert_exists( \%custinfo, 'name', 'Customer has a name field' );
283
284 assert_exists( \%custinfo, [qw( name addr phone )],
285 'Customer has name, address and phone' );
286
287## assert\_lacks( \\%hash, $key \[,$name\] )
288
289## assert\_lacks( \\%hash, \\@keylist \[,$name\] )
290
291Asserts that _%hash_ is indeed a hash, and that _$key_ does NOT exist
292in _%hash_, or that none of the keys in _@keylist_ exist in _%hash_.
293The list `@keylist` cannot be empty.
294
295 assert_lacks( \%users, 'root', 'Root is not in the user table' );
296
297 assert_lacks( \%users, [qw( root admin nobody )], 'No bad usernames found' );
298
299## assert\_all\_keys\_in( \\%hash, \\@names \[, $name \] )
300
301Asserts that each key in `%hash` is in the list of `@names`.
302
303This is used to ensure that there are no extra keys in a given hash.
304
305 assert_all_keys_in( $obj, [qw( height width depth )], '$obj can only contain height, width and depth keys' );
306
307## assert\_keys\_are( \\%hash, \\@keys \[, $name \] )
308
309Asserts that the keys for `%hash` are exactly `@keys`, no more and no less.
310
311# CONTEXT ASSERTIONS
312
313## assert\_context\_nonvoid( \[$name\] )
314
315Verifies that the function currently being executed has not been called
316in void context. This is to ensure the calling function is not ignoring
317the return value of the executing function.
318
319Given this function:
320
321 sub something {
322 ...
323
324 assert_context_scalar();
325
326 return $important_value;
327 }
328
329These calls to `something` will pass:
330
331 my $val = something();
332 my @things = something();
333
334but this will fail:
335
336 something();
337
338## assert\_context\_scalar( \[$name\] )
339
340Verifies that the function currently being executed has been called in
341scalar context. This is to ensure the calling function is not ignoring
342the return value of the executing function.
343
344Given this function:
345
346 sub something {
347 ...
348
349 assert_context_scalar();
350
351 return $important_value;
352 }
353
354This call to `something` will pass:
355
356 my $val = something();
357
358but these will fail:
359
360 something();
361 my @things = something();
362
363# UTILITY ASSERTIONS
364
365## assert\_fail( \[$name\] )
366
367Assertion that always fails. `assert_fail($msg)` is exactly the same
368as calling `assert(0,$msg)`, but it eliminates that case where you
369accidentally use `assert($msg)`, which of course never fires.
370
371# COPYRIGHT & LICENSE
372
373Copyright 2005-2021 Andy Lester.
374
375This program is free software; you can redistribute it and/or modify
376it under the terms of the Artistic License version 2.0.
377
378# ACKNOWLEDGEMENTS
379
380Thanks to
381Eric A. Zarko,
382Bob Diss,
383Pete Krawczyk,
384David Storrs,
385Dan Friedman,
386Allard Hoeve,
387Thomas L. Shinnick,
388and Leland Johnson
389for code and fixes.
390