.\" -*- 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::Manual::Tooling::Formatter 3perl"
.TH Test2::Manual::Tooling::Formatter 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::Manual::Tooling::Formatter \- How to write a custom formatter, in our
case a JSONL formatter.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This tutorial explains a minimal formatter that outputs each event as a json
string on its own line. A true formatter will probably be significantly more
complicated, but this will give you the basics needed to get started.
.SH "COMPLETE CODE UP FRONT"
.IX Header "COMPLETE CODE UP FRONT"
.Vb 3
\&    package Test2::Formatter::MyFormatter;
\&    use strict;
\&    use warnings;
\&
\&    use JSON::MaybeXS qw/encode_json/;
\&
\&    use base qw/Test2::Formatter/;
\&
\&    sub new { bless {}, shift }
\&
\&    sub encoding {};
\&
\&    sub write {
\&        my ($self, $e, $num, $f) = @_;
\&        $f ||= $e\->facet_data;
\&
\&        print encode_json($f), "\en";
\&    }
\&
\&    1;
.Ve
.SH "LINE BY LINE"
.IX Header "LINE BY LINE"
.IP "use base qw/Test2::Formatter/;" 4
.IX Item "use base qw/Test2::Formatter/;"
All formatters should inherit from Test2::Formatter.
.IP "sub new { bless {}, shift }" 4
.IX Item "sub new { bless {}, shift }"
Formatters need to be instantiable objects, this is a minimal \f(CWnew()\fR method.
.IP "sub encoding {};" 4
.IX Item "sub encoding {};"
For this example we leave this sub empty. In general you should implement this
sub to make sure you honor situations where the encoding is set. Test2::V0
itself will try to set the encoding to UTF8.
.IP "sub write { ... }" 4
.IX Item "sub write { ... }"
The \f(CWwrite()\fR method is the most important, each event is sent here.
.ie n .IP "my ($self, $e, $num, $f) = @_;" 4
.el .IP "my ($self, \f(CW$e\fR, \f(CW$num\fR, \f(CW$f\fR) = \f(CW@_\fR;" 4
.IX Item "my ($self, $e, $num, $f) = @_;"
The \f(CWwrite()\fR method receives 3 or 4 arguments, the fourth is optional.
.RS 4
.ie n .IP $self 4
.el .IP \f(CW$self\fR 4
.IX Item "$self"
The formatter itself.
.ie n .IP $e 4
.el .IP \f(CW$e\fR 4
.IX Item "$e"
The event being written
.ie n .IP $num 4
.el .IP \f(CW$num\fR 4
.IX Item "$num"
The most recent assertion number. If the event being processed is an assertion
then this will have been bumped by 1 since the last call to write. For non
assertions this number is set to the most recent assertion.
.ie n .IP $f 4
.el .IP \f(CW$f\fR 4
.IX Item "$f"
This MAY be a hashref containing all the facet data from the event. More often
then not this will be undefined. This is only set if the facet data was needed
by the hub, and it usually is not.
.RE
.RS 4
.RE
.ie n .IP "$f ||= $e\->facet_data;" 4
.el .IP "\f(CW$f\fR ||= \f(CW$e\fR\->facet_data;" 4
.IX Item "$f ||= $e->facet_data;"
We want to dump the event facet data. This will set \f(CW$f\fR to the facet data
unless we already have the facet data.
.IP "print encode_json($f), ""\en"";" 4
.IX Item "print encode_json($f), ""n"";"
This line prints the JSON encoded facet data, and a newline.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test2::Manual \- Primary index of the manual.
.SH SOURCE
.IX Header "SOURCE"
The source code repository for Test2\-Manual 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