TAP::Parser::SourceHandler(3pm)

1TAP::Parser::SourceHandUlseerr(3C)ontributed Perl DocumeTnAtPa:t:iPoanrser::SourceHandler(3)
2
3
4

NAME

6       TAP::Parser::SourceHandler - Base class for different TAP source
7       handlers
8

VERSION

10       Version 3.44
11

SYNOPSIS

13         # abstract class - don't use directly!
14         # see TAP::Parser::IteratorFactory for general usage
15
16         # must be sub-classed for use
17         package MySourceHandler;
18         use base 'TAP::Parser::SourceHandler';
19         sub can_handle    { return $confidence_level }
20         sub make_iterator { return $iterator }
21
22         # see example below for more details
23

DESCRIPTION

25       This is an abstract base class for TAP::Parser::Source handlers /
26       handlers.
27
28       A "TAP::Parser::SourceHandler" does whatever is necessary to produce &
29       capture a stream of TAP from the raw source, and package it up in a
30       TAP::Parser::Iterator for the parser to consume.
31
32       "SourceHandlers" must implement the source detection & handling
33       interface used by TAP::Parser::IteratorFactory.  At 2 methods, the
34       interface is pretty simple: "can_handle" and "make_source".
35
36       Unless you're writing a new TAP::Parser::SourceHandler, a plugin, or
37       subclassing TAP::Parser, you probably won't need to use this module
38       directly.
39

METHODS

41   Class Methods
42       "can_handle"
43
44       Abstract method.
45
46         my $vote = $class->can_handle( $source );
47
48       $source is a TAP::Parser::Source.
49
50       Returns a number between 0 & 1 reflecting how confidently the raw
51       source can be handled.  For example, 0 means the source cannot handle
52       it, 0.5 means it may be able to, and 1 means it definitely can.  See
53       "detect_source" in TAP::Parser::IteratorFactory for details on how this
54       is used.
55
56       "make_iterator"
57
58       Abstract method.
59
60         my $iterator = $class->make_iterator( $source );
61
62       $source is a TAP::Parser::Source.
63
64       Returns a new TAP::Parser::Iterator object for use by the TAP::Parser.
65       "croak"s on error.
66

SUBCLASSING

68       Please see "SUBCLASSING" in TAP::Parser for a subclassing overview, and
69       any of the subclasses that ship with this module as an example.  What
70       follows is a quick overview.
71
72       Start by familiarizing yourself with TAP::Parser::Source and
73       TAP::Parser::IteratorFactory.  TAP::Parser::SourceHandler::RawTAP is
74       the easiest sub-class to use as an example.
75
76       It's important to point out that if you want your subclass to be
77       automatically used by TAP::Parser you'll have to and make sure it gets
78       loaded somehow.  If you're using prove you can write an App::Prove
79       plugin.  If you're using TAP::Parser or TAP::Harness directly (e.g.
80       through a custom script, ExtUtils::MakeMaker, or Module::Build) you can
81       use the "config" option which will cause "load_sources" in
82       TAP::Parser::IteratorFactory to load your subclass).
83
84       Don't forget to register your class with "register_handler" in
85       TAP::Parser::IteratorFactory.
86
87   Example
88         package MySourceHandler;
89
90         use strict;
91
92         use MySourceHandler; # see TAP::Parser::SourceHandler
93         use TAP::Parser::IteratorFactory;
94
95         use base 'TAP::Parser::SourceHandler';
96
97         TAP::Parser::IteratorFactory->register_handler( __PACKAGE__ );
98
99         sub can_handle {
100             my ( $class, $src ) = @_;
101             my $meta   = $src->meta;
102             my $config = $src->config_for( $class );
103
104             if ($config->{accept_all}) {
105                 return 1.0;
106             } elsif (my $file = $meta->{file}) {
107                 return 0.0 unless $file->{exists};
108                 return 1.0 if $file->{lc_ext} eq '.tap';
109                 return 0.9 if $file->{shebang} && $file->{shebang} =~ /^#!.+tap/;
110                 return 0.5 if $file->{text};
111                 return 0.1 if $file->{binary};
112             } elsif ($meta->{scalar}) {
113                 return 0.8 if $$raw_source_ref =~ /\d\.\.\d/;
114                 return 0.6 if $meta->{has_newlines};
115             } elsif ($meta->{array}) {
116                 return 0.8 if $meta->{size} < 5;
117                 return 0.6 if $raw_source_ref->[0] =~ /foo/;
118                 return 0.5;
119             } elsif ($meta->{hash}) {
120                 return 0.6 if $raw_source_ref->{foo};
121                 return 0.2;
122             }
123
124             return 0;
125         }
126
127         sub make_iterator {
128             my ($class, $source) = @_;
129             # this is where you manipulate the source and
130             # capture the stream of TAP in an iterator
131             # either pick a TAP::Parser::Iterator::* or write your own...
132             my $iterator = TAP::Parser::Iterator::Array->new([ 'foo', 'bar' ]);
133             return $iterator;
134         }
135
136         1;
137

AUTHORS

139       TAPx Developers.
140
141       Source detection stuff added by Steve Purkis
142