Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::Compare::Delta.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::Compare::Delta 3pm"
61 .TH Test2::Compare::Delta 3pm 2025-06-24 "perl v5.42.0" "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::Compare::Delta \- Representation of differences between nested data
68 structures.
69 .SH DESCRIPTION
70 .IX Header "DESCRIPTION"
71 This is used by Test2::Compare. When data structures are compared a
72 delta will be returned. Deltas are a tree data structure that represent all the
73 differences between two other data structures.
74 .SH METHODS
75 .IX Header "METHODS"
76 .SS "CLASS METHODS"
77 .IX Subsection "CLASS METHODS"
78 .ie n .IP "$class\->add_column($NAME => sub { ... })" 4
79 .el .IP "\f(CW$class\fR\->add_column($NAME => sub { ... })" 4
80 .IX Item "$class->add_column($NAME => sub { ... })"
81 .PD 0
82 .ie n .IP "$class\->add_column($NAME, %PARAMS)" 4
83 .el .IP "\f(CW$class\fR\->add_column($NAME, \f(CW%PARAMS\fR)" 4
84 .IX Item "$class->add_column($NAME, %PARAMS)"
85 .PD
86 This can be used to add columns to the table that it produced when a comparison
87 fails. The first argument should always be the column name, which must be
88 unique.
89 .Sp
90 The first form simply takes a coderef that produces the value that should be
91 displayed in the column for any given delta. The arguments passed into the sub
92 are the delta, and the row ID.
93 .Sp
94 .Vb 6
95 \& Test2::Compare::Delta\->add_column(
96 \& Foo => sub {
97 \& my ($delta, $id) = @_;
98 \& return $delta\->... ? \*(Aqfoo\*(Aq : \*(Aqbar\*(Aq
99 \& },
100 \& );
101 .Ve
102 .Sp
103 The second form allows you some extra options. The \f(CW\*(Aqvalue\*(Aq\fR key is required,
104 and must be a coderef. All other keys are optional.
105 .Sp
106 .Vb 6
107 \& Test2::Compare::Delta\->add_column(
108 \& \*(AqFoo\*(Aq, # column name
109 \& value => sub { ... }, # how to get the cell value
110 \& alias => \*(AqFOO\*(Aq, # Display name (used in table header)
111 \& no_collapse => $bool, # Show column even if it has no values?
112 \& );
113 .Ve
114 .ie n .IP "$bool = $class\->remove_column($NAME)" 4
115 .el .IP "\f(CW$bool\fR = \f(CW$class\fR\->remove_column($NAME)" 4
116 .IX Item "$bool = $class->remove_column($NAME)"
117 This will remove the specified column. This will return true if the column
118 existed and was removed. This will return false if the column did not exist. No
119 exceptions are thrown. If a missing column is a problem then you need to check
120 the return yourself.
121 .ie n .IP "$class\->set_column_alias($NAME, $ALIAS)" 4
122 .el .IP "\f(CW$class\fR\->set_column_alias($NAME, \f(CW$ALIAS\fR)" 4
123 .IX Item "$class->set_column_alias($NAME, $ALIAS)"
124 This can be used to change the table header, overriding the default column
125 names with new ones.
126 .SS ATTRIBUTES
127 .IX Subsection "ATTRIBUTES"
128 .ie n .IP "$bool = $delta\->verified" 4
129 .el .IP "\f(CW$bool\fR = \f(CW$delta\fR\->verified" 4
130 .IX Item "$bool = $delta->verified"
131 .PD 0
132 .ie n .IP $delta\->set_verified($bool) 4
133 .el .IP \f(CW$delta\fR\->set_verified($bool) 4
134 .IX Item "$delta->set_verified($bool)"
135 .PD
136 This will be true if the delta itself matched, if the delta matched then the
137 problem is in the delta\*(Aqs children, not the delta itself.
138 .ie n .IP "$aref = $delta\->id" 4
139 .el .IP "\f(CW$aref\fR = \f(CW$delta\fR\->id" 4
140 .IX Item "$aref = $delta->id"
141 .PD 0
142 .ie n .IP "$delta\->set_id([$type, $name])" 4
143 .el .IP "\f(CW$delta\fR\->set_id([$type, \f(CW$name\fR])" 4
144 .IX Item "$delta->set_id([$type, $name])"
145 .PD
146 ID for the delta, used to produce the path into the data structure. An
147 example is \f(CW\*(C`[\*(AqHASH\*(Aq => \*(Aqfoo\*(Aq]\*(C'\fR which means the delta is in the path
148 \&\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
149 \&\f(CW\*(C`METHOD\*(C'\fR.
150 .ie n .IP "$val = $delta\->got" 4
151 .el .IP "\f(CW$val\fR = \f(CW$delta\fR\->got" 4
152 .IX Item "$val = $delta->got"
153 .PD 0
154 .ie n .IP $delta\->set_got($val) 4
155 .el .IP \f(CW$delta\fR\->set_got($val) 4
156 .IX Item "$delta->set_got($val)"
157 .PD
158 Deltas are produced by comparing a received data structure \*(Aqgot\*(Aq against a
159 check data structure \*(Aqcheck\*(Aq. The \*(Aqgot\*(Aq attribute contains the value that was
160 received for comparison.
161 .ie n .IP "$check = $delta\->chk" 4
162 .el .IP "\f(CW$check\fR = \f(CW$delta\fR\->chk" 4
163 .IX Item "$check = $delta->chk"
164 .PD 0
165 .ie n .IP "$check = $delta\->check" 4
166 .el .IP "\f(CW$check\fR = \f(CW$delta\fR\->check" 4
167 .IX Item "$check = $delta->check"
168 .ie n .IP $delta\->set_chk($check) 4
169 .el .IP \f(CW$delta\fR\->set_chk($check) 4
170 .IX Item "$delta->set_chk($check)"
171 .ie n .IP $delta\->set_check($check) 4
172 .el .IP \f(CW$delta\fR\->set_check($check) 4
173 .IX Item "$delta->set_check($check)"
174 .PD
175 Deltas are produced by comparing a received data structure \*(Aqgot\*(Aq against a
176 check data structure \*(Aqcheck\*(Aq. The \*(Aqcheck\*(Aq attribute contains the value that was
177 expected in the comparison.
178 .Sp
179 \&\f(CW\*(C`check\*(C'\fR and \f(CW\*(C`chk\*(C'\fR are aliases for the same attribute.
180 .ie n .IP "$aref = $delta\->children" 4
181 .el .IP "\f(CW$aref\fR = \f(CW$delta\fR\->children" 4
182 .IX Item "$aref = $delta->children"
183 .PD 0
184 .ie n .IP "$delta\->set_children([$delta1, $delta2, ...])" 4
185 .el .IP "\f(CW$delta\fR\->set_children([$delta1, \f(CW$delta2\fR, ...])" 4
186 .IX Item "$delta->set_children([$delta1, $delta2, ...])"
187 .PD
188 A Delta may have child deltas. If it does then this is an arrayref with those
189 children.
190 .ie n .IP "$dne = $delta\->dne" 4
191 .el .IP "\f(CW$dne\fR = \f(CW$delta\fR\->dne" 4
192 .IX Item "$dne = $delta->dne"
193 .PD 0
194 .ie n .IP $delta\->set_dne($dne) 4
195 .el .IP \f(CW$delta\fR\->set_dne($dne) 4
196 .IX Item "$delta->set_dne($dne)"
197 .PD
198 Sometimes a comparison results in one side or the other not existing at all, in
199 which case this is set to the name of the attribute that does not exist. This
200 can be set to \*(Aqgot\*(Aq or \*(Aqcheck\*(Aq.
201 .ie n .IP "$e = $delta\->exception" 4
202 .el .IP "\f(CW$e\fR = \f(CW$delta\fR\->exception" 4
203 .IX Item "$e = $delta->exception"
204 .PD 0
205 .ie n .IP $delta\->set_exception($e) 4
206 .el .IP \f(CW$delta\fR\->set_exception($e) 4
207 .IX Item "$delta->set_exception($e)"
208 .PD
209 This will be set to the exception in cases where the comparison failed due to
210 an exception being thrown.
211 .SS OTHER
212 .IX Subsection "OTHER"
213 .ie n .IP "$string = $delta\->render_got" 4
214 .el .IP "\f(CW$string\fR = \f(CW$delta\fR\->render_got" 4
215 .IX Item "$string = $delta->render_got"
216 Renders the string that should be used in a table to represent the received
217 value in a comparison.
218 .ie n .IP "$string = $delta\->render_check" 4
219 .el .IP "\f(CW$string\fR = \f(CW$delta\fR\->render_check" 4
220 .IX Item "$string = $delta->render_check"
221 Renders the string that should be used in a table to represent the expected
222 value in a comparison.
223 .ie n .IP "$bool = $delta\->should_show" 4
224 .el .IP "\f(CW$bool\fR = \f(CW$delta\fR\->should_show" 4
225 .IX Item "$bool = $delta->should_show"
226 This will return true if the delta should be shown in the table. This is
227 normally true for any unverified delta. This will also be true for deltas that
228 contain extra useful debug information.
229 .ie n .IP "$aref = $delta\->filter_visible" 4
230 .el .IP "\f(CW$aref\fR = \f(CW$delta\fR\->filter_visible" 4
231 .IX Item "$aref = $delta->filter_visible"
232 This will produce an arrayref of \f(CW\*(C`[ $path => $delta ]\*(C'\fR for all deltas that
233 should be displayed in the table.
234 .ie n .IP "$aref = $delta\->table_header" 4
235 .el .IP "\f(CW$aref\fR = \f(CW$delta\fR\->table_header" 4
236 .IX Item "$aref = $delta->table_header"
237 This returns an array ref of the headers for the table.
238 .ie n .IP "$string = $delta\->table_op" 4
239 .el .IP "\f(CW$string\fR = \f(CW$delta\fR\->table_op" 4
240 .IX Item "$string = $delta->table_op"
241 This returns the operator that should be shown in the table.
242 .ie n .IP "$string = $delta\->table_check_lines" 4
243 .el .IP "\f(CW$string\fR = \f(CW$delta\fR\->table_check_lines" 4
244 .IX Item "$string = $delta->table_check_lines"
245 This returns the defined lines (extra debug info) that should be displayed.
246 .ie n .IP "$string = $delta\->table_got_lines" 4
247 .el .IP "\f(CW$string\fR = \f(CW$delta\fR\->table_got_lines" 4
248 .IX Item "$string = $delta->table_got_lines"
249 This returns the generated lines (extra debug info) that should be displayed.
250 .ie n .IP "$aref = $delta\->table_rows" 4
251 .el .IP "\f(CW$aref\fR = \f(CW$delta\fR\->table_rows" 4
252 .IX Item "$aref = $delta->table_rows"
253 This returns an arrayref of table rows, each row is itself an arrayref.
254 .ie n .IP "@table_lines = $delta\->table" 4
255 .el .IP "\f(CW@table_lines\fR = \f(CW$delta\fR\->table" 4
256 .IX Item "@table_lines = $delta->table"
257 Returns all the lines of the table that should be displayed.
258 .SH SOURCE
259 .IX Header "SOURCE"
260 The source code repository for Test2\-Suite can be found at
261 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
262 .SH MAINTAINERS
263 .IX Header "MAINTAINERS"
264 .IP "Chad Granum <[email protected]>" 4
265 .IX Item "Chad Granum <[email protected]>"
266 .SH AUTHORS
267 .IX Header "AUTHORS"
268 .IP "Chad Granum <[email protected]>" 4
269 .IX Item "Chad Granum <[email protected]>"
270 .SH COPYRIGHT
271 .IX Header "COPYRIGHT"
272 Copyright Chad Granum <[email protected]>.
273 .PP
274 This program is free software; you can redistribute it and/or
275 modify it under the same terms as Perl itself.
276 .PP
277 See \fIhttp://dev.perl.org/licenses/\fR