NAME

       Test2::Manual::Tooling::Formatter - How to write a custom formatter, in our case a JSONL
       formatter.

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.

COMPLETE CODE UP FRONT

           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), "\n";
           }

           1;

LINE BY LINE

       use base qw/Test2::Formatter/;
           All formatters should inherit from Test2::Formatter.

       sub new { bless {}, shift }
           Formatters need to be instantiable objects, this is a minimal "new()" method.

       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.

       sub write { ... }
           The "write()" method is the most important, each event is sent here.

       my ($self, $e, $num, $f) = @_;
           The "write()" method receives 3 or 4 arguments, the fourth is optional.

           $self
               The formatter itself.

           $e  The event being written

           $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.

           $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.

       $f ||= $e->facet_data;
           We want to dump the event facet data. This will set $f to the facet data unless we
           already have the facet data.

       print encode_json($f), "\n";
           This line prints the JSON encoded facet data, and a newline.

SEE ALSO

       Test2::Manual - Primary index of the manual.

SOURCE

       The source code repository for Test2-Manual can be found at
       https://github.com/Test-More/Test2-Suite/.

MAINTAINERS

       Chad Granum <exodist@cpan.org>

AUTHORS

       Chad Granum <exodist@cpan.org>

COPYRIGHT

       Copyright 2018 Chad Granum <exodist@cpan.org>.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       See http://dev.perl.org/licenses/