Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::Compare::Base.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::Base 3pm"
61 .TH Test2::Compare::Base 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::Base \- Base class for comparison classes.
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 All comparison classes for Test2::Compare should inherit from this base class.
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 3
74 \& package Test2::Compare::MyCheck;
75 \& use strict;
76 \& use warnings;
77 \&
78 \& use base \*(AqTest2::Compare::Base\*(Aq;
79 \& use Test2::Util::HashBase qw/stuff/;
80 \&
81 \& sub name { \*(AqSTUFF\*(Aq }
82 \&
83 \& sub operator {
84 \& my $self = shift;
85 \& my ($got) = @_;
86 \& return \*(Aqeq\*(Aq;
87 \& }
88 \&
89 \& sub verify {
90 \& my $self = shift;
91 \& my $params = @_;
92 \&
93 \& # Always check if $got exists! This method must return false if no
94 \& # value at all was received.
95 \& return 0 unless $params{exists};
96 \&
97 \& my $got = $params{got};
98 \&
99 \& # Returns true if both values match. This includes undef, 0, and other
100 \& # false\-y values!
101 \& return $got eq $self\->stuff;
102 \& }
103 .Ve
104 .SH METHODS
105 .IX Header "METHODS"
106 Some of these must be overridden, others can be.
107 .ie n .IP "$dclass = $check\->delta_class" 4
108 .el .IP "\f(CW$dclass\fR = \f(CW$check\fR\->delta_class" 4
109 .IX Item "$dclass = $check->delta_class"
110 Returns the delta subclass that should be used. By default
111 Test2::Compare::Delta is used.
112 .ie n .IP "@deltas = $check\->deltas(id => $id, exists => $bool, got => $got, convert => \e&convert, seen => \e%seen)" 4
113 .el .IP "\f(CW@deltas\fR = \f(CW$check\fR\->deltas(id => \f(CW$id\fR, exists => \f(CW$bool\fR, got => \f(CW$got\fR, convert => \e&convert, seen => \e%seen)" 4
114 .IX Item "@deltas = $check->deltas(id => $id, exists => $bool, got => $got, convert => &convert, seen => %seen)"
115 Should return child deltas.
116 .ie n .IP "@lines = $check\->got_lines($got)" 4
117 .el .IP "\f(CW@lines\fR = \f(CW$check\fR\->got_lines($got)" 4
118 .IX Item "@lines = $check->got_lines($got)"
119 This is your chance to provide line numbers for errors in the \f(CW$got\fR
120 structure.
121 .ie n .IP "$op = $check\->\fBoperator()\fR" 4
122 .el .IP "\f(CW$op\fR = \f(CW$check\fR\->\fBoperator()\fR" 4
123 .IX Item "$op = $check->operator()"
124 .PD 0
125 .ie n .IP "$op = $check\->operator($got)" 4
126 .el .IP "\f(CW$op\fR = \f(CW$check\fR\->operator($got)" 4
127 .IX Item "$op = $check->operator($got)"
128 .PD
129 Returns the operator that was used to compare the check with the received data
130 in \f(CW$got\fR. If there was no value for got then there will be no arguments,
131 undef will only be an argument if undef was seen in \f(CW$got\fR. This is how you
132 can tell the difference between a missing value and an undefined one.
133 .ie n .IP "$bool = $check\->verify(id => $id, exists => $bool, got => $got, convert => \e&convert, seen => \e%seen)" 4
134 .el .IP "\f(CW$bool\fR = \f(CW$check\fR\->verify(id => \f(CW$id\fR, exists => \f(CW$bool\fR, got => \f(CW$got\fR, convert => \e&convert, seen => \e%seen)" 4
135 .IX Item "$bool = $check->verify(id => $id, exists => $bool, got => $got, convert => &convert, seen => %seen)"
136 Return true if there is a shallow match, that is both items are arrayrefs, both
137 items are the same string or same number, etc. This should not recurse, as deep
138 checks are done in \f(CW\*(C`$check\->deltas()\*(C'\fR.
139 .ie n .IP "$name = $check\->name" 4
140 .el .IP "\f(CW$name\fR = \f(CW$check\fR\->name" 4
141 .IX Item "$name = $check->name"
142 Get the name of the check.
143 .ie n .IP "$display = $check\->render" 4
144 .el .IP "\f(CW$display\fR = \f(CW$check\fR\->render" 4
145 .IX Item "$display = $check->render"
146 What should be displayed in a table for this check, usually the name or value.
147 .ie n .IP "$delta = $check\->run(id => $id, exists => $bool, got => $got, convert => \e&convert, seen => \e%seen)" 4
148 .el .IP "\f(CW$delta\fR = \f(CW$check\fR\->run(id => \f(CW$id\fR, exists => \f(CW$bool\fR, got => \f(CW$got\fR, convert => \e&convert, seen => \e%seen)" 4
149 .IX Item "$delta = $check->run(id => $id, exists => $bool, got => $got, convert => &convert, seen => %seen)"
150 This is where the checking is done, first a shallow check using
151 \&\f(CW\*(C`$check\->verify\*(C'\fR, then checking \f(CW\*(C`$check\->deltas()\*(C'\fR. \f(CW\*(C`\e%seen\*(C'\fR is used
152 to prevent cycles.
153 .SH SOURCE
154 .IX Header "SOURCE"
155 The source code repository for Test2\-Suite can be found at
156 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
157 .SH MAINTAINERS
158 .IX Header "MAINTAINERS"
159 .IP "Chad Granum <[email protected]>" 4
160 .IX Item "Chad Granum <[email protected]>"
161 .SH AUTHORS
162 .IX Header "AUTHORS"
163 .IP "Chad Granum <[email protected]>" 4
164 .IX Item "Chad Granum <[email protected]>"
165 .SH COPYRIGHT
166 .IX Header "COPYRIGHT"
167 Copyright Chad Granum <[email protected]>.
168 .PP
169 This program is free software; you can redistribute it and/or
170 modify it under the same terms as Perl itself.
171 .PP
172 See \fIhttp://dev.perl.org/licenses/\fR