1package TAP::Parser::SourceHandler; 2 3use strict; 4use vars qw($VERSION @ISA); 5 6use TAP::Object (); 7use TAP::Parser::Iterator (); 8 9@ISA = qw(TAP::Object); 10 11=head1 NAME 12 13TAP::Parser::SourceHandler - Base class for different TAP source handlers 14 15=head1 VERSION 16 17Version 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 38This is an abstract base class for L<TAP::Parser::Source> handlers / handlers. 39 40A C<TAP::Parser::SourceHandler> does whatever is necessary to produce & capture 41a stream of TAP from the I<raw> source, and package it up in a 42L<TAP::Parser::Iterator> for the parser to consume. 43 44C<SourceHandlers> must implement the I<source detection & handling> interface 45used by L<TAP::Parser::IteratorFactory>. At 2 methods, the interface is pretty 46simple: L</can_handle> and L</make_source>. 47 48Unless you're writing a new L<TAP::Parser::SourceHandler>, a plugin, or 49subclassing 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 57I<Abstract method>. 58 59 my $vote = $class->can_handle( $source ); 60 61C<$source> is a L<TAP::Parser::Source>. 62 63Returns a number between C<0> & C<1> reflecting how confidently the raw source 64can be handled. For example, C<0> means the source cannot handle it, C<0.5> 65means it may be able to, and C<1> means it definitely can. See 66L<TAP::Parser::IteratorFactory/detect_source> for details on how this is used. 67 68=cut 69 70sub 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 79I<Abstract method>. 80 81 my $iterator = $class->make_iterator( $source ); 82 83C<$source> is a L<TAP::Parser::Source>. 84 85Returns a new L<TAP::Parser::Iterator> object for use by the L<TAP::Parser>. 86C<croak>s on error. 87 88=cut 89 90sub make_iterator { 91 my ( $class, $args ) = @_; 92 $class->_croak( 93 "Abstract method 'make_iterator' not implemented for $class!"); 94 return; 95} 961; 97 98__END__ 99 100=head1 SUBCLASSING 101 102Please see L<TAP::Parser/SUBCLASSING> for a subclassing overview, and any 103of the subclasses that ship with this module as an example. What follows is 104a quick overview. 105 106Start by familiarizing yourself with L<TAP::Parser::Source> and 107L<TAP::Parser::IteratorFactory>. L<TAP::Parser::SourceHandler::RawTAP> is 108the easiest sub-class to use an an example. 109 110It's important to point out that if you want your subclass to be automatically 111used by L<TAP::Parser> you'll have to and make sure it gets loaded somehow. 112If you're using L<prove> you can write an L<App::Prove> plugin. If you're 113using L<TAP::Parser> or L<TAP::Harness> directly (e.g. through a custom script, 114L<ExtUtils::MakeMaker>, or L<Module::Build>) you can use the C<config> option 115which will cause L<TAP::Parser::IteratorFactory/load_sources> to load your 116subclass). 117 118Don't forget to register your class with 119L<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 176TAPx Developers. 177 178Source detection stuff added by Steve Purkis 179 180=head1 SEE ALSO 181 182L<TAP::Object>, 183L<TAP::Parser>, 184L<TAP::Parser::Source>, 185L<TAP::Parser::Iterator>, 186L<TAP::Parser::IteratorFactory>, 187L<TAP::Parser::SourceHandler::Executable>, 188L<TAP::Parser::SourceHandler::Perl>, 189L<TAP::Parser::SourceHandler::File>, 190L<TAP::Parser::SourceHandler::Handle>, 191L<TAP::Parser::SourceHandler::RawTAP> 192 193=cut 194 195