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.28
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 qw( 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 an 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         use vars '@ISA'; # compat with older perls
92
93         use MySourceHandler; # see TAP::Parser::SourceHandler
94         use TAP::Parser::IteratorFactory;
95
96         @ISA = qw( TAP::Parser::SourceHandler );
97
98         TAP::Parser::IteratorFactory->register_handler( __PACKAGE__ );
99
100         sub can_handle {
101             my ( $class, $src ) = @_;
102             my $meta   = $src->meta;
103             my $config = $src->config_for( $class );
104
105             if ($config->{accept_all}) {
106                 return 1.0;
107             } elsif (my $file = $meta->{file}) {
108                 return 0.0 unless $file->{exists};
109                 return 1.0 if $file->{lc_ext} eq '.tap';
110                 return 0.9 if $file->{shebang} && $file->{shebang} =~ /^#!.+tap/;
111                 return 0.5 if $file->{text};
112                 return 0.1 if $file->{binary};
113             } elsif ($meta->{scalar}) {
114                 return 0.8 if $$raw_source_ref =~ /\d\.\.\d/;
115                 return 0.6 if $meta->{has_newlines};
116             } elsif ($meta->{array}) {
117                 return 0.8 if $meta->{size} < 5;
118                 return 0.6 if $raw_source_ref->[0] =~ /foo/;
119                 return 0.5;
120             } elsif ($meta->{hash}) {
121                 return 0.6 if $raw_source_ref->{foo};
122                 return 0.2;
123             }
124
125             return 0;
126         }
127
128         sub make_iterator {
129             my ($class, $source) = @_;
130             # this is where you manipulate the source and
131             # capture the stream of TAP in an iterator
132             # either pick a TAP::Parser::Iterator::* or write your own...
133             my $iterator = TAP::Parser::Iterator::Array->new([ 'foo', 'bar' ]);
134             return $iterator;
135         }
136
137         1;
138

AUTHORS

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