# man > TAP::Parser::SourceHandler

## 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)