TAP::Parser::SourceHandler(3p) Perl Programmers Reference Guide

TAP::Parser::SourceHandler(3p) Perl Programmers Reference Guide #

TAP::Parser::SourceHandler(3p) Perl Programmers Reference Guide

NNAAMMEE #

 TAP::Parser::SourceHandler - Base class for different TAP source handlers

VVEERRSSIIOONN #

 Version 3.44

SSYYNNOOPPSSIISS #

   # abstract class - don't use directly!
   # see TAP::Parser::IteratorFactory for general usage

   # must be sub-classed for use
   package MySourceHandler;
   use base 'TAP::Parser::SourceHandler';
   sub can_handle    { return $confidence_level }
   sub make_iterator { return $iterator }

   # see example below for more details

DDEESSCCRRIIPPTTIIOONN #

 This is an abstract base class for TAP::Parser::Source handlers /
 handlers.

 A "TAP::Parser::SourceHandler" does whatever is necessary to produce &
 capture a stream of TAP from the _r_a_w source, and package it up in a
 TAP::Parser::Iterator for the parser to consume.

 "SourceHandlers" must implement the _s_o_u_r_c_e _d_e_t_e_c_t_i_o_n _& _h_a_n_d_l_i_n_g interface
 used by TAP::Parser::IteratorFactory.  At 2 methods, the interface is
 pretty simple: "can_handle" and "make_source".

 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.

MMEETTHHOODDSS #

CCllaassss MMeetthhooddss _"_c_a_n___h_a_n_d_l_e_"

 _A_b_s_t_r_a_c_t _m_e_t_h_o_d.

   my $vote = $class->can_handle( $source );

 $source is a TAP::Parser::Source.

 Returns a number between 0 & 1 reflecting how confidently the raw source
 can be handled.  For example, 0 means the source cannot handle it, 0.5
 means it may be able to, and 1 means it definitely can.  See
 "detect_source" in TAP::Parser::IteratorFactory for details on how this
 is used.

 _"_m_a_k_e___i_t_e_r_a_t_o_r_"

 _A_b_s_t_r_a_c_t _m_e_t_h_o_d.

   my $iterator = $class->make_iterator( $source );

 $source is a TAP::Parser::Source.

 Returns a new TAP::Parser::Iterator object for use by the TAP::Parser.
 "croak"s on error.

SSUUBBCCLLAASSSSIINNGG #

 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.

 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.

 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 "config" option which will cause "load_sources" in
 TAP::Parser::IteratorFactory to load your subclass).

 Don't forget to register your class with "register_handler" in
 TAP::Parser::IteratorFactory.

EExxaammppllee package MySourceHandler;

   use strict;

   use MySourceHandler; # see TAP::Parser::SourceHandler
   use TAP::Parser::IteratorFactory;

   use base 'TAP::Parser::SourceHandler';

   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 '.tap';
           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 =~ /\d\.\.\d/;
           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([ 'foo', 'bar' ]);
       return $iterator;
   }

   1;

AAUUTTHHOORRSS #

 TAPx Developers.

 Source detection stuff added by Steve Purkis

SSEEEE AALLSSOO #

 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

perl v5.36.3 2023-02-15 TAP::Parser::SourceHandler(3p)