# phpman > info > TAP::Parser::SourceHandler

[TAP::Parser::SourceHandPerl3Programmers](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandPerl3Programmers/markdown) [ReferTAP::Parser](https://www.chedong.com/phpMan.php/perldoc/ReferTAP%3A%3AParser/markdown)::[SourceHandler(3perl)](https://www.chedong.com/phpMan.php/man/SourceHandler/3perl/markdown)

NAME
       [TAP::Parser::SourceHandler](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler/markdown) - Base class for different TAP source
       handlers

VERSION
       Version 3.43

SYNOPSIS
         # abstract class - don't use directly!
         # see [TAP::Parser::IteratorFactory](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIteratorFactory/markdown) for general usage

         # must be sub-classed for use
         package MySourceHandler;
         use base '[TAP::Parser::SourceHandler](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler/markdown)';
         sub can_handle    { return $confidence_level }
         sub make_iterator { return $iterator }

         # see example below for more details

DESCRIPTION
       This is an abstract base class for [TAP::Parser::Source](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASource/markdown) handlers /
       handlers.

       A "[TAP::Parser::SourceHandler](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler/markdown)" does whatever is necessary to produce &
       capture a stream of TAP from the raw source, and package it up in a
       [TAP::Parser::Iterator](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIterator/markdown) for the parser to consume.

       "SourceHandlers" must implement the source detection & handling
       interface used by [TAP::Parser::IteratorFactory](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIteratorFactory/markdown).  At 2 methods, the
       interface is pretty simple: "can_handle" and "make_source".

       Unless you're writing a new [TAP::Parser::SourceHandler](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler/markdown), a plugin, or
       subclassing [TAP::Parser](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser/markdown), you probably won't need to use this module
       directly.

METHODS
   Class Methods
       "can_handle"

       Abstract method.

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

       $source is a [TAP::Parser::Source](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASource/markdown).

       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](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIteratorFactory/markdown) for details on how this
       is used.

       "make_iterator"

       Abstract method.

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

       $source is a [TAP::Parser::Source](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASource/markdown).

       Returns a new [TAP::Parser::Iterator](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIterator/markdown) object for use by the [TAP::Parser](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser/markdown).
       "croak"s on error.

SUBCLASSING
       Please see "SUBCLASSING" in [TAP::Parser](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASource/markdown) and
       [TAP::Parser::IteratorFactory](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIteratorFactory/markdown).  [TAP::Parser::SourceHandler::RawTAP](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler%3A%3ARawTAP/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser/markdown) you'll have to and make sure it gets
       loaded somehow.  If you're using prove you can write an [App::Prove](https://www.chedong.com/phpMan.php/perldoc/App%3A%3AProve/markdown)
       plugin.  If you're using [TAP::Parser](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser/markdown) or [TAP::Harness](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AHarness/markdown) directly (e.g.
       through a custom script, [ExtUtils::MakeMaker](https://www.chedong.com/phpMan.php/perldoc/ExtUtils%3A%3AMakeMaker/markdown), or [Module::Build](https://www.chedong.com/phpMan.php/perldoc/Module%3A%3ABuild/markdown)) you can
       use the "config" option which will cause "load_sources" in
       [TAP::Parser::IteratorFactory](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIteratorFactory/markdown) to load your subclass).

       Don't forget to register your class with "register_handler" in
       [TAP::Parser::IteratorFactory](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIteratorFactory/markdown).

   Example
         package MySourceHandler;

         use strict;

         use MySourceHandler; # see [TAP::Parser::SourceHandler](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler/markdown)
         use [TAP::Parser::IteratorFactory](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIteratorFactory/markdown);

         use base '[TAP::Parser::SourceHandler](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler/markdown)';

         [TAP::Parser::IteratorFactory](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIteratorFactory/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIterator/markdown)::* or write your own...
             my $iterator = [TAP::Parser::Iterator::Array](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIterator%3A%3AArray/markdown)->new([ 'foo', 'bar' ]);
             return $iterator;
         }

         1;

AUTHORS
       TAPx Developers.

       Source detection stuff added by Steve Purkis

SEE ALSO
       [TAP::Object](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AObject/markdown), [TAP::Parser](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser/markdown), [TAP::Parser::Source](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASource/markdown), [TAP::Parser::Iterator](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIterator/markdown),
       [TAP::Parser::IteratorFactory](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3AIteratorFactory/markdown), [TAP::Parser::SourceHandler::Executable](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler%3A%3AExecutable/markdown),
       [TAP::Parser::SourceHandler::Perl](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler%3A%3APerl/markdown), [TAP::Parser::SourceHandler::File](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler%3A%3AFile/markdown),
       [TAP::Parser::SourceHandler::Handle](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler%3A%3AHandle/markdown), [TAP::Parser::SourceHandler::RawTAP](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser%3A%3ASourceHandler%3A%3ARawTAP/markdown)

perl v5.34.0                      2025-07-25 [TAP::Parser](https://www.chedong.com/phpMan.php/perldoc/TAP%3A%3AParser/markdown)::[SourceHandler(3perl)](https://www.chedong.com/phpMan.php/man/SourceHandler/3perl/markdown)