TAP::Parser::SourceHanUser(Contributed Perl DocumTAP::Parser::SourceHandler(3)

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

VERSION
       Version 3.28

SYNOPSIS
         # abstract class - don't use directly!
         # see TAP::Parser::IteratorFactory for general usage

         # must be sub-classed for use
         package MySourceHandler;
         use base qw( TAP::Parser::SourceHandler );
         sub canhandle    { return $confidencelevel }
         sub makeiterator { return $iterator }

         # 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: "canhandle" and "makesource".

       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
       "canhandle"

       Abstract method.

         my $vote = $class->canhandle( $source );

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

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

       "makeiterator"

       Abstract method.

         my $iterator = $class->makeiterator( $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 an 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 "loadsources" in
       TAP::Parser::IteratorFactory to load your subclass).

       Don't forget to register your class with "registerhandler" in
       TAP::Parser::IteratorFactory.

   Example
         package MySourceHandler;

         use strict;
         use vars '@ISA'; # compat with older perls

         use MySourceHandler; # see TAP::Parser::SourceHandler
         use TAP::Parser::IteratorFactory;

         @ISA = qw( TAP::Parser::SourceHandler );

         TAP::Parser::IteratorFactory->registerhandler( PACKAGE );

         sub canhandle {
             my ( $class, $src ) = @;
             my $meta   = $src->meta;
             my $config = $src->configfor( $class );

             if ($config->{acceptall}) {
                 return 1.0;
             } elsif (my $file = $meta->{file}) {
                 return 0.0 unless $file->{exists};
                 return 1.0 if $file->{lcext} 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 $$rawsourceref =~ /\d\.\.\d/;
                 return 0.6 if $meta->{hasnewlines};
             } elsif ($meta->{array}) {
                 return 0.8 if $meta->{size} < 5;
                 return 0.6 if $rawsourceref->[0] =~ /foo/;
                 return 0.5;
             } elsif ($meta->{hash}) {
                 return 0.6 if $rawsourceref->{foo};
                 return 0.2;
             }

             return 0;
         }

         sub makeiterator {
             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

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



perl v5.16.3                      2013-05-02     TAP::Parser::SourceHandler(3)