TAP::P...andler(3perl)

🌸 NAME 🌸

TAP::Parser::SourceHandler — the base class for all the different TAP source handlers, bestie 💖

✨ VERSION ✨

Version 3.52 (yes, we're living in the future, slay)

🎀 SYNOPSIS 🎀

# 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

🦋 DESCRIPTION 🦋

okay so. This is an abstract base class for TAP::Parser::Source handlers / handlers. Like, it's the blueprint, not the building. Don't come for it directly, it's got main character energy but it's not ready to be used on its own 😭

A TAP::Parser::SourceHandler does literally whatever is necessary to produce & capture a stream of TAP from the raw source, and then packages it all up in a TAP::Parser::Iterator so the parser can consume it. It's giving personal chef for TAP streams 👑

SourceHandlers must implement the source detection & handling interface that TAP::Parser::IteratorFactory uses. And honestly? At 2 methods, the interface is pretty simple: can_handle and make_source.

Unless you're out here writing a new TAP::Parser::SourceHandler, a plugin, or subclassing TAP::Parser, you probably won't need to use this module directly. So if that's not you, you can go bestie, this page isn't for you 💅

---

💅 METHODS 💅

👑 Class Methods

⭐ can_handle

Abstract method. It's giving "you must implement me yourself."

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. So like, 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 the details on how this is actually used.

🌈 make_iterator

Abstract method too, twin.

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. And "croak"s on error — so if it goes wrong, it tells you, loudly 💀

---

🧚 SUBCLASSING 🧚

Please see "SUBCLASSING" in TAP::Parser for a subclassing overview, plus any of the subclasses that ship with this module as an example. What follows is a quick overview, iykyk.

Start by familiarizing yourself with TAP::Parser::Source and TAP::Parser::IteratorFactory. And tbh, TAP::Parser::SourceHandler::RawTAP is the easiest sub-class to use as an example — perfect starter pack 🎀

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. Like, seriously, don't forget, that's the whole vibe check 🙈

🍓 Example

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;

---

💖 AUTHORS 💖

TAPx Developers. Periodt.

Source detection stuff added by Steve Purkis — king behavior, we love to see it 👑

🌟 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

---

And that's the whole page bestie, go forth and handle your sources 💅✨ This was perl v5.44.0, dated 2026-10-17, and it ate, no cap 🫶🌸