.\" -*- 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 "TAP::Parser::SourceHandler 3perl"
.TH TAP::Parser::SourceHandler 3perl 2024-05-30 "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
TAP::Parser::SourceHandler \- Base class for different TAP source handlers
.SH VERSION
.IX Header "VERSION"
Version 3.44
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  # abstract class \- don\*(Aqt use directly!
\&  # see TAP::Parser::IteratorFactory for general usage
\&
\&  # must be sub\-classed for use
\&  package MySourceHandler;
\&  use base \*(AqTAP::Parser::SourceHandler\*(Aq;
\&  sub can_handle    { return $confidence_level }
\&  sub make_iterator { return $iterator }
\&
\&  # see example below for more details
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This is an abstract base class for TAP::Parser::Source handlers / handlers.
.PP
A \f(CW\*(C`TAP::Parser::SourceHandler\*(C'\fR does whatever is necessary to produce & capture
a stream of TAP from the \fIraw\fR source, and package it up in a
TAP::Parser::Iterator for the parser to consume.
.PP
\&\f(CW\*(C`SourceHandlers\*(C'\fR must implement the \fIsource detection & handling\fR interface
used by TAP::Parser::IteratorFactory.  At 2 methods, the interface is pretty
simple: "can_handle" and "make_source".
.PP
Unless you're writing a new TAP::Parser::SourceHandler, a plugin, or
subclassing TAP::Parser, you probably won't need to use this module directly.
.SH METHODS
.IX Header "METHODS"
.SS "Class Methods"
.IX Subsection "Class Methods"
\fR\f(CI\*(C`can_handle\*(C'\fR\fI\fR
.IX Subsection "can_handle"
.PP
\&\fIAbstract method\fR.
.PP
.Vb 1
\&  my $vote = $class\->can_handle( $source );
.Ve
.PP
\&\f(CW$source\fR is a TAP::Parser::Source.
.PP
Returns a number between \f(CW0\fR & \f(CW1\fR reflecting how confidently the raw source
can be handled.  For example, \f(CW0\fR means the source cannot handle it, \f(CW0.5\fR
means it may be able to, and \f(CW1\fR means it definitely can.  See
"detect_source" in TAP::Parser::IteratorFactory for details on how this is used.
.PP
\fR\f(CI\*(C`make_iterator\*(C'\fR\fI\fR
.IX Subsection "make_iterator"
.PP
\&\fIAbstract method\fR.
.PP
.Vb 1
\&  my $iterator = $class\->make_iterator( $source );
.Ve
.PP
\&\f(CW$source\fR is a TAP::Parser::Source.
.PP
Returns a new TAP::Parser::Iterator object for use by the TAP::Parser.
\&\f(CW\*(C`croak\*(C'\fRs on error.
.SH SUBCLASSING
.IX Header "SUBCLASSING"
Please see "SUBCLASSING" in TAP::Parser for a subclassing overview, and any
of the subclasses that ship with this module as an example.  What follows is
a quick overview.
.PP
Start by familiarizing yourself with TAP::Parser::Source and
TAP::Parser::IteratorFactory.  TAP::Parser::SourceHandler::RawTAP is
the easiest sub-class to use as an example.
.PP
It's important to point out that if you want your subclass to be automatically
used by TAP::Parser you'll have to and make sure it gets loaded somehow.
If you're using prove you can write an App::Prove plugin.  If you're
using TAP::Parser or TAP::Harness directly (e.g. through a custom script,
ExtUtils::MakeMaker, or Module::Build) you can use the \f(CW\*(C`config\*(C'\fR option
which will cause "load_sources" in TAP::Parser::IteratorFactory to load your
subclass).
.PP
Don't forget to register your class with
"register_handler" in TAP::Parser::IteratorFactory.
.SS Example
.IX Subsection "Example"
.Vb 1
\&  package MySourceHandler;
\&
\&  use strict;
\&
\&  use MySourceHandler; # see TAP::Parser::SourceHandler
\&  use TAP::Parser::IteratorFactory;
\&
\&  use base \*(AqTAP::Parser::SourceHandler\*(Aq;
\&
\&  TAP::Parser::IteratorFactory\->register_handler( _\|_PACKAGE_\|_ );
\&
\&  sub can_handle {
\&      my ( $class, $src ) = @_;
\&      my $meta   = $src\->meta;
\&      my $config = $src\->config_for( $class );
\&
\&      if ($config\->{accept_all}) {
\&          return 1.0;
\&      } elsif (my $file = $meta\->{file}) {
\&          return 0.0 unless $file\->{exists};
\&          return 1.0 if $file\->{lc_ext} eq \*(Aq.tap\*(Aq;
\&          return 0.9 if $file\->{shebang} && $file\->{shebang} =~ /^#!.+tap/;
\&          return 0.5 if $file\->{text};
\&          return 0.1 if $file\->{binary};
\&      } elsif ($meta\->{scalar}) {
\&          return 0.8 if $$raw_source_ref =~ /\ed\e.\e.\ed/;
\&          return 0.6 if $meta\->{has_newlines};
\&      } elsif ($meta\->{array}) {
\&          return 0.8 if $meta\->{size} < 5;
\&          return 0.6 if $raw_source_ref\->[0] =~ /foo/;
\&          return 0.5;
\&      } elsif ($meta\->{hash}) {
\&          return 0.6 if $raw_source_ref\->{foo};
\&          return 0.2;
\&      }
\&
\&      return 0;
\&  }
\&
\&  sub make_iterator {
\&      my ($class, $source) = @_;
\&      # this is where you manipulate the source and
\&      # capture the stream of TAP in an iterator
\&      # either pick a TAP::Parser::Iterator::* or write your own...
\&      my $iterator = TAP::Parser::Iterator::Array\->new([ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ]);
\&      return $iterator;
\&  }
\&
\&  1;
.Ve
.SH AUTHORS
.IX Header "AUTHORS"
TAPx Developers.
.PP
Source detection stuff added by Steve Purkis
.SH "SEE ALSO"
.IX Header "SEE ALSO"
TAP::Object,
TAP::Parser,
TAP::Parser::Source,
TAP::Parser::Iterator,
TAP::Parser::IteratorFactory,
TAP::Parser::SourceHandler::Executable,
TAP::Parser::SourceHandler::Perl,
TAP::Parser::SourceHandler::File,
TAP::Parser::SourceHandler::Handle,
TAP::Parser::SourceHandler::RawTAP