cpan/Test-Harness/lib/TAP/Parser/SourceHandler.pm

   1 package TAP::Parser::SourceHandler;
   2
   3 use strict;
   4 use vars qw($VERSION @ISA);
   5
   6 use TAP::Object           ();
   7 use TAP::Parser::Iterator ();
   8
   9 @ISA = qw(TAP::Object);
  10
  11 =head1 NAME
  12
  13 TAP::Parser::SourceHandler - Base class for different TAP source handlers
  14
  15 =head1 VERSION
  16
  17 Version 3.26
  18
  19 =cut
  20
  21 $VERSION = '3.26';
  22
  23 =head1 SYNOPSIS
  24
  25   # abstract class - don't use directly!
  26   # see TAP::Parser::IteratorFactory for general usage
  27
  28   # must be sub-classed for use
  29   package MySourceHandler;
  30   use base qw( TAP::Parser::SourceHandler );
  31   sub can_handle    { return $confidence_level }
  32   sub make_iterator { return $iterator }
  33
  34   # see example below for more details
  35
  36 =head1 DESCRIPTION
  37
  38 This is an abstract base class for L<TAP::Parser::Source> handlers / handlers.
  39
  40 A C<TAP::Parser::SourceHandler> does whatever is necessary to produce & capture
  41 a stream of TAP from the I<raw> source, and package it up in a
  42 L<TAP::Parser::Iterator> for the parser to consume.
  43
  44 C<SourceHandlers> must implement the I<source detection & handling> interface
  45 used by L<TAP::Parser::IteratorFactory>.  At 2 methods, the interface is pretty
  46 simple: L</can_handle> and L</make_source>.
  47
  48 Unless you're writing a new L<TAP::Parser::SourceHandler>, a plugin, or
  49 subclassing L<TAP::Parser>, you probably won't need to use this module directly.
  50
  51 =head1 METHODS
  52
  53 =head2 Class Methods
  54
  55 =head3 C<can_handle>
  56
  57 I<Abstract method>.
  58
  59   my $vote = $class->can_handle( $source );
  60
  61 C<$source> is a L<TAP::Parser::Source>.
  62
  63 Returns a number between C<0> & C<1> reflecting how confidently the raw source
  64 can be handled.  For example, C<0> means the source cannot handle it, C<0.5>
  65 means it may be able to, and C<1> means it definitely can.  See
  66 L<TAP::Parser::IteratorFactory/detect_source> for details on how this is used.
  67
  68 =cut
  69
  70 sub can_handle {
  71     my ( $class, $args ) = @_;
  72     $class->_croak(
  73         "Abstract method 'can_handle' not implemented for $class!");
  74     return;
  75 }
  76
  77 =head3 C<make_iterator>
  78
  79 I<Abstract method>.
  80
  81   my $iterator = $class->make_iterator( $source );
  82
  83 C<$source> is a L<TAP::Parser::Source>.
  84
  85 Returns a new L<TAP::Parser::Iterator> object for use by the L<TAP::Parser>.
  86 C<croak>s on error.
  87
  88 =cut
  89
  90 sub make_iterator {
  91     my ( $class, $args ) = @_;
  92     $class->_croak(
  93         "Abstract method 'make_iterator' not implemented for $class!");
  94     return;
  95 }
  96 1;
  97
  98 __END__
  99
 100 =head1 SUBCLASSING
 101
 102 Please see L<TAP::Parser/SUBCLASSING> for a subclassing overview, and any
 103 of the subclasses that ship with this module as an example.  What follows is
 104 a quick overview.
 105
 106 Start by familiarizing yourself with L<TAP::Parser::Source> and
 107 L<TAP::Parser::IteratorFactory>.  L<TAP::Parser::SourceHandler::RawTAP> is
 108 the easiest sub-class to use an an example.
 109
 110 It's important to point out that if you want your subclass to be automatically
 111 used by L<TAP::Parser> you'll have to and make sure it gets loaded somehow.
 112 If you're using L<prove> you can write an L<App::Prove> plugin.  If you're
 113 using L<TAP::Parser> or L<TAP::Harness> directly (e.g. through a custom script,
 114 L<ExtUtils::MakeMaker>, or L<Module::Build>) you can use the C<config> option
 115 which will cause L<TAP::Parser::IteratorFactory/load_sources> to load your
 116 subclass).
 117
 118 Don't forget to register your class with
 119 L<TAP::Parser::IteratorFactory/register_handler>.
 120
 121 =head2 Example
 122
 123   package MySourceHandler;
 124
 125   use strict;
 126   use vars '@ISA'; # compat with older perls
 127
 128   use MySourceHandler; # see TAP::Parser::SourceHandler
 129   use TAP::Parser::IteratorFactory;
 130
 131   @ISA = qw( TAP::Parser::SourceHandler );
 132
 133   TAP::Parser::IteratorFactory->register_handler( __PACKAGE__ );
 134
 135   sub can_handle {
 136       my ( $class, $src ) = @_;
 137       my $meta   = $src->meta;
 138       my $config = $src->config_for( $class );
 139
 140       if ($config->{accept_all}) {
 141           return 1.0;
 142       } elsif (my $file = $meta->{file}) {
 143           return 0.0 unless $file->{exists};
 144           return 1.0 if $file->{lc_ext} eq '.tap';
 145           return 0.9 if $file->{shebang} && $file->{shebang} =~ /^#!.+tap/;
 146           return 0.5 if $file->{text};
 147           return 0.1 if $file->{binary};
 148       } elsif ($meta->{scalar}) {
 149           return 0.8 if $$raw_source_ref =~ /\d\.\.\d/;
 150           return 0.6 if $meta->{has_newlines};
 151       } elsif ($meta->{array}) {
 152           return 0.8 if $meta->{size} < 5;
 153           return 0.6 if $raw_source_ref->[0] =~ /foo/;
 154           return 0.5;
 155       } elsif ($meta->{hash}) {
 156           return 0.6 if $raw_source_ref->{foo};
 157           return 0.2;
 158       }
 159
 160       return 0;
 161   }
 162
 163   sub make_iterator {
 164       my ($class, $source) = @_;
 165       # this is where you manipulate the source and
 166       # capture the stream of TAP in an iterator
 167       # either pick a TAP::Parser::Iterator::* or write your own...
 168       my $iterator = TAP::Parser::Iterator::Array->new([ 'foo', 'bar' ]);
 169       return $iterator;
 170   }
 171
 172   1;
 173
 174 =head1 AUTHORS
 175
 176 TAPx Developers.
 177
 178 Source detection stuff added by Steve Purkis
 179
 180 =head1 SEE ALSO
 181
 182 L<TAP::Object>,
 183 L<TAP::Parser>,
 184 L<TAP::Parser::Source>,
 185 L<TAP::Parser::Iterator>,
 186 L<TAP::Parser::IteratorFactory>,
 187 L<TAP::Parser::SourceHandler::Executable>,
 188 L<TAP::Parser::SourceHandler::Perl>,
 189 L<TAP::Parser::SourceHandler::File>,
 190 L<TAP::Parser::SourceHandler::Handle>,
 191 L<TAP::Parser::SourceHandler::RawTAP>
 192
 193 =cut
 194