diff options
Diffstat (limited to 'upstream/debian-unstable/man3/Test2::Formatter.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/Test2::Formatter.3perl | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/Test2::Formatter.3perl b/upstream/debian-unstable/man3/Test2::Formatter.3perl new file mode 100644 index 00000000..8ee3dc95 --- /dev/null +++ b/upstream/debian-unstable/man3/Test2::Formatter.3perl @@ -0,0 +1,166 @@ +.\" -*- 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 3perl" +.TH Test2::Formatter 3perl 2024-01-12 "perl v5.38.2" "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::Formatter \- Namespace for formatters. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This is the namespace for formatters. This is an empty package. +.SH "CREATING FORMATTERS" +.IX Header "CREATING FORMATTERS" +A formatter is any package or object with a \f(CW\*(C`write($event, $num)\*(C'\fR method. +.PP +.Vb 3 +\& package Test2::Formatter::Foo; +\& use strict; +\& use warnings; +\& +\& sub write { +\& my $self_or_class = shift; +\& my ($event, $assert_num) = @_; +\& ... +\& } +\& +\& sub hide_buffered { 1 } +\& +\& sub terminate { } +\& +\& sub finalize { } +\& +\& sub supports_tables { return $BOOL } +\& +\& sub new_root { +\& my $class = shift; +\& ... +\& $class\->new(@_); +\& } +\& +\& 1; +.Ve +.PP +The \f(CW\*(C`write\*(C'\fR method is a method, so it either gets a class or instance. The two +arguments are the \f(CW$event\fR object it should record, and the \f(CW$assert_num\fR +which is the number of the current assertion (ok), or the last assertion if +this event is not itself an assertion. The assertion number may be any integer 0 +or greater, and may be undefined in some cases. +.PP +The \f(CWhide_buffered()\fR method must return a boolean. This is used to tell +buffered subtests whether or not to send it events as they are being buffered. +See "run_subtest(...)" in Test2::API for more information. +.PP +The \f(CW\*(C`terminate\*(C'\fR and \f(CW\*(C`finalize\*(C'\fR methods are optional methods called that you +can implement if the format you're generating needs to handle these cases, for +example if you are generating XML and need close open tags. +.PP +The \f(CW\*(C`terminate\*(C'\fR method is called when an event's \f(CW\*(C`terminate\*(C'\fR method returns +true, for example when a Test2::Event::Plan has a \f(CW\*(Aqskip_all\*(Aq\fR plan, or +when a Test2::Event::Bail event is sent. The \f(CW\*(C`terminate\*(C'\fR method is passed +a single argument, the Test2::Event object which triggered the terminate. +.PP +The \f(CW\*(C`finalize\*(C'\fR method is always the last thing called on the formatter, \fIexcept when \fR\f(CI\*(C`terminate\*(C'\fR\fI is called for a Bail event\fR. It is passed the +following arguments: +.PP +The \f(CW\*(C`supports_tables\*(C'\fR method should be true if the formatter supports directly +rendering table data from the \f(CW\*(C`info\*(C'\fR facets. This is a newer feature and many +older formatters may not support it. When not supported the formatter falls +back to rendering \f(CW\*(C`detail\*(C'\fR instead of the \f(CW\*(C`table\*(C'\fR data. +.PP +The \f(CW\*(C`new_root\*(C'\fR method is used when constructing a root formatter. The default +is to just delegate to the regular \f(CWnew()\fR method, most formatters can ignore +this. +.IP \(bu 4 +The number of tests that were planned +.IP \(bu 4 +The number of tests actually seen +.IP \(bu 4 +The number of tests which failed +.IP \(bu 4 +A boolean indicating whether or not the test suite passed +.IP \(bu 4 +A boolean indicating whether or not this call is for a subtest +.PP +The \f(CW\*(C`new_root\*(C'\fR method is called when \f(CW\*(C`Test2::API::Stack\*(C'\fR Initializes the root +hub for the first time. Most formatters will simply have this call \f(CW\*(C`$class\->new\*(C'\fR, which is the default behavior. Some formatters however may want +to take extra action during construction of the root formatter, this is where +they can do that. +.SH SOURCE +.IX Header "SOURCE" +The source code repository for Test2 can be found at +\&\fIhttp://github.com/Test\-More/test\-more/\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 <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 |