Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Test2::Manual::Tooling::Formatter.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::Manual::Tooling::Formatter 3pm"
61 .TH Test2::Manual::Tooling::Formatter 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::Manual::Tooling::Formatter \- How to write a custom formatter, in our
68 case a JSONL formatter.
69 .SH DESCRIPTION
70 .IX Header "DESCRIPTION"
71 This tutorial explains a minimal formatter that outputs each event as a json
72 string on its own line. A true formatter will probably be significantly more
73 complicated, but this will give you the basics needed to get started.
74 .SH "COMPLETE CODE UP FRONT"
75 .IX Header "COMPLETE CODE UP FRONT"
76 .Vb 3
77 \& package Test2::Formatter::MyFormatter;
78 \& use strict;
79 \& use warnings;
80 \&
81 \& use JSON::MaybeXS qw/encode_json/;
82 \&
83 \& use base qw/Test2::Formatter/;
84 \&
85 \& sub new { bless {}, shift }
86 \&
87 \& sub encoding {};
88 \&
89 \& sub write {
90 \& my ($self, $e, $num, $f) = @_;
91 \& $f ||= $e\->facet_data;
92 \&
93 \& print encode_json($f), "\en";
94 \& }
95 \&
96 \& 1;
97 .Ve
98 .SH "LINE BY LINE"
99 .IX Header "LINE BY LINE"
100 .IP "use base qw/Test2::Formatter/;" 4
101 .IX Item "use base qw/Test2::Formatter/;"
102 All formatters should inherit from Test2::Formatter.
103 .IP "sub new { bless {}, shift }" 4
104 .IX Item "sub new { bless {}, shift }"
105 Formatters need to be instantiable objects, this is a minimal \f(CWnew()\fR method.
106 .IP "sub encoding {};" 4
107 .IX Item "sub encoding {};"
108 For this example we leave this sub empty. In general you should implement this
109 sub to make sure you honor situations where the encoding is set. Test2::V0
110 itself will try to set the encoding to UTF8.
111 .IP "sub write { ... }" 4
112 .IX Item "sub write { ... }"
113 The \f(CWwrite()\fR method is the most important, each event is sent here.
114 .ie n .IP "my ($self, $e, $num, $f) = @_;" 4
115 .el .IP "my ($self, \f(CW$e\fR, \f(CW$num\fR, \f(CW$f\fR) = \f(CW@_\fR;" 4
116 .IX Item "my ($self, $e, $num, $f) = @_;"
117 The \f(CWwrite()\fR method receives 3 or 4 arguments, the fourth is optional.
118 .RS 4
119 .ie n .IP $self 4
120 .el .IP \f(CW$self\fR 4
121 .IX Item "$self"
122 The formatter itself.
123 .ie n .IP $e 4
124 .el .IP \f(CW$e\fR 4
125 .IX Item "$e"
126 The event being written
127 .ie n .IP $num 4
128 .el .IP \f(CW$num\fR 4
129 .IX Item "$num"
130 The most recent assertion number. If the event being processed is an assertion
131 then this will have been bumped by 1 since the last call to write. For non
132 assertions this number is set to the most recent assertion.
133 .ie n .IP $f 4
134 .el .IP \f(CW$f\fR 4
135 .IX Item "$f"
136 This MAY be a hashref containing all the facet data from the event. More often
137 then not this will be undefined. This is only set if the facet data was needed
138 by the hub, and it usually is not.
139 .RE
140 .RS 4
141 .RE
142 .ie n .IP "$f ||= $e\->facet_data;" 4
143 .el .IP "\f(CW$f\fR ||= \f(CW$e\fR\->facet_data;" 4
144 .IX Item "$f ||= $e->facet_data;"
145 We want to dump the event facet data. This will set \f(CW$f\fR to the facet data
146 unless we already have the facet data.
147 .IP "print encode_json($f), ""\en"";" 4
148 .IX Item "print encode_json($f), ""n"";"
149 This line prints the JSON encoded facet data, and a newline.
150 .SH "SEE ALSO"
151 .IX Header "SEE ALSO"
152 Test2::Manual \- Primary index of the manual.
153 .SH SOURCE
154 .IX Header "SOURCE"
155 The source code repository for Test2\-Manual 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