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