.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Test2::Compare::Delta 3pm"
.TH Test2::Compare::Delta 3pm "2019-05-06" "perl v5.24.1" "User Contributed Perl Documentation"
.\" 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::Compare::Delta \- Representation of differences between nested data
structures.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is used by Test2::Compare. When data structures are compared a
delta will be returned. Deltas are a tree data structure that represent all the
differences between two other data structures.
.SH "METHODS"
.IX Header "METHODS"
.SS "\s-1CLASS METHODS\s0"
.IX Subsection "CLASS METHODS"
.ie n .IP "$class\->add_column($NAME => sub { ... })" 4
.el .IP "\f(CW$class\fR\->add_column($NAME => sub { ... })" 4
.IX Item "$class->add_column($NAME => sub { ... })"
.PD 0
.ie n .IP "$class\->add_column($NAME, %PARAMS)" 4
.el .IP "\f(CW$class\fR\->add_column($NAME, \f(CW%PARAMS\fR)" 4
.IX Item "$class->add_column($NAME, %PARAMS)"
.PD
This can be used to add columns to the table that it produced when a comparison
fails. The first argument should always be the column name, which must be
unique.
.Sp
The first form simply takes a coderef that produces the value that should be
displayed in the column for any given delta. The arguments passed into the sub
are the delta, and the row \s-1ID.\s0
.Sp
.Vb 6
\&    Test2::Compare::Delta\->add_column(
\&        Foo => sub {
\&            my ($delta, $id) = @_;
\&            return $delta\->... ? \*(Aqfoo\*(Aq : \*(Aqbar\*(Aq
\&        },
\&    );
.Ve
.Sp
The second form allows you some extra options. The \f(CW\*(Aqvalue\*(Aq\fR key is required,
and must be a coderef. All other keys are optional.
.Sp
.Vb 6
\&    Test2::Compare::Delta\->add_column(
\&        \*(AqFoo\*(Aq,    # column name
\&        value => sub { ... },    # how to get the cell value
\&        alias       => \*(AqFOO\*(Aq,    # Display name (used in table header)
\&        no_collapse => $bool,    # Show column even if it has no values?
\&    );
.Ve
.ie n .IP "$bool = $class\->remove_column($NAME)" 4
.el .IP "\f(CW$bool\fR = \f(CW$class\fR\->remove_column($NAME)" 4
.IX Item "$bool = $class->remove_column($NAME)"
This will remove the specified column. This will return true if the column
existed and was removed. This will return false if the column did not exist. No
exceptions are thrown. If a missing column is a problem then you need to check
the return yourself.
.ie n .IP "$class\->set_column_alias($NAME, $ALIAS)" 4
.el .IP "\f(CW$class\fR\->set_column_alias($NAME, \f(CW$ALIAS\fR)" 4
.IX Item "$class->set_column_alias($NAME, $ALIAS)"
This can be used to change the table header, overriding the default column
names with new ones.
.SS "\s-1ATTRIBUTES\s0"
.IX Subsection "ATTRIBUTES"
.ie n .IP "$bool = $delta\->verified" 4
.el .IP "\f(CW$bool\fR = \f(CW$delta\fR\->verified" 4
.IX Item "$bool = $delta->verified"
.PD 0
.ie n .IP "$delta\->set_verified($bool)" 4
.el .IP "\f(CW$delta\fR\->set_verified($bool)" 4
.IX Item "$delta->set_verified($bool)"
.PD
This will be true if the delta itself matched, if the delta matched then the
problem is in the delta's children, not the delta itself.
.ie n .IP "$aref = $delta\->id" 4
.el .IP "\f(CW$aref\fR = \f(CW$delta\fR\->id" 4
.IX Item "$aref = $delta->id"
.PD 0
.ie n .IP "$delta\->set_id([$type, $name])" 4
.el .IP "\f(CW$delta\fR\->set_id([$type, \f(CW$name\fR])" 4
.IX Item "$delta->set_id([$type, $name])"
.PD
\&\s-1ID\s0 for the delta, used to produce the path into the data structure. An
example is \f(CW\*(C`[\*(AqHASH\*(Aq => \*(Aqfoo\*(Aq]\*(C'\fR which means the delta is in the path
\&\f(CW\*(C`...\->{\*(Aqfoo\*(Aq}\*(C'\fR. Valid types are \f(CW\*(C`HASH\*(C'\fR, \f(CW\*(C`ARRAY\*(C'\fR, \f(CW\*(C`SCALAR\*(C'\fR, \f(CW\*(C`META\*(C'\fR, and
\&\f(CW\*(C`METHOD\*(C'\fR.
.ie n .IP "$val = $delta\->got" 4
.el .IP "\f(CW$val\fR = \f(CW$delta\fR\->got" 4
.IX Item "$val = $delta->got"
.PD 0
.ie n .IP "$delta\->set_got($val)" 4
.el .IP "\f(CW$delta\fR\->set_got($val)" 4
.IX Item "$delta->set_got($val)"
.PD
Deltas are produced by comparing a received data structure 'got' against a
check data structure 'check'. The 'got' attribute contains the value that was
received for comparison.
.ie n .IP "$check = $delta\->chk" 4
.el .IP "\f(CW$check\fR = \f(CW$delta\fR\->chk" 4
.IX Item "$check = $delta->chk"
.PD 0
.ie n .IP "$check = $delta\->check" 4
.el .IP "\f(CW$check\fR = \f(CW$delta\fR\->check" 4
.IX Item "$check = $delta->check"
.ie n .IP "$delta\->set_chk($check)" 4
.el .IP "\f(CW$delta\fR\->set_chk($check)" 4
.IX Item "$delta->set_chk($check)"
.ie n .IP "$delta\->set_check($check)" 4
.el .IP "\f(CW$delta\fR\->set_check($check)" 4
.IX Item "$delta->set_check($check)"
.PD
Deltas are produced by comparing a received data structure 'got' against a
check data structure 'check'. The 'check' attribute contains the value that was
expected in the comparison.
.Sp
\&\f(CW\*(C`check\*(C'\fR and \f(CW\*(C`chk\*(C'\fR are aliases for the same attribute.
.ie n .IP "$aref = $delta\->children" 4
.el .IP "\f(CW$aref\fR = \f(CW$delta\fR\->children" 4
.IX Item "$aref = $delta->children"
.PD 0
.ie n .IP "$delta\->set_children([$delta1, $delta2, ...])" 4
.el .IP "\f(CW$delta\fR\->set_children([$delta1, \f(CW$delta2\fR, ...])" 4
.IX Item "$delta->set_children([$delta1, $delta2, ...])"
.PD
A Delta may have child deltas. If it does then this is an arrayref with those
children.
.ie n .IP "$dne = $delta\->dne" 4
.el .IP "\f(CW$dne\fR = \f(CW$delta\fR\->dne" 4
.IX Item "$dne = $delta->dne"
.PD 0
.ie n .IP "$delta\->set_dne($dne)" 4
.el .IP "\f(CW$delta\fR\->set_dne($dne)" 4
.IX Item "$delta->set_dne($dne)"
.PD
Sometimes a comparison results in one side or the other not existing at all, in
which case this is set to the name of the attribute that does not exist. This
can be set to 'got' or 'check'.
.ie n .IP "$e = $delta\->exception" 4
.el .IP "\f(CW$e\fR = \f(CW$delta\fR\->exception" 4
.IX Item "$e = $delta->exception"
.PD 0
.ie n .IP "$delta\->set_exception($e)" 4
.el .IP "\f(CW$delta\fR\->set_exception($e)" 4
.IX Item "$delta->set_exception($e)"
.PD
This will be set to the exception in cases where the comparison failed due to
an exception being thrown.
.SS "\s-1OTHER\s0"
.IX Subsection "OTHER"
.ie n .IP "$string = $delta\->render_got" 4
.el .IP "\f(CW$string\fR = \f(CW$delta\fR\->render_got" 4
.IX Item "$string = $delta->render_got"
Renders the string that should be used in a table to represent the received
value in a comparison.
.ie n .IP "$string = $delta\->render_check" 4
.el .IP "\f(CW$string\fR = \f(CW$delta\fR\->render_check" 4
.IX Item "$string = $delta->render_check"
Renders the string that should be used in a table to represent the expected
value in a comparison.
.ie n .IP "$bool = $delta\->should_show" 4
.el .IP "\f(CW$bool\fR = \f(CW$delta\fR\->should_show" 4
.IX Item "$bool = $delta->should_show"
This will return true if the delta should be shown in the table. This is
normally true for any unverified delta. This will also be true for deltas that
contain extra useful debug information.
.ie n .IP "$aref = $delta\->filter_visible" 4
.el .IP "\f(CW$aref\fR = \f(CW$delta\fR\->filter_visible" 4
.IX Item "$aref = $delta->filter_visible"
This will produce an arrayref of \f(CW\*(C`[ $path => $delta ]\*(C'\fR for all deltas that
should be displayed in the table.
.ie n .IP "$aref = $delta\->table_header" 4
.el .IP "\f(CW$aref\fR = \f(CW$delta\fR\->table_header" 4
.IX Item "$aref = $delta->table_header"
This returns an array ref of the headers for the table.
.ie n .IP "$string = $delta\->table_op" 4
.el .IP "\f(CW$string\fR = \f(CW$delta\fR\->table_op" 4
.IX Item "$string = $delta->table_op"
This returns the operator that should be shown in the table.
.ie n .IP "$string = $delta\->table_check_lines" 4
.el .IP "\f(CW$string\fR = \f(CW$delta\fR\->table_check_lines" 4
.IX Item "$string = $delta->table_check_lines"
This returns the defined lines (extra debug info) that should be displayed.
.ie n .IP "$string = $delta\->table_got_lines" 4
.el .IP "\f(CW$string\fR = \f(CW$delta\fR\->table_got_lines" 4
.IX Item "$string = $delta->table_got_lines"
This returns the generated lines (extra debug info) that should be displayed.
.ie n .IP "$aref = $delta\->table_rows" 4
.el .IP "\f(CW$aref\fR = \f(CW$delta\fR\->table_rows" 4
.IX Item "$aref = $delta->table_rows"
This returns an arrayref of table rows, each row is itself an arrayref.
.ie n .IP "@table_lines = $delta\->table" 4
.el .IP "\f(CW@table_lines\fR = \f(CW$delta\fR\->table" 4
.IX Item "@table_lines = $delta->table"
Returns all the lines of the table that should be displayed.
.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