NAME

TAP::Parser::SourceHandler - Base class for different TAP source handlers

VERSION

Version 3.42

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

This is an abstract base class for the TAP::Parser::Source manpage handlers / handlers.

A TAP::Parser::SourceHandler does whatever is necessary to produce & capture a stream of TAP from the raw source, and package it up in a the TAP::Parser::Iterator manpage for the parser to consume.

SourceHandlers must implement the source detection & handling interface used by the TAP::Parser::IteratorFactory manpage. At 2 methods, the interface is pretty simple: can_handle and make_source.

Unless you're writing a new the TAP::Parser::SourceHandler manpage, a plugin, or subclassing the TAP::Parser manpage, 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 the TAP::Parser::Source manpage.

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 the TAP::Parser::IteratorFactory manpage for details on how this is used.

`make_iterator`

Abstract method.

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

$source is a the TAP::Parser::Source manpage.

Returns a new the TAP::Parser::Iterator manpage object for use by the the TAP::Parser manpage. croaks on error.

SUBCLASSING

Please see SUBCLASSING in the TAP::Parser manpage 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 the TAP::Parser::Source manpage and the TAP::Parser::IteratorFactory manpage. the TAP::Parser::SourceHandler::RawTAP manpage 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 the TAP::Parser manpage you'll have to and make sure it gets loaded somehow. If you're using prove you can write an the App::Prove manpage plugin. If you're using the TAP::Parser manpage or the TAP::Harness manpage directly (e.g. through a custom script, the ExtUtils::MakeMaker manpage, or the Module::Build manpage) you can use the config option which will cause load_sources in the TAP::Parser::IteratorFactory manpage to load your subclass).

Don't forget to register your class with register_handler in the TAP::Parser::IteratorFactory manpage.

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.

Source detection stuff added by Steve Purkis