Perl 5 version documentation

TAP::Parser::SourceHandler

NAME

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

VERSION

Version 3.42

SYNOPSIS

  1. # abstract class - don't use directly!
  2. # see TAP::Parser::IteratorFactory for general usage
  3. # must be sub-classed for use
  4. package MySourceHandler;
  5. use base 'TAP::Parser::SourceHandler';
  6. sub can_handle { return $confidence_level }
  7. sub make_iterator { return $iterator }
  8. # see example below for more details

DESCRIPTION

This is an abstract base class for TAP::Parser::Source 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 TAP::Parser::Iterator for the parser to consume.

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

Unless you're writing a new TAP::Parser::SourceHandler, a plugin, or subclassing TAP::Parser, you probably won't need to use this module directly.

METHODS

Class Methods

can_handle

Abstract method.

  1. my $vote = $class->can_handle( $source );

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

Returns a number between & 1 reflecting how confidently the raw source can be handled. For example, 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 details on how this is used.

make_iterator

Abstract method.

  1. 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. croak s on error.

SUBCLASSING

Please see SUBCLASSING in TAP::Parser 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 and TAP::Parser::IteratorFactory. TAP::Parser::SourceHandler::RawTAP 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 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.

Example

  1. package MySourceHandler;
  2. use strict;
  3. use MySourceHandler; # see TAP::Parser::SourceHandler
  4. use TAP::Parser::IteratorFactory;
  5. use base 'TAP::Parser::SourceHandler';
  6. TAP::Parser::IteratorFactory->register_handler( __PACKAGE__ );
  7. sub can_handle {
  8. my ( $class, $src ) = @_;
  9. my $meta = $src->meta;
  10. my $config = $src->config_for( $class );
  11. if ($config->{accept_all}) {
  12. return 1.0;
  13. } elsif (my $file = $meta->{file}) {
  14. return 0.0 unless $file->{exists};
  15. return 1.0 if $file->{lc_ext} eq '.tap';
  16. return 0.9 if $file->{shebang} && $file->{shebang} =~ /^#!.+tap/;
  17. return 0.5 if $file->{text};
  18. return 0.1 if $file->{binary};
  19. } elsif ($meta->{scalar}) {
  20. return 0.8 if $$raw_source_ref =~ /\d\.\.\d/;
  21. return 0.6 if $meta->{has_newlines};
  22. } elsif ($meta->{array}) {
  23. return 0.8 if $meta->{size} < 5;
  24. return 0.6 if $raw_source_ref->[0] =~ /foo/;
  25. return 0.5;
  26. } elsif ($meta->{hash}) {
  27. return 0.6 if $raw_source_ref->{foo};
  28. return 0.2;
  29. }
  30. return 0;
  31. }
  32. sub make_iterator {
  33. my ($class, $source) = @_;
  34. # this is where you manipulate the source and
  35. # capture the stream of TAP in an iterator
  36. # either pick a TAP::Parser::Iterator::* or write your own...
  37. my $iterator = TAP::Parser::Iterator::Array->new([ 'foo', 'bar' ]);
  38. return $iterator;
  39. }
  40. 1;

AUTHORS

TAPx Developers.

Source detection stuff added by Steve Purkis

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