Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Test2::Tools::Compare.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test2::Tools::Compare 3pm"
61 .TH Test2::Tools::Compare 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test2::Tools::Compare \- Tools for comparing deep data structures.
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 Test::More had \f(CWis_deeply()\fR. This library is the Test2 version that can
71 be used to compare data structures, but goes a step further in that it provides
72 tools for building a data structure specification against which you can verify
73 your data. There are both \*(Aqstrict\*(Aq and \*(Aqrelaxed\*(Aq versions of the tools.
74 .SH SYNOPSIS
75 .IX Header "SYNOPSIS"
76 .Vb 1
77 \& use Test2::Tools::Compare;
78 \&
79 \& # Hash for demonstration purposes
80 \& my $some_hash = {a => 1, b => 2, c => 3};
81 \&
82 \& # Strict checking, everything must match
83 \& is(
84 \& $some_hash,
85 \& {a => 1, b => 2, c => 3},
86 \& "The hash we got matches our expectations"
87 \& );
88 \&
89 \& # Relaxed Checking, only fields we care about are checked, and we can use a
90 \& # regex to approximate a field.
91 \& like(
92 \& $some_hash,
93 \& {a => 1, b => qr/\eA[0\-9]+\ez/},
94 \& "\*(Aqa\*(Aq is 1, \*(Aqb\*(Aq is an integer, we don\*(Aqt care about \*(Aqc\*(Aq."
95 \& );
96 .Ve
97 .SS ADVANCED
98 .IX Subsection "ADVANCED"
99 Declarative hash, array, and objects builders are available that allow you to
100 generate specifications. These are more verbose than simply providing a hash,
101 but have the advantage that every component you specify has a line number
102 associated. This is helpful for debugging as the failure output will tell you
103 not only which fields was incorrect, but also the line on which you declared
104 the field.
105 .PP
106 .Vb 11
107 \& use Test2::Tools::Compare qw{
108 \& is like isnt unlike
109 \& match mismatch validator
110 \& hash array bag object meta number float rounded within string subset bool
111 \& in_set not_in_set check_set
112 \& item field call call_list call_hash prop check all_items all_keys all_vals all_values
113 \& etc end filter_items
114 \& T F D DF E DNE FDNE U L
115 \& event fail_events
116 \& exact_ref
117 \& };
118 \&
119 \& is(
120 \& $some_hash,
121 \& hash {
122 \& field a => 1;
123 \& field b => 2;
124 \& field c => 3;
125 \& },
126 \& "Hash matches spec"
127 \& );
128 .Ve
129 .SH "COMPARISON TOOLS"
130 .IX Header "COMPARISON TOOLS"
131 .ie n .IP "$bool = is($got, $expect)" 4
132 .el .IP "\f(CW$bool\fR = is($got, \f(CW$expect\fR)" 4
133 .IX Item "$bool = is($got, $expect)"
134 .PD 0
135 .ie n .IP "$bool = is($got, $expect, $name)" 4
136 .el .IP "\f(CW$bool\fR = is($got, \f(CW$expect\fR, \f(CW$name\fR)" 4
137 .IX Item "$bool = is($got, $expect, $name)"
138 .ie n .IP "$bool = is($got, $expect, $name, @diag)" 4
139 .el .IP "\f(CW$bool\fR = is($got, \f(CW$expect\fR, \f(CW$name\fR, \f(CW@diag\fR)" 4
140 .IX Item "$bool = is($got, $expect, $name, @diag)"
141 .PD
142 \&\f(CW$got\fR is the data structure you want to check. \f(CW$expect\fR is what you want
143 \&\f(CW$got\fR to look like. \f(CW$name\fR is an optional name for the test. \f(CW@diag\fR is
144 optional diagnostics messages that will be printed to STDERR in event of
145 failure, they will not be displayed when the comparison is successful. The
146 boolean true/false result of the comparison is returned.
147 .Sp
148 This is the strict checker. The strict checker requires a perfect match between
149 \&\f(CW$got\fR and \f(CW$expect\fR. All hash fields must be specified, all array items must
150 be present, etc. All non\-scalar/hash/array/regex references must be identical
151 (same memory address). Scalar, hash and array references will be traversed and
152 compared. Regex references will be compared to see if they have the same
153 pattern.
154 .Sp
155 .Vb 5
156 \& is(
157 \& $some_hash,
158 \& {a => 1, b => 2, c => 3},
159 \& "The hash we got matches our expectations"
160 \& );
161 .Ve
162 .Sp
163 The only exception to strictness is when it is given an \f(CW$expect\fR object that
164 was built from a specification, in which case the specification determines the
165 strictness. Strictness only applies to literal values/references that are
166 provided and converted to a specification for you.
167 .Sp
168 .Vb 9
169 \& is(
170 \& $some_hash,
171 \& hash { # Note: the hash function is not exported by default
172 \& field a => 1;
173 \& field b => match(qr/\eA[0\-9]+\ez/); # Note: The match function is not exported by default
174 \& # Don\*(Aqt care about other fields.
175 \& },
176 \& "The hash comparison is not strict"
177 \& );
178 .Ve
179 .Sp
180 This works for both deep and shallow structures. For instance you can use this
181 to compare two strings:
182 .Sp
183 .Vb 1
184 \& is(\*(Aqfoo\*(Aq, \*(Aqfoo\*(Aq, "strings match");
185 .Ve
186 .Sp
187 \&\fBNote\fR: This is not the tool to use if you want to check if two references are
188 the same exact reference, use \f(CWref_is()\fR from the
189 Test2::Tools::Ref plugin instead. \fIMost\fR of the time this will
190 work as well, however there are problems if your reference contains a cycle and
191 refers back to itself at some point. If this happens, an exception will be
192 thrown to break an otherwise infinite recursion.
193 .Sp
194 \&\fBNote\fR: Non\-reference values will be compared as strings using \f(CW\*(C`eq\*(C'\fR, so that
195 means strings \*(Aq2.0\*(Aq and \*(Aq2\*(Aq will not match, but numeric 2.0 and 2 will, since
196 they are both stringified to \*(Aq2\*(Aq.
197 .ie n .IP "$bool = isnt($got, $expect)" 4
198 .el .IP "\f(CW$bool\fR = isnt($got, \f(CW$expect\fR)" 4
199 .IX Item "$bool = isnt($got, $expect)"
200 .PD 0
201 .ie n .IP "$bool = isnt($got, $expect, $name)" 4
202 .el .IP "\f(CW$bool\fR = isnt($got, \f(CW$expect\fR, \f(CW$name\fR)" 4
203 .IX Item "$bool = isnt($got, $expect, $name)"
204 .ie n .IP "$bool = isnt($got, $expect, $name, @diag)" 4
205 .el .IP "\f(CW$bool\fR = isnt($got, \f(CW$expect\fR, \f(CW$name\fR, \f(CW@diag\fR)" 4
206 .IX Item "$bool = isnt($got, $expect, $name, @diag)"
207 .PD
208 Opposite of \f(CWis()\fR. Does all the same checks, but passes when there is a
209 mismatch.
210 .ie n .IP "$bool = like($got, $expect)" 4
211 .el .IP "\f(CW$bool\fR = like($got, \f(CW$expect\fR)" 4
212 .IX Item "$bool = like($got, $expect)"
213 .PD 0
214 .ie n .IP "$bool = like($got, $expect, $name)" 4
215 .el .IP "\f(CW$bool\fR = like($got, \f(CW$expect\fR, \f(CW$name\fR)" 4
216 .IX Item "$bool = like($got, $expect, $name)"
217 .ie n .IP "$bool = like($got, $expect, $name, @diag)" 4
218 .el .IP "\f(CW$bool\fR = like($got, \f(CW$expect\fR, \f(CW$name\fR, \f(CW@diag\fR)" 4
219 .IX Item "$bool = like($got, $expect, $name, @diag)"
220 .PD
221 \&\f(CW$got\fR is the data structure you want to check. \f(CW$expect\fR is what you want
222 \&\f(CW$got\fR to look like. \f(CW$name\fR is an optional name for the test. \f(CW@diag\fR is
223 optional diagnostics messages that will be printed to STDERR in event of
224 failure, they will not be displayed when the comparison is successful. The
225 boolean true/false result of the comparison is returned.
226 .Sp
227 This is the relaxed checker. This will ignore hash keys or array indexes that
228 you do not actually specify in your \f(CW$expect\fR structure. In addition regex and
229 sub references will be used as validators. If you provide a regex using
230 \&\f(CW\*(C`qr/.../\*(C'\fR, the regex itself will be used to validate the corresponding value
231 in the \f(CW$got\fR structure. The same is true for coderefs, the value is passed in
232 as the first argument (and in \f(CW$_\fR) and the sub should return a boolean value.
233 In this tool regexes will stringify the thing they are checking.
234 .Sp
235 .Vb 5
236 \& like(
237 \& $some_hash,
238 \& {a => 1, b => qr/\eA[0\-9]+\ez/},
239 \& "\*(Aqa\*(Aq is 1, \*(Aqb\*(Aq is an integer, we don\*(Aqt care about other fields"
240 \& );
241 .Ve
242 .Sp
243 This works for both deep and shallow structures. For instance you can use this
244 to compare two strings:
245 .Sp
246 .Vb 1
247 \& like(\*(Aqfoo bar\*(Aq, qr/^foo/, "string matches the pattern");
248 .Ve
249 .ie n .IP "$bool = unlike($got, $expect)" 4
250 .el .IP "\f(CW$bool\fR = unlike($got, \f(CW$expect\fR)" 4
251 .IX Item "$bool = unlike($got, $expect)"
252 .PD 0
253 .ie n .IP "$bool = unlike($got, $expect, $name)" 4
254 .el .IP "\f(CW$bool\fR = unlike($got, \f(CW$expect\fR, \f(CW$name\fR)" 4
255 .IX Item "$bool = unlike($got, $expect, $name)"
256 .ie n .IP "$bool = unlike($got, $expect, $name, @diag)" 4
257 .el .IP "\f(CW$bool\fR = unlike($got, \f(CW$expect\fR, \f(CW$name\fR, \f(CW@diag\fR)" 4
258 .IX Item "$bool = unlike($got, $expect, $name, @diag)"
259 .PD
260 Opposite of \f(CWlike()\fR. Does all the same checks, but passes when there is a
261 mismatch.
262 .PP
263 The \f(CWis()\fR, \f(CWisnt()\fR, \f(CWlike()\fR, and \f(CWunlike()\fR functions can be made
264 to dump \f(CW$got\fR using Data::Dumper when tests fail by setting the
265 \&\f(CW\*(C`T2_AUTO_DUMP\*(C'\fR environment variable to "1". (Alternatively, \f(CW\*(C`T2_AUTO_DUMP\*(C'\fR
266 can be set to the name of a Perl module providing a compatible \f(CWDump()\fR
267 method.) The \f(CW\*(C`T2_AUTO_DEPARSE\*(C'\fR environment variable can be used to
268 enable Data::Dumper\*(Aqs deparsing of coderefs.
269 .SS "QUICK CHECKS"
270 .IX Subsection "QUICK CHECKS"
271 \&\fBNote: None of these are exported by default. You need to request them.\fR
272 .PP
273 Quick checks are a way to quickly generate a common value specification. These
274 can be used in structures passed into \f(CW\*(C`is\*(C'\fR and \f(CW\*(C`like\*(C'\fR through the \f(CW$expect\fR
275 argument.
276 .PP
277 Example:
278 .PP
279 .Vb 1
280 \& is($foo, T(), \*(Aq$foo has a true value\*(Aq);
281 .Ve
282 .ie n .IP "$check = T()" 4
283 .el .IP "\f(CW$check\fR = T()" 4
284 .IX Item "$check = T()"
285 This verifies that the value in the corresponding \f(CW$got\fR structure is
286 true, any true value will do.
287 .Sp
288 .Vb 1
289 \& is($foo, T(), \*(Aq$foo has a true value\*(Aq);
290 \&
291 \& is(
292 \& { a => \*(Aqxxx\*(Aq },
293 \& { a => T() },
294 \& "The \*(Aqa\*(Aq key is true"
295 \& );
296 .Ve
297 .ie n .IP "$check = F()" 4
298 .el .IP "\f(CW$check\fR = F()" 4
299 .IX Item "$check = F()"
300 This verifies that the value in the corresponding \f(CW$got\fR structure is
301 false, any false value will do, \fBbut the value must exist\fR.
302 .Sp
303 .Vb 1
304 \& is($foo, F(), \*(Aq$foo has a false value\*(Aq);
305 \&
306 \& is(
307 \& { a => 0 },
308 \& { a => F() },
309 \& "The \*(Aqa\*(Aq key is false"
310 \& );
311 .Ve
312 .Sp
313 It is important to note that a nonexistent value does not count as false. This
314 check will generate a failing test result:
315 .Sp
316 .Vb 5
317 \& is(
318 \& { a => 1 },
319 \& { a => 1, b => F() },
320 \& "The \*(Aqb\*(Aq key is false"
321 \& );
322 .Ve
323 .Sp
324 This will produce the following output:
325 .Sp
326 .Vb 8
327 \& not ok 1 \- The b key is false
328 \& # Failed test "The \*(Aqb\*(Aq key is false"
329 \& # at some_file.t line 10.
330 \& # +\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
331 \& # | PATH | GOT | OP | CHECK |
332 \& # +\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
333 \& # | {b} | <DOES NOT EXIST> | FALSE | FALSE() |
334 \& # +\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
335 .Ve
336 .Sp
337 In Perl, you can have behavior that is different for a missing key vs. a false
338 key, so it was decided not to count a completely absent value as false.
339 See the \f(CWDNE()\fR shortcut below for checking that a field is missing.
340 .Sp
341 If you want to check for false and/or DNE use the \f(CWFDNE()\fR check.
342 .ie n .IP "$check = D()" 4
343 .el .IP "\f(CW$check\fR = D()" 4
344 .IX Item "$check = D()"
345 This is to verify that the value in the \f(CW$got\fR structure is defined. Any value
346 other than \f(CW\*(C`undef\*(C'\fR will pass.
347 .Sp
348 This will pass:
349 .Sp
350 .Vb 1
351 \& is(\*(Aqfoo\*(Aq, D(), \*(Aqfoo is defined\*(Aq);
352 .Ve
353 .Sp
354 This will fail:
355 .Sp
356 .Vb 1
357 \& is(undef, D(), \*(Aqfoo is defined\*(Aq);
358 .Ve
359 .ie n .IP "$check = U()" 4
360 .el .IP "\f(CW$check\fR = U()" 4
361 .IX Item "$check = U()"
362 This is to verify that the value in the \f(CW$got\fR structure is undefined.
363 .Sp
364 This will pass:
365 .Sp
366 .Vb 1
367 \& is(undef, U(), \*(Aqnot defined\*(Aq);
368 .Ve
369 .Sp
370 This will fail:
371 .Sp
372 .Vb 1
373 \& is(\*(Aqfoo\*(Aq, U(), \*(Aqnot defined\*(Aq);
374 .Ve
375 .ie n .IP "$check = \fBDF()\fR" 4
376 .el .IP "\f(CW$check\fR = \fBDF()\fR" 4
377 .IX Item "$check = DF()"
378 This is to verify that the value in the \f(CW$got\fR structure is defined but false.
379 Any false value other than \f(CW\*(C`undef\*(C'\fR will pass.
380 .Sp
381 This will pass:
382 .Sp
383 .Vb 1
384 \& is(0, DF(), \*(Aqfoo is defined but false\*(Aq);
385 .Ve
386 .Sp
387 These will fail:
388 .Sp
389 .Vb 2
390 \& is(undef, DF(), \*(Aqfoo is defined but false\*(Aq);
391 \& is(1, DF(), \*(Aqfoo is defined but false\*(Aq);
392 .Ve
393 .ie n .IP "$check = E()" 4
394 .el .IP "\f(CW$check\fR = E()" 4
395 .IX Item "$check = E()"
396 This can be used to check that a value exists. This is useful to check that an
397 array has more values, or to check that a key exists in a hash, even if the
398 value is undefined.
399 .Sp
400 These pass:
401 .Sp
402 .Vb 2
403 \& is([\*(Aqa\*(Aq, \*(Aqb\*(Aq, undef], [\*(Aqa\*(Aq, \*(Aqb\*(Aq, E()], "There is a third item in the array");
404 \& is({a => 1, b => 2}, {a => 1, b => E()}, "The \*(Aqb\*(Aq key exists in the hash");
405 .Ve
406 .Sp
407 These will fail:
408 .Sp
409 .Vb 2
410 \& is([\*(Aqa\*(Aq, \*(Aqb\*(Aq], [\*(Aqa\*(Aq, \*(Aqb\*(Aq, E()], "Third item exists");
411 \& is({a => 1}, {a => 1, b => E()}, "\*(Aqb\*(Aq key exists");
412 .Ve
413 .ie n .IP "$check = \fBDNE()\fR" 4
414 .el .IP "\f(CW$check\fR = \fBDNE()\fR" 4
415 .IX Item "$check = DNE()"
416 This can be used to check that no value exists. This is useful to check the end
417 bound of an array, or to check that a key does not exist in a hash.
418 .Sp
419 These pass:
420 .Sp
421 .Vb 2
422 \& is([\*(Aqa\*(Aq, \*(Aqb\*(Aq], [\*(Aqa\*(Aq, \*(Aqb\*(Aq, DNE()], "There is no third item in the array");
423 \& is({a => 1}, {a => 1, b => DNE()}, "The \*(Aqb\*(Aq key does not exist in the hash");
424 .Ve
425 .Sp
426 These will fail:
427 .Sp
428 .Vb 2
429 \& is([\*(Aqa\*(Aq, \*(Aqb\*(Aq, \*(Aqc\*(Aq], [\*(Aqa\*(Aq, \*(Aqb\*(Aq, DNE()], "No third item");
430 \& is({a => 1, b => 2}, {a => 1, b => DNE()}, "No \*(Aqb\*(Aq key");
431 .Ve
432 .ie n .IP "$check = \fBFDNE()\fR" 4
433 .el .IP "\f(CW$check\fR = \fBFDNE()\fR" 4
434 .IX Item "$check = FDNE()"
435 This is a combination of \f(CWF()\fR and \f(CWDNE()\fR. This will pass for a false value,
436 or a nonexistent value.
437 .ie n .IP "$check = L()" 4
438 .el .IP "\f(CW$check\fR = L()" 4
439 .IX Item "$check = L()"
440 This is to verify that the value in the \f(CW$got\fR structure is defined and
441 has length. Any value other than \f(CW\*(C`undef\*(C'\fR or the empty string will pass
442 (including references).
443 .Sp
444 These will pass:
445 .Sp
446 .Vb 2
447 \& is(\*(Aqfoo\*(Aq, L(), \*(Aqvalue is defined and has length\*(Aq);
448 \& is([], L(), \*(Aqvalue is defined and has length\*(Aq);
449 .Ve
450 .Sp
451 These will fail:
452 .Sp
453 .Vb 2
454 \& is(undef, L(), \*(Aqvalue is defined and has length\*(Aq);
455 \& is(\*(Aq\*(Aq, L(), \*(Aqvalue is defined and has length\*(Aq);
456 .Ve
457 .SS "VALUE SPECIFICATIONS"
458 .IX Subsection "VALUE SPECIFICATIONS"
459 \&\fBNote: None of these are exported by default. You need to request them.\fR
460 .ie n .IP "$check = string ""...""" 4
461 .el .IP "\f(CW$check\fR = string ""...""" 4
462 .IX Item "$check = string ""..."""
463 Verify that the value matches the given string using the \f(CW\*(C`eq\*(C'\fR operator.
464 .ie n .IP "$check = !string ""...""" 4
465 .el .IP "\f(CW$check\fR = !string ""...""" 4
466 .IX Item "$check = !string ""..."""
467 Verify that the value does not match the given string using the \f(CW\*(C`ne\*(C'\fR operator.
468 .ie n .IP "$check = number ...;" 4
469 .el .IP "\f(CW$check\fR = number ...;" 4
470 .IX Item "$check = number ...;"
471 Verify that the value matches the given number using the \f(CW\*(C`==\*(C'\fR operator.
472 .ie n .IP "$check = !number ...;" 4
473 .el .IP "\f(CW$check\fR = !number ...;" 4
474 .IX Item "$check = !number ...;"
475 Verify that the value does not match the given number using the \f(CW\*(C`!=\*(C'\fR operator.
476 .ie n .IP "$check = number_lt ...;" 4
477 .el .IP "\f(CW$check\fR = number_lt ...;" 4
478 .IX Item "$check = number_lt ...;"
479 .PD 0
480 .ie n .IP "$check = number_le ...;" 4
481 .el .IP "\f(CW$check\fR = number_le ...;" 4
482 .IX Item "$check = number_le ...;"
483 .ie n .IP "$check = number_ge ...;" 4
484 .el .IP "\f(CW$check\fR = number_ge ...;" 4
485 .IX Item "$check = number_ge ...;"
486 .ie n .IP "$check = number_gt ...;" 4
487 .el .IP "\f(CW$check\fR = number_gt ...;" 4
488 .IX Item "$check = number_gt ...;"
489 .PD
490 Verify that the value is less than, less than or equal to, greater than or
491 equal to, or greater than the given number.
492 .ie n .IP "$check = float ...;" 4
493 .el .IP "\f(CW$check\fR = float ...;" 4
494 .IX Item "$check = float ...;"
495 Verify that the value is approximately equal to the given number.
496 .Sp
497 If a \*(Aqprecision\*(Aq parameter is specified, both operands will be
498 rounded to \*(Aqprecision\*(Aq number of fractional decimal digits and
499 compared with \f(CW\*(C`eq\*(C'\fR.
500 .Sp
501 .Vb 1
502 \& is($near_val, float($val, precision => 4), "Near 4 decimal digits");
503 .Ve
504 .Sp
505 Otherwise, the check will be made within a range of +/\- \*(Aqtolerance\*(Aq,
506 with a default \*(Aqtolerance\*(Aq of 1e\-08.
507 .Sp
508 .Vb 1
509 \& is( $near_val, float($val, tolerance => 0.01), "Almost there...");
510 .Ve
511 .Sp
512 See also \f(CW\*(C`within\*(C'\fR and \f(CW\*(C`rounded\*(C'\fR.
513 .ie n .IP "$check = !float ...;" 4
514 .el .IP "\f(CW$check\fR = !float ...;" 4
515 .IX Item "$check = !float ...;"
516 Verify that the value is not approximately equal to the given number.
517 .Sp
518 If a \*(Aqprecision\*(Aq parameter is specified, both operands will be
519 rounded to \*(Aqprecision\*(Aq number of fractional decimal digits and
520 compared with \f(CW\*(C`eq\*(C'\fR.
521 .Sp
522 Otherwise, the check will be made within a range of +/\- \*(Aqtolerance\*(Aq,
523 with a default \*(Aqtolerance\*(Aq of 1e\-08.
524 .Sp
525 See also \f(CW\*(C`!within\*(C'\fR and \f(CW\*(C`!rounded\*(C'\fR.
526 .ie n .IP "$check = within($num, $tolerance);" 4
527 .el .IP "\f(CW$check\fR = within($num, \f(CW$tolerance\fR);" 4
528 .IX Item "$check = within($num, $tolerance);"
529 Verify that the value approximately matches the given number,
530 within a range of +/\- \f(CW$tolerance\fR. Compared using the \f(CW\*(C`==\*(C'\fR operator.
531 .Sp
532 \&\f(CW$tolerance\fR is optional and defaults to 1e\-08.
533 .ie n .IP "$check = !within($num, $tolerance);" 4
534 .el .IP "\f(CW$check\fR = !within($num, \f(CW$tolerance\fR);" 4
535 .IX Item "$check = !within($num, $tolerance);"
536 Verify that the value does not approximately match the given number within a range of +/\- \f(CW$tolerance\fR. Compared using the \f(CW\*(C`!=\*(C'\fR operator.
537 .Sp
538 \&\f(CW$tolerance\fR is optional and defaults to 1e\-08.
539 .ie n .IP "$check = rounded($num, $precision);" 4
540 .el .IP "\f(CW$check\fR = rounded($num, \f(CW$precision\fR);" 4
541 .IX Item "$check = rounded($num, $precision);"
542 Verify that the value approximately matches the given number, when both are rounded to \f(CW$precision\fR number of fractional digits. Compared using the \f(CW\*(C`eq\*(C'\fR operator.
543 .ie n .IP "$check = !rounded($num, $precision);" 4
544 .el .IP "\f(CW$check\fR = !rounded($num, \f(CW$precision\fR);" 4
545 .IX Item "$check = !rounded($num, $precision);"
546 Verify that the value does not approximately match the given number, when both are rounded to \f(CW$precision\fR number of fractional digits. Compared using the \f(CW\*(C`ne\*(C'\fR operator.
547 .ie n .IP "$check = bool ...;" 4
548 .el .IP "\f(CW$check\fR = bool ...;" 4
549 .IX Item "$check = bool ...;"
550 Verify the value has the same boolean value as the given argument (XNOR).
551 .ie n .IP "$check = !bool ...;" 4
552 .el .IP "\f(CW$check\fR = !bool ...;" 4
553 .IX Item "$check = !bool ...;"
554 Verify the value has a different boolean value from the given argument (XOR).
555 .ie n .IP "$check = check_isa ...;" 4
556 .el .IP "\f(CW$check\fR = check_isa ...;" 4
557 .IX Item "$check = check_isa ...;"
558 Verify the value is an instance of the given class name.
559 .ie n .IP "$check = !check_isa ...;" 4
560 .el .IP "\f(CW$check\fR = !check_isa ...;" 4
561 .IX Item "$check = !check_isa ...;"
562 Verify the value is not an instance of the given class name.
563 .ie n .IP "$check = match qr/.../" 4
564 .el .IP "\f(CW$check\fR = match qr/.../" 4
565 .IX Item "$check = match qr/.../"
566 .PD 0
567 .ie n .IP "$check = !mismatch qr/.../" 4
568 .el .IP "\f(CW$check\fR = !mismatch qr/.../" 4
569 .IX Item "$check = !mismatch qr/.../"
570 .PD
571 Verify that the value matches the regex pattern. This form of pattern check
572 will \fBNOT\fR stringify references being checked.
573 .Sp
574 \&\fBNote:\fR \f(CW\*(C`!mismatch()\*(C'\fR is documented for completion, please do not use it.
575 .ie n .IP "$check = !match qr/.../" 4
576 .el .IP "\f(CW$check\fR = !match qr/.../" 4
577 .IX Item "$check = !match qr/.../"
578 .PD 0
579 .ie n .IP "$check = mismatch qr/.../" 4
580 .el .IP "\f(CW$check\fR = mismatch qr/.../" 4
581 .IX Item "$check = mismatch qr/.../"
582 .PD
583 Verify that the value does not match the regex pattern. This form of pattern
584 check will \fBNOT\fR stringify references being checked.
585 .Sp
586 \&\fBNote:\fR \f(CWmismatch()\fR was created before overloading of \f(CW\*(C`!\*(C'\fR for \f(CWmatch()\fR
587 was a thing.
588 .ie n .IP "$check = validator(sub{ ... })" 4
589 .el .IP "\f(CW$check\fR = validator(sub{ ... })" 4
590 .IX Item "$check = validator(sub{ ... })"
591 .PD 0
592 .ie n .IP "$check = validator($NAME => sub{ ... })" 4
593 .el .IP "\f(CW$check\fR = validator($NAME => sub{ ... })" 4
594 .IX Item "$check = validator($NAME => sub{ ... })"
595 .ie n .IP "$check = validator($OP, $NAME, sub{ ... })" 4
596 .el .IP "\f(CW$check\fR = validator($OP, \f(CW$NAME\fR, sub{ ... })" 4
597 .IX Item "$check = validator($OP, $NAME, sub{ ... })"
598 .PD
599 The coderef is the only required argument. The coderef should check that the
600 value is what you expect and return a boolean true or false. Optionally,
601 you can specify a name and operator that are used in diagnostics. They are also
602 provided to the sub itself as named parameters.
603 .Sp
604 Check the value using this sub. The sub gets the value in \f(CW$_\fR, and it
605 receives the value and several other items as named parameters.
606 .Sp
607 .Vb 2
608 \& my $check = validator(sub {
609 \& my %params = @_;
610 \&
611 \& # These both work:
612 \& my $got = $_;
613 \& my $got = $params{got};
614 \&
615 \& # Check if a value exists at all
616 \& my $exists = $params{exists}
617 \&
618 \& # What $OP (if any) did we specify when creating the validator
619 \& my $operator = $params{operator};
620 \&
621 \& # What name (if any) did we specify when creating the validator
622 \& my $name = $params{name};
623 \&
624 \& ...
625 \&
626 \& return $bool;
627 \& }
628 .Ve
629 .ie n .IP "$check = exact_ref($ref)" 4
630 .el .IP "\f(CW$check\fR = exact_ref($ref)" 4
631 .IX Item "$check = exact_ref($ref)"
632 Check that the value is exactly the same reference as the one provided.
633 .SS "SET BUILDERS"
634 .IX Subsection "SET BUILDERS"
635 \&\fBNote: None of these are exported by default. You need to request them.\fR
636 .ie n .IP "my $check = check_set($check1, $check2, ...)" 4
637 .el .IP "my \f(CW$check\fR = check_set($check1, \f(CW$check2\fR, ...)" 4
638 .IX Item "my $check = check_set($check1, $check2, ...)"
639 Check that the value matches ALL of the specified checks.
640 .ie n .IP "my $check = in_set($check1, $check2, ...)" 4
641 .el .IP "my \f(CW$check\fR = in_set($check1, \f(CW$check2\fR, ...)" 4
642 .IX Item "my $check = in_set($check1, $check2, ...)"
643 Check that the value matches ONE OR MORE of the specified checks.
644 .ie n .IP "not_in_set($check1, $check2, ...)" 4
645 .el .IP "not_in_set($check1, \f(CW$check2\fR, ...)" 4
646 .IX Item "not_in_set($check1, $check2, ...)"
647 Check that the value DOES NOT match ANY of the specified checks.
648 .ie n .IP "check $thing" 4
649 .el .IP "check \f(CW$thing\fR" 4
650 .IX Item "check $thing"
651 Check that the value matches the specified thing.
652 .SS "HASH BUILDER"
653 .IX Subsection "HASH BUILDER"
654 \&\fBNote: None of these are exported by default. You need to request them.\fR
655 .PP
656 .Vb 3
657 \& $check = hash {
658 \& field foo => 1;
659 \& field bar => 2;
660 \&
661 \& # Ensure the \*(Aqbaz\*(Aq keys does not even exist in the hash.
662 \& field baz => DNE();
663 \&
664 \& # Ensure the key exists, but is set to undef
665 \& field bat => undef;
666 \&
667 \& # Any check can be used
668 \& field boo => $check;
669 \&
670 \& # Set checks that apply to all keys or values. Can be done multiple
671 \& # times, and each call can define multiple checks, all will be run.
672 \& all_vals match qr/a/, match qr/b/; # All values must have an \*(Aqa\*(Aq and a \*(Aqb\*(Aq
673 \& all_keys match qr/x/; # All keys must have an \*(Aqx\*(Aq
674 \&
675 \& ...
676 \&
677 \& end(); # optional, enforces that no other keys are present.
678 \& };
679 .Ve
680 .ie n .IP "$check = hash { ... }" 4
681 .el .IP "\f(CW$check\fR = hash { ... }" 4
682 .IX Item "$check = hash { ... }"
683 This is used to define a hash check.
684 .ie n .IP "field $NAME => $VAL" 4
685 .el .IP "field \f(CW$NAME\fR => \f(CW$VAL\fR" 4
686 .IX Item "field $NAME => $VAL"
687 .PD 0
688 .ie n .IP "field $NAME => $CHECK" 4
689 .el .IP "field \f(CW$NAME\fR => \f(CW$CHECK\fR" 4
690 .IX Item "field $NAME => $CHECK"
691 .PD
692 Specify a field check. This will check the hash key specified by \f(CW$NAME\fR and
693 ensure it matches the value in \f(CW$VAL\fR. You can put any valid check in \f(CW$VAL\fR,
694 such as the result of another call to \f(CW\*(C`array { ... }\*(C'\fR, \f(CWDNE()\fR, etc.
695 .Sp
696 \&\fBNote:\fR This function can only be used inside a hash builder sub, and must be
697 called in void context.
698 .ie n .IP "all_keys($CHECK1, $CHECK2, ...)" 4
699 .el .IP "all_keys($CHECK1, \f(CW$CHECK2\fR, ...)" 4
700 .IX Item "all_keys($CHECK1, $CHECK2, ...)"
701 Add checks that apply to all keys. You can put this anywhere in the hash
702 block, and can call it any number of times with any number of arguments.
703 .ie n .IP "all_vals($CHECK1, $CHECK2, ...)" 4
704 .el .IP "all_vals($CHECK1, \f(CW$CHECK2\fR, ...)" 4
705 .IX Item "all_vals($CHECK1, $CHECK2, ...)"
706 .PD 0
707 .ie n .IP "all_values($CHECK1, $CHECK2, ...)" 4
708 .el .IP "all_values($CHECK1, \f(CW$CHECK2\fR, ...)" 4
709 .IX Item "all_values($CHECK1, $CHECK2, ...)"
710 .PD
711 Add checks that apply to all values. You can put this anywhere in the hash
712 block, and can call it any number of times with any number of arguments.
713 .IP \fBend()\fR 4
714 .IX Item "end()"
715 Enforce that no keys are found in the hash other than those specified. This is
716 essentially the \f(CW\*(C`use strict\*(C'\fR of a hash check. This can be used anywhere in the
717 hash builder, though typically it is placed at the end.
718 .IP \fBetc()\fR 4
719 .IX Item "etc()"
720 Ignore any extra keys found in the hash. This is the opposite of \f(CWend()\fR.
721 This can be used anywhere in the hash builder, though typically it is placed at
722 the end.
723 .IP \fBDNE()\fR 4
724 .IX Item "DNE()"
725 This is a handy check that can be used with \f(CWfield()\fR to ensure that a field
726 (D)oes (N)ot (E)xist.
727 .Sp
728 .Vb 1
729 \& field foo => DNE();
730 .Ve
731 .SS "ARRAY BUILDER"
732 .IX Subsection "ARRAY BUILDER"
733 \&\fBNote: None of these are exported by default. You need to request them.\fR
734 .PP
735 .Vb 3
736 \& $check = array {
737 \& # Uses the next index, in this case index 0;
738 \& item \*(Aqa\*(Aq;
739 \&
740 \& # Gets index 1 automatically
741 \& item \*(Aqb\*(Aq;
742 \&
743 \& # Specify the index
744 \& item 2 => \*(Aqc\*(Aq;
745 \&
746 \& # We skipped index 3, which means we don\*(Aqt care what it is.
747 \& item 4 => \*(Aqe\*(Aq;
748 \&
749 \& # Gets index 5.
750 \& item \*(Aqf\*(Aq;
751 \&
752 \& # Remove any REMAINING items that contain 0\-9.
753 \& filter_items { grep {!m/[0\-9]/} @_ };
754 \&
755 \& # Set checks that apply to all items. Can be done multiple times, and
756 \& # each call can define multiple checks, all will be run.
757 \& all_items match qr/a/, match qr/b/;
758 \& all_items match qr/x/;
759 \&
760 \& # Of the remaining items (after the filter is applied) the next one
761 \& # (which is now index 6) should be \*(Aqg\*(Aq.
762 \& item 6 => \*(Aqg\*(Aq;
763 \&
764 \& item 7 => DNE; # Ensure index 7 does not exist.
765 \&
766 \& end(); # Ensure no other indexes exist.
767 \& };
768 .Ve
769 .ie n .IP "$check = array { ... }" 4
770 .el .IP "\f(CW$check\fR = array { ... }" 4
771 .IX Item "$check = array { ... }"
772 .PD 0
773 .ie n .IP "item $VAL" 4
774 .el .IP "item \f(CW$VAL\fR" 4
775 .IX Item "item $VAL"
776 .ie n .IP "item $CHECK" 4
777 .el .IP "item \f(CW$CHECK\fR" 4
778 .IX Item "item $CHECK"
779 .ie n .IP "item $IDX, $VAL" 4
780 .el .IP "item \f(CW$IDX\fR, \f(CW$VAL\fR" 4
781 .IX Item "item $IDX, $VAL"
782 .ie n .IP "item $IDX, $CHECK" 4
783 .el .IP "item \f(CW$IDX\fR, \f(CW$CHECK\fR" 4
784 .IX Item "item $IDX, $CHECK"
785 .PD
786 Add an expected item to the array. If \f(CW$IDX\fR is not specified it will
787 automatically calculate it based on the last item added. You can skip indexes,
788 which means you do not want them to be checked.
789 .Sp
790 You can provide any value to check in \f(CW$VAL\fR, or you can provide any valid
791 check object.
792 .Sp
793 \&\fBNote:\fR Items MUST be added in order.
794 .Sp
795 \&\fBNote:\fR This function can only be used inside an array, bag or subset
796 builder sub, and must be called in void context.
797 .ie n .IP "filter_items { my @remaining = @_; ...; return @filtered }" 4
798 .el .IP "filter_items { my \f(CW@remaining\fR = \f(CW@_\fR; ...; return \f(CW@filtered\fR }" 4
799 .IX Item "filter_items { my @remaining = @_; ...; return @filtered }"
800 This function adds a filter, all items remaining in the array from the point
801 the filter is reached will be passed into the filter sub as arguments, the sub
802 should return only the items that should be checked.
803 .Sp
804 \&\fBNote:\fR This function can only be used inside an array builder sub, and must
805 be called in void context.
806 .ie n .IP "all_items($CHECK1, $CHECK2, ...)" 4
807 .el .IP "all_items($CHECK1, \f(CW$CHECK2\fR, ...)" 4
808 .IX Item "all_items($CHECK1, $CHECK2, ...)"
809 Add checks that apply to all items. You can put this anywhere in the array
810 block, and can call it any number of times with any number of arguments.
811 .IP \fBend()\fR 4
812 .IX Item "end()"
813 Enforce that there are no indexes after the last one specified. This will not
814 force checking of skipped indexes.
815 .IP \fBetc()\fR 4
816 .IX Item "etc()"
817 Ignore any extra items found in the array. This is the opposite of \f(CWend()\fR.
818 This can be used anywhere in the array builder, though typically it is placed
819 at the end.
820 .IP \fBDNE()\fR 4
821 .IX Item "DNE()"
822 This is a handy check that can be used with \f(CWitem()\fR to ensure that an index
823 (D)oes (N)ot (E)xist.
824 .Sp
825 .Vb 1
826 \& item 5 => DNE();
827 .Ve
828 .SS "BAG BUILDER"
829 .IX Subsection "BAG BUILDER"
830 \&\fBNote: None of these are exported by default. You need to request them.\fR
831 .PP
832 .Vb 3
833 \& $check = bag {
834 \& item \*(Aqa\*(Aq;
835 \& item \*(Aqb\*(Aq;
836 \&
837 \& end(); # Ensure no other elements exist.
838 \& };
839 .Ve
840 .PP
841 A bag is like an array, but we don\*(Aqt care about the order of the
842 items. In the example, \f(CW$check\fR would match both \f(CW\*(C`[\*(Aqa\*(Aq,\*(Aqb\*(Aq]\*(C'\fR and
843 \&\f(CW\*(C`[\*(Aqb\*(Aq,\*(Aqa\*(Aq]\*(C'\fR.
844 .ie n .IP "$check = bag { ... }" 4
845 .el .IP "\f(CW$check\fR = bag { ... }" 4
846 .IX Item "$check = bag { ... }"
847 .PD 0
848 .ie n .IP "item $VAL" 4
849 .el .IP "item \f(CW$VAL\fR" 4
850 .IX Item "item $VAL"
851 .ie n .IP "item $CHECK" 4
852 .el .IP "item \f(CW$CHECK\fR" 4
853 .IX Item "item $CHECK"
854 .PD
855 Add an expected item to the bag.
856 .Sp
857 You can provide any value to check in \f(CW$VAL\fR, or you can provide any valid
858 check object.
859 .Sp
860 \&\fBNote:\fR This function can only be used inside an array, bag or subset
861 builder sub, and must be called in void context.
862 .ie n .IP "all_items($CHECK1, $CHECK2, ...)" 4
863 .el .IP "all_items($CHECK1, \f(CW$CHECK2\fR, ...)" 4
864 .IX Item "all_items($CHECK1, $CHECK2, ...)"
865 Add checks that apply to all items. You can put this anywhere in the bag
866 block, and can call it any number of times with any number of arguments.
867 .IP \fBend()\fR 4
868 .IX Item "end()"
869 Enforce that there are no more items after the last one specified.
870 .IP \fBetc()\fR 4
871 .IX Item "etc()"
872 Ignore any extra items found in the array. This is the opposite of \f(CWend()\fR.
873 This can be used anywhere in the bag builder, though typically it is placed
874 at the end.
875 .SS "ORDERED SUBSET BUILDER"
876 .IX Subsection "ORDERED SUBSET BUILDER"
877 \&\fBNote: None of these are exported by default. You need to request them.\fR
878 .PP
879 .Vb 4
880 \& $check = subset {
881 \& item \*(Aqa\*(Aq;
882 \& item \*(Aqb\*(Aq;
883 \& item \*(Aqc\*(Aq;
884 \&
885 \& # Doesn\*(Aqt matter if the array has \*(Aqd\*(Aq, the check will skip past any
886 \& # unknown items until it finds the next one in our subset.
887 \&
888 \& item \*(Aqe\*(Aq;
889 \& item \*(Aqf\*(Aq;
890 \& };
891 .Ve
892 .ie n .IP "$check = subset { ... }" 4
893 .el .IP "\f(CW$check\fR = subset { ... }" 4
894 .IX Item "$check = subset { ... }"
895 .PD 0
896 .ie n .IP "item $VAL" 4
897 .el .IP "item \f(CW$VAL\fR" 4
898 .IX Item "item $VAL"
899 .ie n .IP "item $CHECK" 4
900 .el .IP "item \f(CW$CHECK\fR" 4
901 .IX Item "item $CHECK"
902 .PD
903 Add an expected item to the subset.
904 .Sp
905 You can provide any value to check in \f(CW$VAL\fR, or you can provide any valid
906 check object.
907 .Sp
908 \&\fBNote:\fR Items MUST be added in order.
909 .Sp
910 \&\fBNote:\fR This function can only be used inside an array, bag or subset
911 builder sub, and must be called in void context.
912 .SS "META BUILDER"
913 .IX Subsection "META BUILDER"
914 \&\fBNote: None of these are exported by default. You need to request them.\fR
915 .PP
916 .Vb 7
917 \& my $check = meta {
918 \& prop blessed => \*(AqMy::Module\*(Aq; # Ensure value is blessed as our package
919 \& prop reftype => \*(AqHASH\*(Aq; # Ensure value is a blessed hash
920 \& prop isa => \*(AqMy::Base\*(Aq; # Ensure value is an instance of our class
921 \& prop size => 4; # Check the number of hash keys
922 \& prop this => ...; # Check the item itself
923 \& };
924 .Ve
925 .IP "meta { ... }" 4
926 .IX Item "meta { ... }"
927 .PD 0
928 .IP "meta_check { ... }" 4
929 .IX Item "meta_check { ... }"
930 .PD
931 Build a meta check. If you are using Moose then the \f(CWmeta()\fR function would
932 conflict with the one exported by Moose, in such cases \f(CWmeta_check()\fR is
933 available. Neither is exported by default.
934 .ie n .IP "prop $NAME => $VAL" 4
935 .el .IP "prop \f(CW$NAME\fR => \f(CW$VAL\fR" 4
936 .IX Item "prop $NAME => $VAL"
937 .PD 0
938 .ie n .IP "prop $NAME => $CHECK" 4
939 .el .IP "prop \f(CW$NAME\fR => \f(CW$CHECK\fR" 4
940 .IX Item "prop $NAME => $CHECK"
941 .PD
942 Check the property specified by \f(CW$name\fR against the value or check.
943 .Sp
944 Valid properties are:
945 .RS 4
946 .IP \*(Aqblessed\*(Aq 4
947 .IX Item "'blessed'"
948 What package (if any) the thing is blessed as.
949 .IP \*(Aqreftype\*(Aq 4
950 .IX Item "'reftype'"
951 Reference type (if any) the thing is.
952 .IP \*(Aqisa\*(Aq 4
953 .IX Item "'isa'"
954 What class the thing is an instance of.
955 .IP \*(Aqthis\*(Aq 4
956 .IX Item "'this'"
957 The thing itself.
958 .IP \*(Aqsize\*(Aq 4
959 .IX Item "'size'"
960 For array references this returns the number of elements. For hashes this
961 returns the number of keys. For everything else this returns undef.
962 .RE
963 .RS 4
964 .RE
965 .SS "OBJECT BUILDER"
966 .IX Subsection "OBJECT BUILDER"
967 \&\fBNote: None of these are exported by default. You need to request them.\fR
968 .PP
969 .Vb 2
970 \& my $check = object {
971 \& call foo => 1; # Call the \*(Aqfoo\*(Aq method, check the result.
972 \&
973 \& # Call the specified sub\-ref as a method on the object, check the
974 \& # result. This is useful for wrapping methods that return multiple
975 \& # values.
976 \& call sub { [ shift\->get_list ] } => [...];
977 \&
978 \& # This can be used to ensure a method does not exist.
979 \& call nope => DNE();
980 \&
981 \& # Check the hash key \*(Aqfoo\*(Aq of the underlying reference, this only works
982 \& # on blessed hashes.
983 \& field foo => 1;
984 \&
985 \& # Check the value of index 4 on the underlying reference, this only
986 \& # works on blessed arrays.
987 \& item 4 => \*(Aqfoo\*(Aq;
988 \&
989 \& # Check the meta\-property \*(Aqblessed\*(Aq of the object.
990 \& prop blessed => \*(AqMy::Module\*(Aq;
991 \&
992 \& # Check if the object is an instance of the specified class.
993 \& prop isa => \*(AqMy::Base\*(Aq;
994 \&
995 \& # Ensure only the specified hash keys or array indexes are present in
996 \& # the underlying hash. Has no effect on meta\-property checks or method
997 \& # checks.
998 \& end();
999 \& };
1000 .Ve
1001 .ie n .IP "$check = object { ... }" 4
1002 .el .IP "\f(CW$check\fR = object { ... }" 4
1003 .IX Item "$check = object { ... }"
1004 Specify an object check for use in comparisons.
1005 .ie n .IP "call $METHOD_NAME => $RESULT" 4
1006 .el .IP "call \f(CW$METHOD_NAME\fR => \f(CW$RESULT\fR" 4
1007 .IX Item "call $METHOD_NAME => $RESULT"
1008 .PD 0
1009 .ie n .IP "call $METHOD_NAME => $CHECK" 4
1010 .el .IP "call \f(CW$METHOD_NAME\fR => \f(CW$CHECK\fR" 4
1011 .IX Item "call $METHOD_NAME => $CHECK"
1012 .ie n .IP "call [$METHOD_NAME, @METHOD_ARGS] => $RESULT" 4
1013 .el .IP "call [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$RESULT\fR" 4
1014 .IX Item "call [$METHOD_NAME, @METHOD_ARGS] => $RESULT"
1015 .ie n .IP "call [$METHOD_NAME, @METHOD_ARGS] => $CHECK" 4
1016 .el .IP "call [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$CHECK\fR" 4
1017 .IX Item "call [$METHOD_NAME, @METHOD_ARGS] => $CHECK"
1018 .ie n .IP "call sub { ... }, $RESULT" 4
1019 .el .IP "call sub { ... }, \f(CW$RESULT\fR" 4
1020 .IX Item "call sub { ... }, $RESULT"
1021 .ie n .IP "call sub { ... }, $CHECK" 4
1022 .el .IP "call sub { ... }, \f(CW$CHECK\fR" 4
1023 .IX Item "call sub { ... }, $CHECK"
1024 .PD
1025 Call the specified method (or coderef) and verify the result. If you
1026 pass an arrayref, the first element must be the method name, the
1027 others are the arguments it will be called with.
1028 .Sp
1029 The coderef form is useful if you need to do something more complex.
1030 .Sp
1031 .Vb 4
1032 \& my $ref = sub {
1033 \& local $SOME::GLOBAL::THING = 3;
1034 \& return [shift\->get_values_for(\*(Aqthing\*(Aq)];
1035 \& };
1036 \&
1037 \& call $ref => ...;
1038 .Ve
1039 .ie n .IP "call_list $METHOD_NAME => $RESULT" 4
1040 .el .IP "call_list \f(CW$METHOD_NAME\fR => \f(CW$RESULT\fR" 4
1041 .IX Item "call_list $METHOD_NAME => $RESULT"
1042 .PD 0
1043 .ie n .IP "call_list $METHOD_NAME => $CHECK" 4
1044 .el .IP "call_list \f(CW$METHOD_NAME\fR => \f(CW$CHECK\fR" 4
1045 .IX Item "call_list $METHOD_NAME => $CHECK"
1046 .ie n .IP "call_list [$METHOD_NAME, @METHOD_ARGS] => $RESULT" 4
1047 .el .IP "call_list [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$RESULT\fR" 4
1048 .IX Item "call_list [$METHOD_NAME, @METHOD_ARGS] => $RESULT"
1049 .ie n .IP "call_list [$METHOD_NAME, @METHOD_ARGS] => $CHECK" 4
1050 .el .IP "call_list [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$CHECK\fR" 4
1051 .IX Item "call_list [$METHOD_NAME, @METHOD_ARGS] => $CHECK"
1052 .ie n .IP "call_list sub { ... }, $RESULT" 4
1053 .el .IP "call_list sub { ... }, \f(CW$RESULT\fR" 4
1054 .IX Item "call_list sub { ... }, $RESULT"
1055 .ie n .IP "call_list sub { ... }, $CHECK" 4
1056 .el .IP "call_list sub { ... }, \f(CW$CHECK\fR" 4
1057 .IX Item "call_list sub { ... }, $CHECK"
1058 .PD
1059 Same as \f(CW\*(C`call\*(C'\fR, but the method is invoked in list context, and the
1060 result is always an arrayref.
1061 .Sp
1062 .Vb 1
1063 \& call_list get_items => [ ... ];
1064 .Ve
1065 .ie n .IP "call_hash $METHOD_NAME => $RESULT" 4
1066 .el .IP "call_hash \f(CW$METHOD_NAME\fR => \f(CW$RESULT\fR" 4
1067 .IX Item "call_hash $METHOD_NAME => $RESULT"
1068 .PD 0
1069 .ie n .IP "call_hash $METHOD_NAME => $CHECK" 4
1070 .el .IP "call_hash \f(CW$METHOD_NAME\fR => \f(CW$CHECK\fR" 4
1071 .IX Item "call_hash $METHOD_NAME => $CHECK"
1072 .ie n .IP "call_hash [$METHOD_NAME, @METHOD_ARGS] => $RESULT" 4
1073 .el .IP "call_hash [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$RESULT\fR" 4
1074 .IX Item "call_hash [$METHOD_NAME, @METHOD_ARGS] => $RESULT"
1075 .ie n .IP "call_hash [$METHOD_NAME, @METHOD_ARGS] => $CHECK" 4
1076 .el .IP "call_hash [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$CHECK\fR" 4
1077 .IX Item "call_hash [$METHOD_NAME, @METHOD_ARGS] => $CHECK"
1078 .ie n .IP "call_hash sub { ... }, $RESULT" 4
1079 .el .IP "call_hash sub { ... }, \f(CW$RESULT\fR" 4
1080 .IX Item "call_hash sub { ... }, $RESULT"
1081 .ie n .IP "call_hash sub { ... }, $CHECK" 4
1082 .el .IP "call_hash sub { ... }, \f(CW$CHECK\fR" 4
1083 .IX Item "call_hash sub { ... }, $CHECK"
1084 .PD
1085 Same as \f(CW\*(C`call\*(C'\fR, but the method is invoked in list context, and the
1086 result is always a hashref. This will warn if the method returns an
1087 odd number of values.
1088 .Sp
1089 .Vb 1
1090 \& call_hash get_items => { ... };
1091 .Ve
1092 .ie n .IP "field $NAME => $VAL" 4
1093 .el .IP "field \f(CW$NAME\fR => \f(CW$VAL\fR" 4
1094 .IX Item "field $NAME => $VAL"
1095 Works just like it does for hash checks.
1096 .ie n .IP "item $VAL" 4
1097 .el .IP "item \f(CW$VAL\fR" 4
1098 .IX Item "item $VAL"
1099 .PD 0
1100 .ie n .IP "item $IDX, $VAL" 4
1101 .el .IP "item \f(CW$IDX\fR, \f(CW$VAL\fR" 4
1102 .IX Item "item $IDX, $VAL"
1103 .PD
1104 Works just like it does for array checks.
1105 .ie n .IP "prop $NAME => $VAL" 4
1106 .el .IP "prop \f(CW$NAME\fR => \f(CW$VAL\fR" 4
1107 .IX Item "prop $NAME => $VAL"
1108 .PD 0
1109 .ie n .IP "prop $NAME => $CHECK" 4
1110 .el .IP "prop \f(CW$NAME\fR => \f(CW$CHECK\fR" 4
1111 .IX Item "prop $NAME => $CHECK"
1112 .PD
1113 Check the property specified by \f(CW$name\fR against the value or check.
1114 .Sp
1115 Valid properties are:
1116 .RS 4
1117 .IP \*(Aqblessed\*(Aq 4
1118 .IX Item "'blessed'"
1119 What package (if any) the thing is blessed as.
1120 .IP \*(Aqreftype\*(Aq 4
1121 .IX Item "'reftype'"
1122 Reference type (if any) the thing is.
1123 .IP \*(Aqisa\*(Aq 4
1124 .IX Item "'isa'"
1125 What class the thing is an instance of.
1126 .IP \*(Aqthis\*(Aq 4
1127 .IX Item "'this'"
1128 The thing itself.
1129 .IP \*(Aqsize\*(Aq 4
1130 .IX Item "'size'"
1131 For array references this returns the number of elements. For hashes this
1132 returns the number of keys. For everything else this returns undef.
1133 .RE
1134 .RS 4
1135 .RE
1136 .IP \fBDNE()\fR 4
1137 .IX Item "DNE()"
1138 Can be used with \f(CW\*(C`item\*(C'\fR, or \f(CW\*(C`field\*(C'\fR to ensure the hash field or array index
1139 does not exist. Can also be used with \f(CW\*(C`call\*(C'\fR to ensure a method does not
1140 exist.
1141 .IP \fBend()\fR 4
1142 .IX Item "end()"
1143 Turn on strict array/hash checking, ensuring that no extra keys/indexes
1144 are present.
1145 .IP \fBetc()\fR 4
1146 .IX Item "etc()"
1147 Ignore any extra items found in the hash/array. This is the opposite of
1148 \&\f(CWend()\fR. This can be used anywhere in the builder, though typically it is
1149 placed at the end.
1150 .SS "EVENT BUILDERS"
1151 .IX Subsection "EVENT BUILDERS"
1152 \&\fBNote: None of these are exported by default. You need to request them.\fR
1153 .PP
1154 Check that we got an event of a specified type:
1155 .PP
1156 .Vb 1
1157 \& my $check = event \*(AqOk\*(Aq;
1158 .Ve
1159 .PP
1160 Check for details about the event:
1161 .PP
1162 .Vb 3
1163 \& my $check = event Ok => sub {
1164 \& # Check for a failure
1165 \& call pass => 0;
1166 \&
1167 \& # Effective pass after TODO/SKIP are accounted for.
1168 \& call effective_pass => 1;
1169 \&
1170 \& # Check the diagnostics
1171 \& call diag => [ match qr/Failed test foo/ ];
1172 \&
1173 \& # Check the file the event reports to
1174 \& prop file => \*(Aqfoo.t\*(Aq;
1175 \&
1176 \& # Check the line number the event reports to
1177 \& prop line => \*(Aq42\*(Aq;
1178 \&
1179 \& # You can check the todo/skip values as well:
1180 \& prop skip => \*(Aqbroken\*(Aq;
1181 \& prop todo => \*(Aqfixme\*(Aq;
1182 \&
1183 \& # Thread\-id and process\-id where event was generated
1184 \& prop tid => 123;
1185 \& prop pid => 123;
1186 \& };
1187 .Ve
1188 .PP
1189 You can also provide a fully qualified event package with the \*(Aq+\*(Aq prefix:
1190 .PP
1191 .Vb 1
1192 \& my $check = event \*(Aq+My::Event\*(Aq => sub { ... }
1193 .Ve
1194 .PP
1195 You can also provide a hashref instead of a sub to directly check hash values
1196 of the event:
1197 .PP
1198 .Vb 1
1199 \& my $check = event Ok => { pass => 1, ... };
1200 .Ve
1201 .PP
1202 \fIUSE IN OTHER BUILDERS\fR
1203 .IX Subsection "USE IN OTHER BUILDERS"
1204 .PP
1205 You can use these all in other builders, simply use them in void context to
1206 have their value(s) appended to the build.
1207 .PP
1208 .Vb 3
1209 \& my $check = array {
1210 \& event Ok => { ... };
1211 \& event Note => { ... };
1212 \&
1213 \& fail_events Ok => { pass => 0 };
1214 \& # Get a Diag for free.
1215 \& };
1216 .Ve
1217 .PP
1218 \fISPECIFICS\fR
1219 .IX Subsection "SPECIFICS"
1220 .ie n .IP "$check = event $TYPE;" 4
1221 .el .IP "\f(CW$check\fR = event \f(CW$TYPE\fR;" 4
1222 .IX Item "$check = event $TYPE;"
1223 .PD 0
1224 .ie n .IP "$check = event $TYPE => sub { ... };" 4
1225 .el .IP "\f(CW$check\fR = event \f(CW$TYPE\fR => sub { ... };" 4
1226 .IX Item "$check = event $TYPE => sub { ... };"
1227 .ie n .IP "$check = event $TYPE => { ... };" 4
1228 .el .IP "\f(CW$check\fR = event \f(CW$TYPE\fR => { ... };" 4
1229 .IX Item "$check = event $TYPE => { ... };"
1230 .PD
1231 This works just like an object builder. In addition to supporting everything
1232 the object check supports, you also have to specify the event type, and many
1233 extra meta\-properties are available.
1234 .Sp
1235 Extra properties are:
1236 .RS 4
1237 .IP \*(Aqfile\*(Aq 4
1238 .IX Item "'file'"
1239 File name to which the event reports (for use in diagnostics).
1240 .IP \*(Aqline\*(Aq 4
1241 .IX Item "'line'"
1242 Line number to which the event reports (for use in diagnostics).
1243 .IP \*(Aqpackage\*(Aq 4
1244 .IX Item "'package'"
1245 Package to which the event reports (for use in diagnostics).
1246 .IP \*(Aqsubname\*(Aq 4
1247 .IX Item "'subname'"
1248 Sub that was called to generate the event (example: \f(CWok()\fR).
1249 .IP \*(Aqskip\*(Aq 4
1250 .IX Item "'skip'"
1251 Set to the skip value if the result was generated by skipping tests.
1252 .IP \*(Aqtodo\*(Aq 4
1253 .IX Item "'todo'"
1254 Set to the todo value if TODO was set when the event was generated.
1255 .IP \*(Aqtrace\*(Aq 4
1256 .IX Item "'trace'"
1257 The \f(CW\*(C`at file foo.t line 42\*(C'\fR string that will be used in diagnostics.
1258 .IP \*(Aqtid\*(Aq 4
1259 .IX Item "'tid'"
1260 Thread ID in which the event was generated.
1261 .IP \*(Aqpid\*(Aq 4
1262 .IX Item "'pid'"
1263 Process ID in which the event was generated.
1264 .RE
1265 .RS 4
1266 .Sp
1267 \&\fBNOTE\fR: Event checks have an implicit \f(CWetc()\fR added. This means you need to
1268 use \f(CWend()\fR if you want to fail on unexpected hash keys or array indexes. This
1269 implicit \f(CWetc()\fR extends to all forms, including builder, hashref, and no
1270 argument.
1271 .RE
1272 .ie n .IP "@checks = fail_events $TYPE;" 4
1273 .el .IP "\f(CW@checks\fR = fail_events \f(CW$TYPE\fR;" 4
1274 .IX Item "@checks = fail_events $TYPE;"
1275 .PD 0
1276 .ie n .IP "@checks = fail_events $TYPE => sub { ... };" 4
1277 .el .IP "\f(CW@checks\fR = fail_events \f(CW$TYPE\fR => sub { ... };" 4
1278 .IX Item "@checks = fail_events $TYPE => sub { ... };"
1279 .ie n .IP "@checks = fail_events $TYPE => { ... };" 4
1280 .el .IP "\f(CW@checks\fR = fail_events \f(CW$TYPE\fR => { ... };" 4
1281 .IX Item "@checks = fail_events $TYPE => { ... };"
1282 .PD
1283 Just like \f(CWevent()\fR documented above. The difference is that this produces two
1284 events, the one you specify, and a \f(CW\*(C`Diag\*(C'\fR after it. There are no extra checks
1285 in the Diag.
1286 .Sp
1287 Use this to validate a simple failure where you do not want to be bothered with
1288 the default diagnostics. It only adds a single Diag check, so if your failure
1289 has custom diagnostics you will need to add checks for them.
1290 .SH SOURCE
1291 .IX Header "SOURCE"
1292 The source code repository for Test2\-Suite can be found at
1293 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
1294 .SH MAINTAINERS
1295 .IX Header "MAINTAINERS"
1296 .IP "Chad Granum <[email protected]>" 4
1297 .IX Item "Chad Granum <[email protected]>"
1298 .SH AUTHORS
1299 .IX Header "AUTHORS"
1300 .IP "Chad Granum <[email protected]>" 4
1301 .IX Item "Chad Granum <[email protected]>"
1302 .SH COPYRIGHT
1303 .IX Header "COPYRIGHT"
1304 Copyright Chad Granum <[email protected]>.
1305 .PP
1306 This program is free software; you can redistribute it and/or
1307 modify it under the same terms as Perl itself.
1308 .PP
1309 See \fIhttp://dev.perl.org/licenses/\fR