.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test2::Tools::Compare 3perl"
.TH Test2::Tools::Compare 3perl 2024-09-01 "perl v5.40.0" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Test2::Tools::Compare \- Tools for comparing deep data structures.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Test::More had \f(CWis_deeply()\fR. This library is the Test2 version that can
be used to compare data structures, but goes a step further in that it provides
tools for building a data structure specification against which you can verify
your data. There are both 'strict' and 'relaxed' versions of the tools.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use Test2::Tools::Compare;
\&
\&    # Hash for demonstration purposes
\&    my $some_hash = {a => 1, b => 2, c => 3};
\&
\&    # Strict checking, everything must match
\&    is(
\&        $some_hash,
\&        {a => 1, b => 2, c => 3},
\&        "The hash we got matches our expectations"
\&    );
\&
\&    # Relaxed Checking, only fields we care about are checked, and we can use a
\&    # regex to approximate a field.
\&    like(
\&        $some_hash,
\&        {a => 1, b => qr/\eA[0\-9]+\ez/},
\&        "\*(Aqa\*(Aq is 1, \*(Aqb\*(Aq is an integer, we don\*(Aqt care about \*(Aqc\*(Aq."
\&    );
.Ve
.SS ADVANCED
.IX Subsection "ADVANCED"
Declarative hash, array, and objects builders are available that allow you to
generate specifications. These are more verbose than simply providing a hash,
but have the advantage that every component you specify has a line number
associated. This is helpful for debugging as the failure output will tell you
not only which fields was incorrect, but also the line on which you declared
the field.
.PP
.Vb 11
\&    use Test2::Tools::Compare qw{
\&        is like isnt unlike
\&        match mismatch validator
\&        hash array bag object meta number float rounded within string subset bool
\&        in_set not_in_set check_set
\&        item field call call_list call_hash prop check all_items all_keys all_vals all_values
\&        etc end filter_items
\&        T F D DF E DNE FDNE U L
\&        event fail_events
\&        exact_ref
\&    };
\&
\&    is(
\&        $some_hash,
\&        hash {
\&            field a => 1;
\&            field b => 2;
\&            field c => 3;
\&        },
\&        "Hash matches spec"
\&    );
.Ve
.SH "COMPARISON TOOLS"
.IX Header "COMPARISON TOOLS"
.ie n .IP "$bool = is($got, $expect)" 4
.el .IP "\f(CW$bool\fR = is($got, \f(CW$expect\fR)" 4
.IX Item "$bool = is($got, $expect)"
.PD 0
.ie n .IP "$bool = is($got, $expect, $name)" 4
.el .IP "\f(CW$bool\fR = is($got, \f(CW$expect\fR, \f(CW$name\fR)" 4
.IX Item "$bool = is($got, $expect, $name)"
.ie n .IP "$bool = is($got, $expect, $name, @diag)" 4
.el .IP "\f(CW$bool\fR = is($got, \f(CW$expect\fR, \f(CW$name\fR, \f(CW@diag\fR)" 4
.IX Item "$bool = is($got, $expect, $name, @diag)"
.PD
\&\f(CW$got\fR is the data structure you want to check. \f(CW$expect\fR is what you want
\&\f(CW$got\fR to look like. \f(CW$name\fR is an optional name for the test. \f(CW@diag\fR is
optional diagnostics messages that will be printed to STDERR in event of
failure, they will not be displayed when the comparison is successful. The
boolean true/false result of the comparison is returned.
.Sp
This is the strict checker. The strict checker requires a perfect match between
\&\f(CW$got\fR and \f(CW$expect\fR. All hash fields must be specified, all array items must
be present, etc. All non\-scalar/hash/array/regex references must be identical
(same memory address). Scalar, hash and array references will be traversed and
compared. Regex references will be compared to see if they have the same
pattern.
.Sp
.Vb 5
\&    is(
\&        $some_hash,
\&        {a => 1, b => 2, c => 3},
\&        "The hash we got matches our expectations"
\&    );
.Ve
.Sp
The only exception to strictness is when it is given an \f(CW$expect\fR object that
was built from a specification, in which case the specification determines the
strictness. Strictness only applies to literal values/references that are
provided and converted to a specification for you.
.Sp
.Vb 9
\&    is(
\&        $some_hash,
\&        hash {    # Note: the hash function is not exported by default
\&            field a => 1;
\&            field b => match(qr/\eA[0\-9]+\ez/);    # Note: The match function is not exported by default
\&            # Don\*(Aqt care about other fields.
\&        },
\&        "The hash comparison is not strict"
\&    );
.Ve
.Sp
This works for both deep and shallow structures. For instance you can use this
to compare two strings:
.Sp
.Vb 1
\&    is(\*(Aqfoo\*(Aq, \*(Aqfoo\*(Aq, "strings match");
.Ve
.Sp
\&\fBNote\fR: This is not the tool to use if you want to check if two references are
the same exact reference, use \f(CWref_is()\fR from the
Test2::Tools::Ref plugin instead. \fIMost\fR of the time this will
work as well, however there are problems if your reference contains a cycle and
refers back to itself at some point. If this happens, an exception will be
thrown to break an otherwise infinite recursion.
.Sp
\&\fBNote\fR: Non-reference values will be compared as strings using \f(CW\*(C`eq\*(C'\fR, so that
means strings '2.0' and '2' will not match, but numeric 2.0 and 2 will, since
they are both stringified to '2'.
.ie n .IP "$bool = isnt($got, $expect)" 4
.el .IP "\f(CW$bool\fR = isnt($got, \f(CW$expect\fR)" 4
.IX Item "$bool = isnt($got, $expect)"
.PD 0
.ie n .IP "$bool = isnt($got, $expect, $name)" 4
.el .IP "\f(CW$bool\fR = isnt($got, \f(CW$expect\fR, \f(CW$name\fR)" 4
.IX Item "$bool = isnt($got, $expect, $name)"
.ie n .IP "$bool = isnt($got, $expect, $name, @diag)" 4
.el .IP "\f(CW$bool\fR = isnt($got, \f(CW$expect\fR, \f(CW$name\fR, \f(CW@diag\fR)" 4
.IX Item "$bool = isnt($got, $expect, $name, @diag)"
.PD
Opposite of \f(CWis()\fR. Does all the same checks, but passes when there is a
mismatch.
.ie n .IP "$bool = like($got, $expect)" 4
.el .IP "\f(CW$bool\fR = like($got, \f(CW$expect\fR)" 4
.IX Item "$bool = like($got, $expect)"
.PD 0
.ie n .IP "$bool = like($got, $expect, $name)" 4
.el .IP "\f(CW$bool\fR = like($got, \f(CW$expect\fR, \f(CW$name\fR)" 4
.IX Item "$bool = like($got, $expect, $name)"
.ie n .IP "$bool = like($got, $expect, $name, @diag)" 4
.el .IP "\f(CW$bool\fR = like($got, \f(CW$expect\fR, \f(CW$name\fR, \f(CW@diag\fR)" 4
.IX Item "$bool = like($got, $expect, $name, @diag)"
.PD
\&\f(CW$got\fR is the data structure you want to check. \f(CW$expect\fR is what you want
\&\f(CW$got\fR to look like. \f(CW$name\fR is an optional name for the test. \f(CW@diag\fR is
optional diagnostics messages that will be printed to STDERR in event of
failure, they will not be displayed when the comparison is successful. The
boolean true/false result of the comparison is returned.
.Sp
This is the relaxed checker. This will ignore hash keys or array indexes that
you do not actually specify in your \f(CW$expect\fR structure. In addition regex and
sub references will be used as validators. If you provide a regex using
\&\f(CW\*(C`qr/.../\*(C'\fR, the regex itself will be used to validate the corresponding value
in the \f(CW$got\fR structure. The same is true for coderefs, the value is passed in
as the first argument (and in \f(CW$_\fR) and the sub should return a boolean value.
In this tool regexes will stringify the thing they are checking.
.Sp
.Vb 5
\&    like(
\&        $some_hash,
\&        {a => 1, b => qr/\eA[0\-9]+\ez/},
\&        "\*(Aqa\*(Aq is 1, \*(Aqb\*(Aq is an integer, we don\*(Aqt care about other fields"
\&    );
.Ve
.Sp
This works for both deep and shallow structures. For instance you can use this
to compare two strings:
.Sp
.Vb 1
\&    like(\*(Aqfoo bar\*(Aq, qr/^foo/, "string matches the pattern");
.Ve
.ie n .IP "$bool = unlike($got, $expect)" 4
.el .IP "\f(CW$bool\fR = unlike($got, \f(CW$expect\fR)" 4
.IX Item "$bool = unlike($got, $expect)"
.PD 0
.ie n .IP "$bool = unlike($got, $expect, $name)" 4
.el .IP "\f(CW$bool\fR = unlike($got, \f(CW$expect\fR, \f(CW$name\fR)" 4
.IX Item "$bool = unlike($got, $expect, $name)"
.ie n .IP "$bool = unlike($got, $expect, $name, @diag)" 4
.el .IP "\f(CW$bool\fR = unlike($got, \f(CW$expect\fR, \f(CW$name\fR, \f(CW@diag\fR)" 4
.IX Item "$bool = unlike($got, $expect, $name, @diag)"
.PD
Opposite of \f(CWlike()\fR. Does all the same checks, but passes when there is a
mismatch.
.PP
The \f(CWis()\fR, \f(CWisnt()\fR, \f(CWlike()\fR, and \f(CWunlike()\fR functions can be made
to dump \f(CW$got\fR using Data::Dumper when tests fail by setting the
\&\f(CW\*(C`T2_AUTO_DUMP\*(C'\fR environment variable to "1". (Alternatively, \f(CW\*(C`T2_AUTO_DUMP\*(C'\fR
can be set to the name of a Perl module providing a compatible \f(CWDump()\fR
method.) The \f(CW\*(C`T2_AUTO_DEPARSE\*(C'\fR environment variable can be used to
enable Data::Dumper's deparsing of coderefs.
.SS "QUICK CHECKS"
.IX Subsection "QUICK CHECKS"
\&\fBNote: None of these are exported by default. You need to request them.\fR
.PP
Quick checks are a way to quickly generate a common value specification. These
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
argument.
.PP
Example:
.PP
.Vb 1
\&    is($foo, T(), \*(Aq$foo has a true value\*(Aq);
.Ve
.ie n .IP "$check = T()" 4
.el .IP "\f(CW$check\fR = T()" 4
.IX Item "$check = T()"
This verifies that the value in the corresponding \f(CW$got\fR structure is
true, any true value will do.
.Sp
.Vb 1
\&    is($foo, T(), \*(Aq$foo has a true value\*(Aq);
\&
\&    is(
\&        { a => \*(Aqxxx\*(Aq },
\&        { a => T() },
\&        "The \*(Aqa\*(Aq key is true"
\&    );
.Ve
.ie n .IP "$check = F()" 4
.el .IP "\f(CW$check\fR = F()" 4
.IX Item "$check = F()"
This verifies that the value in the corresponding \f(CW$got\fR structure is
false, any false value will do, \fBbut the value must exist\fR.
.Sp
.Vb 1
\&    is($foo, F(), \*(Aq$foo has a false value\*(Aq);
\&
\&    is(
\&        { a => 0 },
\&        { a => F() },
\&        "The \*(Aqa\*(Aq key is false"
\&    );
.Ve
.Sp
It is important to note that a nonexistent value does not count as false. This
check will generate a failing test result:
.Sp
.Vb 5
\&    is(
\&        { a => 1 },
\&        { a => 1, b => F() },
\&        "The \*(Aqb\*(Aq key is false"
\&    );
.Ve
.Sp
This will produce the following output:
.Sp
.Vb 8
\&    not ok 1 \- The b key is false
\&    # Failed test "The \*(Aqb\*(Aq key is false"
\&    # at some_file.t line 10.
\&    # +\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
\&    # | PATH | GOT              | OP    | CHECK   |
\&    # +\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
\&    # | {b}  | <DOES NOT EXIST> | FALSE | FALSE() |
\&    # +\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
.Ve
.Sp
In Perl, you can have behavior that is different for a missing key vs. a false
key, so it was decided not to count a completely absent value as false.
See the \f(CWDNE()\fR shortcut below for checking that a field is missing.
.Sp
If you want to check for false and/or DNE use the \f(CWFDNE()\fR check.
.ie n .IP "$check = D()" 4
.el .IP "\f(CW$check\fR = D()" 4
.IX Item "$check = D()"
This is to verify that the value in the \f(CW$got\fR structure is defined. Any value
other than \f(CW\*(C`undef\*(C'\fR will pass.
.Sp
This will pass:
.Sp
.Vb 1
\&    is(\*(Aqfoo\*(Aq, D(), \*(Aqfoo is defined\*(Aq);
.Ve
.Sp
This will fail:
.Sp
.Vb 1
\&    is(undef, D(), \*(Aqfoo is defined\*(Aq);
.Ve
.ie n .IP "$check = U()" 4
.el .IP "\f(CW$check\fR = U()" 4
.IX Item "$check = U()"
This is to verify that the value in the \f(CW$got\fR structure is undefined.
.Sp
This will pass:
.Sp
.Vb 1
\&    is(undef, U(), \*(Aqnot defined\*(Aq);
.Ve
.Sp
This will fail:
.Sp
.Vb 1
\&    is(\*(Aqfoo\*(Aq, U(), \*(Aqnot defined\*(Aq);
.Ve
.ie n .IP "$check = \fBDF()\fR" 4
.el .IP "\f(CW$check\fR = \fBDF()\fR" 4
.IX Item "$check = DF()"
This is to verify that the value in the \f(CW$got\fR structure is defined but false.
Any false value other than \f(CW\*(C`undef\*(C'\fR will pass.
.Sp
This will pass:
.Sp
.Vb 1
\&    is(0, DF(), \*(Aqfoo is defined but false\*(Aq);
.Ve
.Sp
These will fail:
.Sp
.Vb 2
\&    is(undef, DF(), \*(Aqfoo is defined but false\*(Aq);
\&    is(1, DF(), \*(Aqfoo is defined but false\*(Aq);
.Ve
.ie n .IP "$check = E()" 4
.el .IP "\f(CW$check\fR = E()" 4
.IX Item "$check = E()"
This can be used to check that a value exists. This is useful to check that an
array has more values, or to check that a key exists in a hash, even if the
value is undefined.
.Sp
These pass:
.Sp
.Vb 2
\&    is([\*(Aqa\*(Aq, \*(Aqb\*(Aq, undef], [\*(Aqa\*(Aq, \*(Aqb\*(Aq, E()], "There is a third item in the array");
\&    is({a => 1, b => 2}, {a => 1, b => E()}, "The \*(Aqb\*(Aq key exists in the hash");
.Ve
.Sp
These will fail:
.Sp
.Vb 2
\&    is([\*(Aqa\*(Aq, \*(Aqb\*(Aq], [\*(Aqa\*(Aq, \*(Aqb\*(Aq, E()], "Third item exists");
\&    is({a => 1}, {a => 1, b => E()}, "\*(Aqb\*(Aq key exists");
.Ve
.ie n .IP "$check = \fBDNE()\fR" 4
.el .IP "\f(CW$check\fR = \fBDNE()\fR" 4
.IX Item "$check = DNE()"
This can be used to check that no value exists. This is useful to check the end
bound of an array, or to check that a key does not exist in a hash.
.Sp
These pass:
.Sp
.Vb 2
\&    is([\*(Aqa\*(Aq, \*(Aqb\*(Aq], [\*(Aqa\*(Aq, \*(Aqb\*(Aq, DNE()], "There is no third item in the array");
\&    is({a => 1}, {a => 1, b => DNE()}, "The \*(Aqb\*(Aq key does not exist in the hash");
.Ve
.Sp
These will fail:
.Sp
.Vb 2
\&    is([\*(Aqa\*(Aq, \*(Aqb\*(Aq, \*(Aqc\*(Aq], [\*(Aqa\*(Aq, \*(Aqb\*(Aq, DNE()], "No third item");
\&    is({a => 1, b => 2}, {a => 1, b => DNE()}, "No \*(Aqb\*(Aq key");
.Ve
.ie n .IP "$check = \fBFDNE()\fR" 4
.el .IP "\f(CW$check\fR = \fBFDNE()\fR" 4
.IX Item "$check = FDNE()"
This is a combination of \f(CWF()\fR and \f(CWDNE()\fR. This will pass for a false value,
or a nonexistent value.
.ie n .IP "$check = L()" 4
.el .IP "\f(CW$check\fR = L()" 4
.IX Item "$check = L()"
This is to verify that the value in the \f(CW$got\fR structure is defined and
has length.  Any value other than \f(CW\*(C`undef\*(C'\fR or the empty string will pass
(including references).
.Sp
These will pass:
.Sp
.Vb 2
\&    is(\*(Aqfoo\*(Aq, L(), \*(Aqvalue is defined and has length\*(Aq);
\&    is([],    L(), \*(Aqvalue is defined and has length\*(Aq);
.Ve
.Sp
These will fail:
.Sp
.Vb 2
\&    is(undef, L(), \*(Aqvalue is defined and has length\*(Aq);
\&    is(\*(Aq\*(Aq,    L(), \*(Aqvalue is defined and has length\*(Aq);
.Ve
.SS "VALUE SPECIFICATIONS"
.IX Subsection "VALUE SPECIFICATIONS"
\&\fBNote: None of these are exported by default. You need to request them.\fR
.ie n .IP "$check = string ""...""" 4
.el .IP "\f(CW$check\fR = string ""...""" 4
.IX Item "$check = string ""..."""
Verify that the value matches the given string using the \f(CW\*(C`eq\*(C'\fR operator.
.ie n .IP "$check = !string ""...""" 4
.el .IP "\f(CW$check\fR = !string ""...""" 4
.IX Item "$check = !string ""..."""
Verify that the value does not match the given string using the \f(CW\*(C`ne\*(C'\fR operator.
.ie n .IP "$check = number ...;" 4
.el .IP "\f(CW$check\fR = number ...;" 4
.IX Item "$check = number ...;"
Verify that the value matches the given number using the \f(CW\*(C`==\*(C'\fR operator.
.ie n .IP "$check = !number ...;" 4
.el .IP "\f(CW$check\fR = !number ...;" 4
.IX Item "$check = !number ...;"
Verify that the value does not match the given number using the \f(CW\*(C`!=\*(C'\fR operator.
.ie n .IP "$check = number_lt ...;" 4
.el .IP "\f(CW$check\fR = number_lt ...;" 4
.IX Item "$check = number_lt ...;"
.PD 0
.ie n .IP "$check = number_le ...;" 4
.el .IP "\f(CW$check\fR = number_le ...;" 4
.IX Item "$check = number_le ...;"
.ie n .IP "$check = number_ge ...;" 4
.el .IP "\f(CW$check\fR = number_ge ...;" 4
.IX Item "$check = number_ge ...;"
.ie n .IP "$check = number_gt ...;" 4
.el .IP "\f(CW$check\fR = number_gt ...;" 4
.IX Item "$check = number_gt ...;"
.PD
Verify that the value is less than, less than or equal to, greater than or
equal to, or greater than the given number.
.ie n .IP "$check = float ...;" 4
.el .IP "\f(CW$check\fR = float ...;" 4
.IX Item "$check = float ...;"
Verify that the value is approximately equal to the given number.
.Sp
If a 'precision' parameter is specified, both operands will be
rounded to 'precision' number of fractional decimal digits and
compared with \f(CW\*(C`eq\*(C'\fR.
.Sp
.Vb 1
\&  is($near_val, float($val, precision => 4), "Near 4 decimal digits");
.Ve
.Sp
Otherwise, the check will be made within a range of +/\- 'tolerance',
with a default 'tolerance' of 1e\-08.
.Sp
.Vb 1
\&  is( $near_val, float($val, tolerance => 0.01), "Almost there...");
.Ve
.Sp
See also \f(CW\*(C`within\*(C'\fR and \f(CW\*(C`rounded\*(C'\fR.
.ie n .IP "$check = !float ...;" 4
.el .IP "\f(CW$check\fR = !float ...;" 4
.IX Item "$check = !float ...;"
Verify that the value is not approximately equal to the given number.
.Sp
If a 'precision' parameter is specified, both operands will be
rounded to 'precision' number of fractional decimal digits and
compared with \f(CW\*(C`eq\*(C'\fR.
.Sp
Otherwise, the check will be made within a range of +/\- 'tolerance',
with a default 'tolerance' of 1e\-08.
.Sp
See also \f(CW\*(C`!within\*(C'\fR and \f(CW\*(C`!rounded\*(C'\fR.
.ie n .IP "$check = within($num, $tolerance);" 4
.el .IP "\f(CW$check\fR = within($num, \f(CW$tolerance\fR);" 4
.IX Item "$check = within($num, $tolerance);"
Verify that the value approximately matches the given number,
within a range of +/\- \f(CW$tolerance\fR.  Compared using the \f(CW\*(C`==\*(C'\fR operator.
.Sp
\&\f(CW$tolerance\fR is optional and defaults to 1e\-08.
.ie n .IP "$check = !within($num, $tolerance);" 4
.el .IP "\f(CW$check\fR = !within($num, \f(CW$tolerance\fR);" 4
.IX Item "$check = !within($num, $tolerance);"
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.
.Sp
\&\f(CW$tolerance\fR is optional and defaults to 1e\-08.
.ie n .IP "$check = rounded($num, $precision);" 4
.el .IP "\f(CW$check\fR = rounded($num, \f(CW$precision\fR);" 4
.IX Item "$check = rounded($num, $precision);"
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.
.ie n .IP "$check = !rounded($num, $precision);" 4
.el .IP "\f(CW$check\fR = !rounded($num, \f(CW$precision\fR);" 4
.IX Item "$check = !rounded($num, $precision);"
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.
.ie n .IP "$check = bool ...;" 4
.el .IP "\f(CW$check\fR = bool ...;" 4
.IX Item "$check = bool ...;"
Verify the value has the same boolean value as the given argument (XNOR).
.ie n .IP "$check = !bool ...;" 4
.el .IP "\f(CW$check\fR = !bool ...;" 4
.IX Item "$check = !bool ...;"
Verify the value has a different boolean value from the given argument (XOR).
.ie n .IP "$check = check_isa ...;" 4
.el .IP "\f(CW$check\fR = check_isa ...;" 4
.IX Item "$check = check_isa ...;"
Verify the value is an instance of the given class name.
.ie n .IP "$check = !check_isa ...;" 4
.el .IP "\f(CW$check\fR = !check_isa ...;" 4
.IX Item "$check = !check_isa ...;"
Verify the value is not an instance of the given class name.
.ie n .IP "$check = match qr/.../" 4
.el .IP "\f(CW$check\fR = match qr/.../" 4
.IX Item "$check = match qr/.../"
.PD 0
.ie n .IP "$check = !mismatch qr/.../" 4
.el .IP "\f(CW$check\fR = !mismatch qr/.../" 4
.IX Item "$check = !mismatch qr/.../"
.PD
Verify that the value matches the regex pattern. This form of pattern check
will \fBNOT\fR stringify references being checked.
.Sp
\&\fBNote:\fR \f(CW\*(C`!mismatch()\*(C'\fR is documented for completion, please do not use it.
.ie n .IP "$check = !match qr/.../" 4
.el .IP "\f(CW$check\fR = !match qr/.../" 4
.IX Item "$check = !match qr/.../"
.PD 0
.ie n .IP "$check = mismatch qr/.../" 4
.el .IP "\f(CW$check\fR = mismatch qr/.../" 4
.IX Item "$check = mismatch qr/.../"
.PD
Verify that the value does not match the regex pattern. This form of pattern
check will \fBNOT\fR stringify references being checked.
.Sp
\&\fBNote:\fR \f(CWmismatch()\fR was created before overloading of \f(CW\*(C`!\*(C'\fR for \f(CWmatch()\fR
was a thing.
.ie n .IP "$check = validator(sub{ ... })" 4
.el .IP "\f(CW$check\fR = validator(sub{ ... })" 4
.IX Item "$check = validator(sub{ ... })"
.PD 0
.ie n .IP "$check = validator($NAME => sub{ ... })" 4
.el .IP "\f(CW$check\fR = validator($NAME => sub{ ... })" 4
.IX Item "$check = validator($NAME => sub{ ... })"
.ie n .IP "$check = validator($OP, $NAME, sub{ ... })" 4
.el .IP "\f(CW$check\fR = validator($OP, \f(CW$NAME\fR, sub{ ... })" 4
.IX Item "$check = validator($OP, $NAME, sub{ ... })"
.PD
The coderef is the only required argument. The coderef should check that the
value is what you expect and return a boolean true or false. Optionally,
you can specify a name and operator that are used in diagnostics. They are also
provided to the sub itself as named parameters.
.Sp
Check the value using this sub. The sub gets the value in \f(CW$_\fR, and it
receives the value and several other items as named parameters.
.Sp
.Vb 2
\&    my $check = validator(sub {
\&        my %params = @_;
\&
\&        # These both work:
\&        my $got = $_;
\&        my $got = $params{got};
\&
\&        # Check if a value exists at all
\&        my $exists = $params{exists}
\&
\&        # What $OP (if any) did we specify when creating the validator
\&        my $operator = $params{operator};
\&
\&        # What name (if any) did we specify when creating the validator
\&        my $name = $params{name};
\&
\&        ...
\&
\&        return $bool;
\&    }
.Ve
.ie n .IP "$check = exact_ref($ref)" 4
.el .IP "\f(CW$check\fR = exact_ref($ref)" 4
.IX Item "$check = exact_ref($ref)"
Check that the value is exactly the same reference as the one provided.
.SS "SET BUILDERS"
.IX Subsection "SET BUILDERS"
\&\fBNote: None of these are exported by default. You need to request them.\fR
.ie n .IP "my $check = check_set($check1, $check2, ...)" 4
.el .IP "my \f(CW$check\fR = check_set($check1, \f(CW$check2\fR, ...)" 4
.IX Item "my $check = check_set($check1, $check2, ...)"
Check that the value matches ALL of the specified checks.
.ie n .IP "my $check = in_set($check1, $check2, ...)" 4
.el .IP "my \f(CW$check\fR = in_set($check1, \f(CW$check2\fR, ...)" 4
.IX Item "my $check = in_set($check1, $check2, ...)"
Check that the value matches ONE OR MORE of the specified checks.
.ie n .IP "not_in_set($check1, $check2, ...)" 4
.el .IP "not_in_set($check1, \f(CW$check2\fR, ...)" 4
.IX Item "not_in_set($check1, $check2, ...)"
Check that the value DOES NOT match ANY of the specified checks.
.ie n .IP "check $thing" 4
.el .IP "check \f(CW$thing\fR" 4
.IX Item "check $thing"
Check that the value matches the specified thing.
.SS "HASH BUILDER"
.IX Subsection "HASH BUILDER"
\&\fBNote: None of these are exported by default. You need to request them.\fR
.PP
.Vb 3
\&    $check = hash {
\&        field foo => 1;
\&        field bar => 2;
\&
\&        # Ensure the \*(Aqbaz\*(Aq keys does not even exist in the hash.
\&        field baz => DNE();
\&
\&        # Ensure the key exists, but is set to undef
\&        field bat => undef;
\&
\&        # Any check can be used
\&        field boo => $check;
\&
\&        # Set checks that apply to all keys or values. Can be done multiple
\&        # times, and each call can define multiple checks, all will be run.
\&        all_vals match qr/a/, match qr/b/;    # All values must have an \*(Aqa\*(Aq and a \*(Aqb\*(Aq
\&        all_keys match qr/x/;                 # All keys must have an \*(Aqx\*(Aq
\&
\&        ...
\&
\&        end(); # optional, enforces that no other keys are present.
\&    };
.Ve
.ie n .IP "$check = hash { ... }" 4
.el .IP "\f(CW$check\fR = hash { ... }" 4
.IX Item "$check = hash { ... }"
This is used to define a hash check.
.ie n .IP "field $NAME => $VAL" 4
.el .IP "field \f(CW$NAME\fR => \f(CW$VAL\fR" 4
.IX Item "field $NAME => $VAL"
.PD 0
.ie n .IP "field $NAME => $CHECK" 4
.el .IP "field \f(CW$NAME\fR => \f(CW$CHECK\fR" 4
.IX Item "field $NAME => $CHECK"
.PD
Specify a field check. This will check the hash key specified by \f(CW$NAME\fR and
ensure it matches the value in \f(CW$VAL\fR. You can put any valid check in \f(CW$VAL\fR,
such as the result of another call to \f(CW\*(C`array { ... }\*(C'\fR, \f(CWDNE()\fR, etc.
.Sp
\&\fBNote:\fR This function can only be used inside a hash builder sub, and must be
called in void context.
.ie n .IP "all_keys($CHECK1, $CHECK2, ...)" 4
.el .IP "all_keys($CHECK1, \f(CW$CHECK2\fR, ...)" 4
.IX Item "all_keys($CHECK1, $CHECK2, ...)"
Add checks that apply to all keys. You can put this anywhere in the hash
block, and can call it any number of times with any number of arguments.
.ie n .IP "all_vals($CHECK1, $CHECK2, ...)" 4
.el .IP "all_vals($CHECK1, \f(CW$CHECK2\fR, ...)" 4
.IX Item "all_vals($CHECK1, $CHECK2, ...)"
.PD 0
.ie n .IP "all_values($CHECK1, $CHECK2, ...)" 4
.el .IP "all_values($CHECK1, \f(CW$CHECK2\fR, ...)" 4
.IX Item "all_values($CHECK1, $CHECK2, ...)"
.PD
Add checks that apply to all values. You can put this anywhere in the hash
block, and can call it any number of times with any number of arguments.
.IP \fBend()\fR 4
.IX Item "end()"
Enforce that no keys are found in the hash other than those specified. This is
essentially the \f(CW\*(C`use strict\*(C'\fR of a hash check. This can be used anywhere in the
hash builder, though typically it is placed at the end.
.IP \fBetc()\fR 4
.IX Item "etc()"
Ignore any extra keys found in the hash. This is the opposite of \f(CWend()\fR.
This can be used anywhere in the hash builder, though typically it is placed at
the end.
.IP \fBDNE()\fR 4
.IX Item "DNE()"
This is a handy check that can be used with \f(CWfield()\fR to ensure that a field
(D)oes (N)ot (E)xist.
.Sp
.Vb 1
\&    field foo => DNE();
.Ve
.SS "ARRAY BUILDER"
.IX Subsection "ARRAY BUILDER"
\&\fBNote: None of these are exported by default. You need to request them.\fR
.PP
.Vb 3
\&    $check = array {
\&        # Uses the next index, in this case index 0;
\&        item \*(Aqa\*(Aq;
\&
\&        # Gets index 1 automatically
\&        item \*(Aqb\*(Aq;
\&
\&        # Specify the index
\&        item 2 => \*(Aqc\*(Aq;
\&
\&        # We skipped index 3, which means we don\*(Aqt care what it is.
\&        item 4 => \*(Aqe\*(Aq;
\&
\&        # Gets index 5.
\&        item \*(Aqf\*(Aq;
\&
\&        # Remove any REMAINING items that contain 0\-9.
\&        filter_items { grep {!m/[0\-9]/} @_ };
\&
\&        # Set checks that apply to all items. Can be done multiple times, and
\&        # each call can define multiple checks, all will be run.
\&        all_items match qr/a/, match qr/b/;
\&        all_items match qr/x/;
\&
\&        # Of the remaining items (after the filter is applied) the next one
\&        # (which is now index 6) should be \*(Aqg\*(Aq.
\&        item 6 => \*(Aqg\*(Aq;
\&
\&        item 7 => DNE; # Ensure index 7 does not exist.
\&
\&        end(); # Ensure no other indexes exist.
\&    };
.Ve
.ie n .IP "$check = array { ... }" 4
.el .IP "\f(CW$check\fR = array { ... }" 4
.IX Item "$check = array { ... }"
.PD 0
.ie n .IP "item $VAL" 4
.el .IP "item \f(CW$VAL\fR" 4
.IX Item "item $VAL"
.ie n .IP "item $CHECK" 4
.el .IP "item \f(CW$CHECK\fR" 4
.IX Item "item $CHECK"
.ie n .IP "item $IDX, $VAL" 4
.el .IP "item \f(CW$IDX\fR, \f(CW$VAL\fR" 4
.IX Item "item $IDX, $VAL"
.ie n .IP "item $IDX, $CHECK" 4
.el .IP "item \f(CW$IDX\fR, \f(CW$CHECK\fR" 4
.IX Item "item $IDX, $CHECK"
.PD
Add an expected item to the array. If \f(CW$IDX\fR is not specified it will
automatically calculate it based on the last item added. You can skip indexes,
which means you do not want them to be checked.
.Sp
You can provide any value to check in \f(CW$VAL\fR, or you can provide any valid
check object.
.Sp
\&\fBNote:\fR Items MUST be added in order.
.Sp
\&\fBNote:\fR This function can only be used inside an array, bag or subset
builder sub, and must be called in void context.
.ie n .IP "filter_items { my @remaining = @_; ...; return @filtered }" 4
.el .IP "filter_items { my \f(CW@remaining\fR = \f(CW@_\fR; ...; return \f(CW@filtered\fR }" 4
.IX Item "filter_items { my @remaining = @_; ...; return @filtered }"
This function adds a filter, all items remaining in the array from the point
the filter is reached will be passed into the filter sub as arguments, the sub
should return only the items that should be checked.
.Sp
\&\fBNote:\fR This function can only be used inside an array builder sub, and must
be called in void context.
.ie n .IP "all_items($CHECK1, $CHECK2, ...)" 4
.el .IP "all_items($CHECK1, \f(CW$CHECK2\fR, ...)" 4
.IX Item "all_items($CHECK1, $CHECK2, ...)"
Add checks that apply to all items. You can put this anywhere in the array
block, and can call it any number of times with any number of arguments.
.IP \fBend()\fR 4
.IX Item "end()"
Enforce that there are no indexes after the last one specified. This will not
force checking of skipped indexes.
.IP \fBetc()\fR 4
.IX Item "etc()"
Ignore any extra items found in the array. This is the opposite of \f(CWend()\fR.
This can be used anywhere in the array builder, though typically it is placed
at the end.
.IP \fBDNE()\fR 4
.IX Item "DNE()"
This is a handy check that can be used with \f(CWitem()\fR to ensure that an index
(D)oes (N)ot (E)xist.
.Sp
.Vb 1
\&    item 5 => DNE();
.Ve
.SS "BAG BUILDER"
.IX Subsection "BAG BUILDER"
\&\fBNote: None of these are exported by default. You need to request them.\fR
.PP
.Vb 3
\&    $check = bag {
\&        item \*(Aqa\*(Aq;
\&        item \*(Aqb\*(Aq;
\&
\&        end(); # Ensure no other elements exist.
\&    };
.Ve
.PP
A bag is like an array, but we don't care about the order of the
items. In the example, \f(CW$check\fR would match both \f(CW\*(C`[\*(Aqa\*(Aq,\*(Aqb\*(Aq]\*(C'\fR and
\&\f(CW\*(C`[\*(Aqb\*(Aq,\*(Aqa\*(Aq]\*(C'\fR.
.ie n .IP "$check = bag { ... }" 4
.el .IP "\f(CW$check\fR = bag { ... }" 4
.IX Item "$check = bag { ... }"
.PD 0
.ie n .IP "item $VAL" 4
.el .IP "item \f(CW$VAL\fR" 4
.IX Item "item $VAL"
.ie n .IP "item $CHECK" 4
.el .IP "item \f(CW$CHECK\fR" 4
.IX Item "item $CHECK"
.PD
Add an expected item to the bag.
.Sp
You can provide any value to check in \f(CW$VAL\fR, or you can provide any valid
check object.
.Sp
\&\fBNote:\fR This function can only be used inside an array, bag or subset
builder sub, and must be called in void context.
.ie n .IP "all_items($CHECK1, $CHECK2, ...)" 4
.el .IP "all_items($CHECK1, \f(CW$CHECK2\fR, ...)" 4
.IX Item "all_items($CHECK1, $CHECK2, ...)"
Add checks that apply to all items. You can put this anywhere in the bag
block, and can call it any number of times with any number of arguments.
.IP \fBend()\fR 4
.IX Item "end()"
Enforce that there are no more items after the last one specified.
.IP \fBetc()\fR 4
.IX Item "etc()"
Ignore any extra items found in the array. This is the opposite of \f(CWend()\fR.
This can be used anywhere in the bag builder, though typically it is placed
at the end.
.SS "ORDERED SUBSET BUILDER"
.IX Subsection "ORDERED SUBSET BUILDER"
\&\fBNote: None of these are exported by default. You need to request them.\fR
.PP
.Vb 4
\&    $check = subset {
\&        item \*(Aqa\*(Aq;
\&        item \*(Aqb\*(Aq;
\&        item \*(Aqc\*(Aq;
\&
\&        # Doesn\*(Aqt matter if the array has \*(Aqd\*(Aq, the check will skip past any
\&        # unknown items until it finds the next one in our subset.
\&
\&        item \*(Aqe\*(Aq;
\&        item \*(Aqf\*(Aq;
\&    };
.Ve
.ie n .IP "$check = subset { ... }" 4
.el .IP "\f(CW$check\fR = subset { ... }" 4
.IX Item "$check = subset { ... }"
.PD 0
.ie n .IP "item $VAL" 4
.el .IP "item \f(CW$VAL\fR" 4
.IX Item "item $VAL"
.ie n .IP "item $CHECK" 4
.el .IP "item \f(CW$CHECK\fR" 4
.IX Item "item $CHECK"
.PD
Add an expected item to the subset.
.Sp
You can provide any value to check in \f(CW$VAL\fR, or you can provide any valid
check object.
.Sp
\&\fBNote:\fR Items MUST be added in order.
.Sp
\&\fBNote:\fR This function can only be used inside an array, bag or subset
builder sub, and must be called in void context.
.SS "META BUILDER"
.IX Subsection "META BUILDER"
\&\fBNote: None of these are exported by default. You need to request them.\fR
.PP
.Vb 7
\&    my $check = meta {
\&        prop blessed => \*(AqMy::Module\*(Aq; # Ensure value is blessed as our package
\&        prop reftype => \*(AqHASH\*(Aq;       # Ensure value is a blessed hash
\&        prop isa     => \*(AqMy::Base\*(Aq;   # Ensure value is an instance of our class
\&        prop size    => 4;            # Check the number of hash keys
\&        prop this    => ...;          # Check the item itself
\&    };
.Ve
.IP "meta { ... }" 4
.IX Item "meta { ... }"
.PD 0
.IP "meta_check { ... }" 4
.IX Item "meta_check { ... }"
.PD
Build a meta check. If you are using Moose then the \f(CWmeta()\fR function would
conflict with the one exported by Moose, in such cases \f(CWmeta_check()\fR is
available. Neither is exported by default.
.ie n .IP "prop $NAME => $VAL" 4
.el .IP "prop \f(CW$NAME\fR => \f(CW$VAL\fR" 4
.IX Item "prop $NAME => $VAL"
.PD 0
.ie n .IP "prop $NAME => $CHECK" 4
.el .IP "prop \f(CW$NAME\fR => \f(CW$CHECK\fR" 4
.IX Item "prop $NAME => $CHECK"
.PD
Check the property specified by \f(CW$name\fR against the value or check.
.Sp
Valid properties are:
.RS 4
.IP 'blessed' 4
.IX Item "'blessed'"
What package (if any) the thing is blessed as.
.IP 'reftype' 4
.IX Item "'reftype'"
Reference type (if any) the thing is.
.IP 'isa' 4
.IX Item "'isa'"
What class the thing is an instance of.
.IP 'this' 4
.IX Item "'this'"
The thing itself.
.IP 'size' 4
.IX Item "'size'"
For array references this returns the number of elements. For hashes this
returns the number of keys. For everything else this returns undef.
.RE
.RS 4
.RE
.SS "OBJECT BUILDER"
.IX Subsection "OBJECT BUILDER"
\&\fBNote: None of these are exported by default. You need to request them.\fR
.PP
.Vb 2
\&    my $check = object {
\&        call foo => 1; # Call the \*(Aqfoo\*(Aq method, check the result.
\&
\&        # Call the specified sub\-ref as a method on the object, check the
\&        # result. This is useful for wrapping methods that return multiple
\&        # values.
\&        call sub { [ shift\->get_list ] } => [...];
\&
\&        # This can be used to ensure a method does not exist.
\&        call nope => DNE();
\&
\&        # Check the hash key \*(Aqfoo\*(Aq of the underlying reference, this only works
\&        # on blessed hashes.
\&        field foo => 1;
\&
\&        # Check the value of index 4 on the underlying reference, this only
\&        # works on blessed arrays.
\&        item 4 => \*(Aqfoo\*(Aq;
\&
\&        # Check the meta\-property \*(Aqblessed\*(Aq of the object.
\&        prop blessed => \*(AqMy::Module\*(Aq;
\&
\&        # Check if the object is an instance of the specified class.
\&        prop isa => \*(AqMy::Base\*(Aq;
\&
\&        # Ensure only the specified hash keys or array indexes are present in
\&        # the underlying hash. Has no effect on meta\-property checks or method
\&        # checks.
\&        end();
\&    };
.Ve
.ie n .IP "$check = object { ... }" 4
.el .IP "\f(CW$check\fR = object { ... }" 4
.IX Item "$check = object { ... }"
Specify an object check for use in comparisons.
.ie n .IP "call $METHOD_NAME => $RESULT" 4
.el .IP "call \f(CW$METHOD_NAME\fR => \f(CW$RESULT\fR" 4
.IX Item "call $METHOD_NAME => $RESULT"
.PD 0
.ie n .IP "call $METHOD_NAME => $CHECK" 4
.el .IP "call \f(CW$METHOD_NAME\fR => \f(CW$CHECK\fR" 4
.IX Item "call $METHOD_NAME => $CHECK"
.ie n .IP "call [$METHOD_NAME, @METHOD_ARGS] => $RESULT" 4
.el .IP "call [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$RESULT\fR" 4
.IX Item "call [$METHOD_NAME, @METHOD_ARGS] => $RESULT"
.ie n .IP "call [$METHOD_NAME, @METHOD_ARGS] => $CHECK" 4
.el .IP "call [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$CHECK\fR" 4
.IX Item "call [$METHOD_NAME, @METHOD_ARGS] => $CHECK"
.ie n .IP "call sub { ... }, $RESULT" 4
.el .IP "call sub { ... }, \f(CW$RESULT\fR" 4
.IX Item "call sub { ... }, $RESULT"
.ie n .IP "call sub { ... }, $CHECK" 4
.el .IP "call sub { ... }, \f(CW$CHECK\fR" 4
.IX Item "call sub { ... }, $CHECK"
.PD
Call the specified method (or coderef) and verify the result. If you
pass an arrayref, the first element must be the method name, the
others are the arguments it will be called with.
.Sp
The coderef form is useful if you need to do something more complex.
.Sp
.Vb 4
\&    my $ref = sub {
\&      local $SOME::GLOBAL::THING = 3;
\&      return [shift\->get_values_for(\*(Aqthing\*(Aq)];
\&    };
\&
\&    call $ref => ...;
.Ve
.ie n .IP "call_list $METHOD_NAME => $RESULT" 4
.el .IP "call_list \f(CW$METHOD_NAME\fR => \f(CW$RESULT\fR" 4
.IX Item "call_list $METHOD_NAME => $RESULT"
.PD 0
.ie n .IP "call_list $METHOD_NAME => $CHECK" 4
.el .IP "call_list \f(CW$METHOD_NAME\fR => \f(CW$CHECK\fR" 4
.IX Item "call_list $METHOD_NAME => $CHECK"
.ie n .IP "call_list [$METHOD_NAME, @METHOD_ARGS] => $RESULT" 4
.el .IP "call_list [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$RESULT\fR" 4
.IX Item "call_list [$METHOD_NAME, @METHOD_ARGS] => $RESULT"
.ie n .IP "call_list [$METHOD_NAME, @METHOD_ARGS] => $CHECK" 4
.el .IP "call_list [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$CHECK\fR" 4
.IX Item "call_list [$METHOD_NAME, @METHOD_ARGS] => $CHECK"
.ie n .IP "call_list sub { ... }, $RESULT" 4
.el .IP "call_list sub { ... }, \f(CW$RESULT\fR" 4
.IX Item "call_list sub { ... }, $RESULT"
.ie n .IP "call_list sub { ... }, $CHECK" 4
.el .IP "call_list sub { ... }, \f(CW$CHECK\fR" 4
.IX Item "call_list sub { ... }, $CHECK"
.PD
Same as \f(CW\*(C`call\*(C'\fR, but the method is invoked in list context, and the
result is always an arrayref.
.Sp
.Vb 1
\&    call_list get_items => [ ... ];
.Ve
.ie n .IP "call_hash $METHOD_NAME => $RESULT" 4
.el .IP "call_hash \f(CW$METHOD_NAME\fR => \f(CW$RESULT\fR" 4
.IX Item "call_hash $METHOD_NAME => $RESULT"
.PD 0
.ie n .IP "call_hash $METHOD_NAME => $CHECK" 4
.el .IP "call_hash \f(CW$METHOD_NAME\fR => \f(CW$CHECK\fR" 4
.IX Item "call_hash $METHOD_NAME => $CHECK"
.ie n .IP "call_hash [$METHOD_NAME, @METHOD_ARGS] => $RESULT" 4
.el .IP "call_hash [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$RESULT\fR" 4
.IX Item "call_hash [$METHOD_NAME, @METHOD_ARGS] => $RESULT"
.ie n .IP "call_hash [$METHOD_NAME, @METHOD_ARGS] => $CHECK" 4
.el .IP "call_hash [$METHOD_NAME, \f(CW@METHOD_ARGS\fR] => \f(CW$CHECK\fR" 4
.IX Item "call_hash [$METHOD_NAME, @METHOD_ARGS] => $CHECK"
.ie n .IP "call_hash sub { ... }, $RESULT" 4
.el .IP "call_hash sub { ... }, \f(CW$RESULT\fR" 4
.IX Item "call_hash sub { ... }, $RESULT"
.ie n .IP "call_hash sub { ... }, $CHECK" 4
.el .IP "call_hash sub { ... }, \f(CW$CHECK\fR" 4
.IX Item "call_hash sub { ... }, $CHECK"
.PD
Same as \f(CW\*(C`call\*(C'\fR, but the method is invoked in list context, and the
result is always a hashref. This will warn if the method returns an
odd number of values.
.Sp
.Vb 1
\&    call_hash get_items => { ... };
.Ve
.ie n .IP "field $NAME => $VAL" 4
.el .IP "field \f(CW$NAME\fR => \f(CW$VAL\fR" 4
.IX Item "field $NAME => $VAL"
Works just like it does for hash checks.
.ie n .IP "item $VAL" 4
.el .IP "item \f(CW$VAL\fR" 4
.IX Item "item $VAL"
.PD 0
.ie n .IP "item $IDX, $VAL" 4
.el .IP "item \f(CW$IDX\fR, \f(CW$VAL\fR" 4
.IX Item "item $IDX, $VAL"
.PD
Works just like it does for array checks.
.ie n .IP "prop $NAME => $VAL" 4
.el .IP "prop \f(CW$NAME\fR => \f(CW$VAL\fR" 4
.IX Item "prop $NAME => $VAL"
.PD 0
.ie n .IP "prop $NAME => $CHECK" 4
.el .IP "prop \f(CW$NAME\fR => \f(CW$CHECK\fR" 4
.IX Item "prop $NAME => $CHECK"
.PD
Check the property specified by \f(CW$name\fR against the value or check.
.Sp
Valid properties are:
.RS 4
.IP 'blessed' 4
.IX Item "'blessed'"
What package (if any) the thing is blessed as.
.IP 'reftype' 4
.IX Item "'reftype'"
Reference type (if any) the thing is.
.IP 'isa' 4
.IX Item "'isa'"
What class the thing is an instance of.
.IP 'this' 4
.IX Item "'this'"
The thing itself.
.IP 'size' 4
.IX Item "'size'"
For array references this returns the number of elements. For hashes this
returns the number of keys. For everything else this returns undef.
.RE
.RS 4
.RE
.IP \fBDNE()\fR 4
.IX Item "DNE()"
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
does not exist. Can also be used with \f(CW\*(C`call\*(C'\fR to ensure a method does not
exist.
.IP \fBend()\fR 4
.IX Item "end()"
Turn on strict array/hash checking, ensuring that no extra keys/indexes
are present.
.IP \fBetc()\fR 4
.IX Item "etc()"
Ignore any extra items found in the hash/array. This is the opposite of
\&\f(CWend()\fR.  This can be used anywhere in the builder, though typically it is
placed at the end.
.SS "EVENT BUILDERS"
.IX Subsection "EVENT BUILDERS"
\&\fBNote: None of these are exported by default. You need to request them.\fR
.PP
Check that we got an event of a specified type:
.PP
.Vb 1
\&    my $check = event \*(AqOk\*(Aq;
.Ve
.PP
Check for details about the event:
.PP
.Vb 3
\&    my $check = event Ok => sub {
\&        # Check for a failure
\&        call pass => 0;
\&
\&        # Effective pass after TODO/SKIP are accounted for.
\&        call effective_pass => 1;
\&
\&        # Check the diagnostics
\&        call diag => [ match qr/Failed test foo/ ];
\&
\&        # Check the file the event reports to
\&        prop file => \*(Aqfoo.t\*(Aq;
\&
\&        # Check the line number the event reports to
\&        prop line => \*(Aq42\*(Aq;
\&
\&        # You can check the todo/skip values as well:
\&        prop skip => \*(Aqbroken\*(Aq;
\&        prop todo => \*(Aqfixme\*(Aq;
\&
\&        # Thread\-id and process\-id where event was generated
\&        prop tid => 123;
\&        prop pid => 123;
\&    };
.Ve
.PP
You can also provide a fully qualified event package with the '+' prefix:
.PP
.Vb 1
\&    my $check = event \*(Aq+My::Event\*(Aq => sub { ... }
.Ve
.PP
You can also provide a hashref instead of a sub to directly check hash values
of the event:
.PP
.Vb 1
\&    my $check = event Ok => { pass => 1, ... };
.Ve
.PP
\fIUSE IN OTHER BUILDERS\fR
.IX Subsection "USE IN OTHER BUILDERS"
.PP
You can use these all in other builders, simply use them in void context to
have their value(s) appended to the build.
.PP
.Vb 3
\&    my $check = array {
\&        event Ok => { ... };
\&        event Note => { ... };
\&
\&        fail_events Ok => { pass => 0 };
\&        # Get a Diag for free.
\&    };
.Ve
.PP
\fISPECIFICS\fR
.IX Subsection "SPECIFICS"
.ie n .IP "$check = event $TYPE;" 4
.el .IP "\f(CW$check\fR = event \f(CW$TYPE\fR;" 4
.IX Item "$check = event $TYPE;"
.PD 0
.ie n .IP "$check = event $TYPE => sub { ... };" 4
.el .IP "\f(CW$check\fR = event \f(CW$TYPE\fR => sub { ... };" 4
.IX Item "$check = event $TYPE => sub { ... };"
.ie n .IP "$check = event $TYPE => { ... };" 4
.el .IP "\f(CW$check\fR = event \f(CW$TYPE\fR => { ... };" 4
.IX Item "$check = event $TYPE => { ... };"
.PD
This works just like an object builder. In addition to supporting everything
the object check supports, you also have to specify the event type, and many
extra meta-properties are available.
.Sp
Extra properties are:
.RS 4
.IP 'file' 4
.IX Item "'file'"
File name to which the event reports (for use in diagnostics).
.IP 'line' 4
.IX Item "'line'"
Line number to which the event reports (for use in diagnostics).
.IP 'package' 4
.IX Item "'package'"
Package to which the event reports (for use in diagnostics).
.IP 'subname' 4
.IX Item "'subname'"
Sub that was called to generate the event (example: \f(CWok()\fR).
.IP 'skip' 4
.IX Item "'skip'"
Set to the skip value if the result was generated by skipping tests.
.IP 'todo' 4
.IX Item "'todo'"
Set to the todo value if TODO was set when the event was generated.
.IP 'trace' 4
.IX Item "'trace'"
The \f(CW\*(C`at file foo.t line 42\*(C'\fR string that will be used in diagnostics.
.IP 'tid' 4
.IX Item "'tid'"
Thread ID in which the event was generated.
.IP 'pid' 4
.IX Item "'pid'"
Process ID in which the event was generated.
.RE
.RS 4
.Sp
\&\fBNOTE\fR: Event checks have an implicit \f(CWetc()\fR added. This means you need to
use \f(CWend()\fR if you want to fail on unexpected hash keys or array indexes. This
implicit \f(CWetc()\fR extends to all forms, including builder, hashref, and no
argument.
.RE
.ie n .IP "@checks = fail_events $TYPE;" 4
.el .IP "\f(CW@checks\fR = fail_events \f(CW$TYPE\fR;" 4
.IX Item "@checks = fail_events $TYPE;"
.PD 0
.ie n .IP "@checks = fail_events $TYPE => sub { ... };" 4
.el .IP "\f(CW@checks\fR = fail_events \f(CW$TYPE\fR => sub { ... };" 4
.IX Item "@checks = fail_events $TYPE => sub { ... };"
.ie n .IP "@checks = fail_events $TYPE => { ... };" 4
.el .IP "\f(CW@checks\fR = fail_events \f(CW$TYPE\fR => { ... };" 4
.IX Item "@checks = fail_events $TYPE => { ... };"
.PD
Just like \f(CWevent()\fR documented above. The difference is that this produces two
events, the one you specify, and a \f(CW\*(C`Diag\*(C'\fR after it. There are no extra checks
in the Diag.
.Sp
Use this to validate a simple failure where you do not want to be bothered with
the default diagnostics. It only adds a single Diag check, so if your failure
has custom diagnostics you will need to add checks for them.
.SH SOURCE
.IX Header "SOURCE"
The source code repository for Test2\-Suite can be found at
\&\fIhttps://github.com/Test\-More/Test2\-Suite/\fR.
.SH MAINTAINERS
.IX Header "MAINTAINERS"
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.SH AUTHORS
.IX Header "AUTHORS"
.PD 0
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.PD
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2018 Chad Granum <exodist@cpan.org>.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.PP
See \fIhttp://dev.perl.org/licenses/\fR