```{index} single: TAP::Parser::IteratorFactory ``` # TAP::Parser::IteratorFactory Figures out which SourceHandler objects to use for a given Source ## VERSION Version 3.52 ## SYNOPSIS ```perl use TAP::Parser::IteratorFactory; my $factory = TAP::Parser::IteratorFactory->new({ %config }); my $iterator = $factory->make_iterator( $filename ); ``` ## DESCRIPTION This is a factory class that takes a [TAP::Parser::Source](Source.md) and runs it through all the registered [TAP::Parser::SourceHandler](SourceHandler.md)s to see which one should handle the source. If you're a plugin author, you'll be interested in how to "register\_handler"s, how "detect\_source" works. ## METHODS ### Class Methods #### `new` Creates a new factory class: ```perl my $sf = TAP::Parser::IteratorFactory->new( $config ); ``` `$config` is optional. If given, sets "config" and calls "load\_handlers". #### `register_handler` Registers a new [TAP::Parser::SourceHandler](SourceHandler.md) with this factory. ```perl __PACKAGE__->register_handler( $handler_class ); ``` #### `handlers` List of handlers that have been registered. ### Instance Methods #### `config` ```perl 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: ```perl ## these are equivalent $sf->config({ 'TAP::Parser::SourceHandler::Perl' => { %config } }); $sf->config({ 'Perl' => { %config } }); ``` #### `load_handlers` ```perl $sf->load_handlers; ``` Loads the handler classes defined in "config". For example, given a config: ```perl $sf->config({ MySourceHandler => { some => 'config' }, }); ``` `load_handlers` will attempt to load the `MySourceHandler` class by looking in `@INC` for it in this order: ```text TAP::Parser::SourceHandler::MySourceHandler MySourceHandler ``` `croak`s on error. #### `make_iterator` ```perl my $iterator = $src_factory->make_iterator( $source ); ``` Given a [TAP::Parser::Source](Source.md), finds the most suitable [TAP::Parser::SourceHandler](SourceHandler.md) to use to create a [TAP::Parser::Iterator](Iterator.md) (see "detect\_source"). Dies on error. #### `detect_source` Given a [TAP::Parser::Source](Source.md), detects what kind of source it is and returns _one_ [TAP::Parser::SourceHandler](SourceHandler.md) (the most confident one). Dies on error. The detection algorithm works something like this: ```perl 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. ## SUBCLASSING Please see ["SUBCLASSING" in TAP::Parser](../Parser.md) for a subclassing overview. ### 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](SourceHandler.md) for that). But in case you find the need to... ```perl 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; ``` ## AUTHORS Steve Purkis ## ATTRIBUTION Originally ripped off from [Test::Harness](../../Test/Harness.md). Moved out of [TAP::Parser](../Parser.md) & converted to a factory class to support extensible TAP source detective work by Steve Purkis. ## SEE ALSO [TAP::Object](../Object.md), [TAP::Parser](../Parser.md), [TAP::Parser::SourceHandler](SourceHandler.md), [TAP::Parser::SourceHandler::File](SourceHandler/File.md), [TAP::Parser::SourceHandler::Perl](SourceHandler/Perl.md), [TAP::Parser::SourceHandler::RawTAP](SourceHandler/RawTAP.md), [TAP::Parser::SourceHandler::Handle](SourceHandler/Handle.md), [TAP::Parser::SourceHandler::Executable](SourceHandler/Executable.md)