Commit | Line | Data |
---|---|---|
6d313664 CBW |
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 | ||
149d510d | 17 | Version 3.23 |
6d313664 CBW |
18 | |
19 | =cut | |
20 | ||
149d510d | 21 | $VERSION = '3.23'; |
6d313664 CBW |
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 | |
686add28 | 113 | using L<TAP::Parser> or L<TAP::Harness> directly (e.g. through a custom script, |
6d313664 CBW |
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 |