TAP::Pa...Factory(3pm)

hey bestie, welcome to the TAP::Parser::IteratorFactory(3pm) page from the Perl Programmers Reference Guide 💖 this one is literally a factory class, and it's giving "who should handle this source?" main character energy ✨

🌸 NAME 🌸

TAP::Parser::IteratorFactory — figures out which SourceHandler objects to use for a given Source. slay.

💖 VERSION 💖

Version 3.50.

✨ SYNOPSIS ✨

use TAP::Parser::IteratorFactory;
my $factory = TAP::Parser::IteratorFactory->new({ %config });
my $iterator  = $factory->make_iterator( $filename );

🦋 DESCRIPTION 🦋

Okay so this is a factory class that takes a TAP::Parser::Source and runs it through all the registered TAP::Parser::SourceHandlers to see which one should handle the source. no cap, that's the whole vibe check 🫶

If you're a plugin author, you'll be interested in how register_handlers work and how detect_source works. iykyk 💅

🎀 METHODS 🎀

Class Methods

new

Creates a new factory class:

my $sf = TAP::Parser::IteratorFactory->new( $config );

$config is optional. If given, it sets config and calls load_handlers. cute and efficient 💖

register_handler

Registers a new TAP::Parser::SourceHandler with this factory:

__PACKAGE__->register_handler( $handler_class );

handlers

List of handlers that have been registered. periodt ✨

Instance Methods

config

my $cfg = $sf->config;
$sf->config({ Perl => { %config } });

Chaining getter/setter for the configuration of the available source handlers. This is a hashref keyed on handler class whose values contain config to be passed onto the handlers during detection & creation. Class names may be fully qualified or abbreviated, eg:

# these are equivalent
$sf->config({ 'TAP::Parser::SourceHandler::Perl' => { %config } });
$sf->config({ 'Perl' => { %config } });

lowkey iconic that both forms work 💅

load_handlers

$sf->load_handlers;

Loads the handler classes defined in config. For example, given a config:

$sf->config({
  MySourceHandler => { some => 'config' },
});

load_handlers will attempt to load the MySourceHandler class by looking in @INC for it in this order:

TAP::Parser::SourceHandler::MySourceHandler
MySourceHandler

It croaks on error. so bestie, be ready for drama if the class isn't there 😭

make_iterator

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

Given a TAP::Parser::Source, finds the most suitable TAP::Parser::SourceHandler to use to create a TAP::Parser::Iterator (see detect_source). Dies on error. it's giving "choose the right handler or else" 💀

detect_source

Given a TAP::Parser::Source, detects what kind of source it is and returns one TAP::Parser::SourceHandler (the most confident one). Dies on error. yup, confidence is the whole plot here 👑

The detection algorithm works something like this:

for (@registered_handlers) {
  # ask them how confident they are about handling this source
  $confidence{$handler} = $handler->can_handle( $source )
}
# choose the most confident handler

Ties are handled by choosing the first handler. fr fr, first one wins 🫡

🌈 SUBCLASSING 🌈

Please see SUBCLASSING in TAP::Parser for a subclassing overview. bestie, go read that if you're going full custom 👀

Example

If we've done things right, you'll probably want to write a new source, rather than sub-classing this (see TAP::Parser::SourceHandler for that). that's the dream, honestly 🌸

But in case you find the need to...

package MyIteratorFactory;

use strict;

use base 'TAP::Parser::IteratorFactory';

# override source detection algorithm
sub detect_source {
  my ($self, $raw_source_ref, $meta) = @_;
  # do detective work, using $meta and whatever else...
}

1;

not me writing a whole detective subroutine 😭🕵️‍♀️

⭐ AUTHORS ⭐

Steve Purkis.

💜 ATTRIBUTION 💜

Originally ripped off from Test::Harness. their words, not mine, bestie 🙈

Moved out of TAP::Parser & converted to a factory class to support extensible TAP source detective work by Steve Purkis. iconic evolution, honestly 🦋

🔥 SEE ALSO 🔥

• TAP::Object
• TAP::Parser
• TAP::Parser::SourceHandler
• TAP::Parser::SourceHandler::File
• TAP::Parser::SourceHandler::Perl
• TAP::Parser::SourceHandler::RawTAP
• TAP::Parser::SourceHandler::Handle
• TAP::Parser::SourceHandler::Executable

---

This page is from perl v5.42.3, dated 2026-11-03, and it's the TAP::Pa...Factory(3pm) page — periodt. 💅✨