.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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::Formatter::Test2::Composer 3pm"
.TH Test2::Formatter::Test2::Composer 3pm 2024-03-08 "perl v5.38.2" "User Contributed Perl Documentation"
.\" 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::Formatter::Test2::Composer \- Compose output components from event facets
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This is used by Test2::Formatter::Test2 to turn events into output
components. This logic lives here instead of in the formatter because it is
also used by Test2::Harness::UI. Other tools may also find this conversion
useful.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use Test2::Formatter::Test2::Composer;
\&
\&    # Note, all methods are class methods, this is just here for convenience.
\&    my $comp = Test2::Formatter::Test2::Composer\->new();
\&
\&    my $out = $comp\->render_one_line($event);
\&    my ($facet_name, $tag_string, $text_for_humans) = @$out;
\&    ...
\&
\&    for my $line ($comp\->render_verbose($event)) {
\&        my ($facet_name, $tag_string, $text_for_humans) = @$line;
\&        ...,
\&    }
.Ve
.SH METHODS
.IX Header "METHODS"
All methods are class methods, but they also work just fine on a blessed
instance. There is no benefit to a blessed instance, but you can create one for
convenience if it makes you more comfortable.
.ie n .IP "$inst = $class\->\fBnew()\fR" 4
.el .IP "\f(CW$inst\fR = \f(CW$class\fR\->\fBnew()\fR" 4
.IX Item "$inst = $class->new()"
Create a blessed instance. This is here for convenience only. All methods are
class methods.
.ie n .IP "$arrayref = $class\->render_one_line($event)" 4
.el .IP "\f(CW$arrayref\fR = \f(CW$class\fR\->render_one_line($event)" 4
.IX Item "$arrayref = $class->render_one_line($event)"
.PD 0
.ie n .IP "$arrayref = $class\->render_one_line(\e%facet_data)" 4
.el .IP "\f(CW$arrayref\fR = \f(CW$class\fR\->render_one_line(\e%facet_data)" 4
.IX Item "$arrayref = $class->render_one_line(%facet_data)"
.PD
.Vb 2
\&    my $out = $comp\->render_one_line($event);
\&    my ($facet_name, $tag_string, $text_for_humans) = @$out;
.Ve
.Sp
This will return a single line of output from the event, even if the event
would normally return multiple lines.
.Sp
In order of priority:
.RS 4
.IP "Custom 'render' facet" 4
.IX Item "Custom 'render' facet"
.PD 0
.IP "Control 'halt' facet (bail-out)" 4
.IX Item "Control 'halt' facet (bail-out)"
.IP "Assertion (pass/fail)" 4
.IX Item "Assertion (pass/fail)"
.IP "Error message" 4
.IX Item "Error message"
.IP Plan 4
.IX Item "Plan"
.IP "Info (note/diag)" 4
.IX Item "Info (note/diag)"
.IP "Timing data" 4
.IX Item "Timing data"
.IP About 4
.IX Item "About"
.RE
.RS 4
.RE
.ie n .IP "@lines = $class\->render_verbose($event, %control_params)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_verbose($event, \f(CW%control_params\fR)" 4
.IX Item "@lines = $class->render_verbose($event, %control_params)"
.ie n .IP "@lines = $class\->render_verbose(\e%facet_data, %control_params)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_verbose(\e%facet_data, \f(CW%control_params\fR)" 4
.IX Item "@lines = $class->render_verbose(%facet_data, %control_params)"
.PD
This will verbosely render any event. The \f(CW%control_params\fR are passed
directly to \f(CWrender_control()\fR and are not used for anything else.
.Sp
.Vb 4
\&    for my $line ($comp\->render_verbose($event)) {
\&        my ($facet_name, $tag_string, $text_for_humans) = @$line;
\&        ...,
\&    }
.Ve
.ie n .IP "@lines = $class\->render_super_verbose($event)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_super_verbose($event)" 4
.IX Item "@lines = $class->render_super_verbose($event)"
.PD 0
.ie n .IP "@lines = $class\->render_super_verbose(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_super_verbose(\e%facet_data)" 4
.IX Item "@lines = $class->render_super_verbose(%facet_data)"
.PD
This is even more verbose than \f(CWrender_verbose()\fR because it produces output
lines even for facets that should normally not be seen, things that would
usually be considered noise.
.Sp
This is mainly useful for tools that allow deep inspection of log files.
.SS "FACET RENDERERS"
.IX Subsection "FACET RENDERERS"
With exception of \f(CWrender_control()\fR these are all the same. These all take
\&\f(CW\*(C`\e%facet_data\*(C'\fR as their only argument, and return a list of line-arrayrefs
\&\f(CW\*(C`[$facet, $tag, $text_for_humans]\*(C'\fR.
.ie n .IP "@lines = $class\->render_control(\e%facet_data, super_verbose => $bool)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_control(\e%facet_data, super_verbose => \f(CW$bool\fR)" 4
.IX Item "@lines = $class->render_control(%facet_data, super_verbose => $bool)"
This specific one is special in that it can take an extra argument. This
argument is used to toggle between super_verbose and regular verbosity. No
other facet renderer needs this toggle. If omitted it defaults to not being
super verbose.
.ie n .IP "@lines = $class\->render_launch(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_launch(\e%facet_data)" 4
.IX Item "@lines = $class->render_launch(%facet_data)"
.PD 0
.ie n .IP "@lines = $class\->render_start(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_start(\e%facet_data)" 4
.IX Item "@lines = $class->render_start(%facet_data)"
.ie n .IP "@lines = $class\->render_exit(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_exit(\e%facet_data)" 4
.IX Item "@lines = $class->render_exit(%facet_data)"
.ie n .IP "@lines = $class\->render_end(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_end(\e%facet_data)" 4
.IX Item "@lines = $class->render_end(%facet_data)"
.ie n .IP "@lines = $class\->render_brief(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_brief(\e%facet_data)" 4
.IX Item "@lines = $class->render_brief(%facet_data)"
.ie n .IP "@lines = $class\->render_plan(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_plan(\e%facet_data)" 4
.IX Item "@lines = $class->render_plan(%facet_data)"
.ie n .IP "@lines = $class\->render_assert(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_assert(\e%facet_data)" 4
.IX Item "@lines = $class->render_assert(%facet_data)"
.ie n .IP "@lines = $class\->render_amnesty(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_amnesty(\e%facet_data)" 4
.IX Item "@lines = $class->render_amnesty(%facet_data)"
.ie n .IP "@lines = $class\->render_debug(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_debug(\e%facet_data)" 4
.IX Item "@lines = $class->render_debug(%facet_data)"
.ie n .IP "@lines = $class\->render_info(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_info(\e%facet_data)" 4
.IX Item "@lines = $class->render_info(%facet_data)"
.ie n .IP "@lines = $class\->render_about(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_about(\e%facet_data)" 4
.IX Item "@lines = $class->render_about(%facet_data)"
.ie n .IP "@lines = $class\->render_errors(\e%facet_data)" 4
.el .IP "\f(CW@lines\fR = \f(CW$class\fR\->render_errors(\e%facet_data)" 4
.IX Item "@lines = $class->render_errors(%facet_data)"
.PD
.SH SOURCE
.IX Header "SOURCE"
The source code repository for Test2\-Harness can be found at
\&\fIhttp://github.com/Test\-More/Test2\-Harness/\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 2020 Chad Granum <exodist7@gmail.com>.
.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