Debian Codegraph @

upstream/mageia-cauldron/man3pm/TAP::Parser::SourceHandler.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "TAP::Parser::SourceHandler 3pm"
61 .TH TAP::Parser::SourceHandler 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 TAP::Parser::SourceHandler \- Base class for different TAP source handlers
68 .SH VERSION
69 .IX Header "VERSION"
70 Version 3.50
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 2
74 \& # abstract class \- don\*(Aqt use directly!
75 \& # see TAP::Parser::IteratorFactory for general usage
76 \&
77 \& # must be sub\-classed for use
78 \& package MySourceHandler;
79 \& use base \*(AqTAP::Parser::SourceHandler\*(Aq;
80 \& sub can_handle { return $confidence_level }
81 \& sub make_iterator { return $iterator }
82 \&
83 \& # see example below for more details
84 .Ve
85 .SH DESCRIPTION
86 .IX Header "DESCRIPTION"
87 This is an abstract base class for TAP::Parser::Source handlers / handlers.
88 .PP
89 A \f(CW\*(C`TAP::Parser::SourceHandler\*(C'\fR does whatever is necessary to produce & capture
90 a stream of TAP from the \fIraw\fR source, and package it up in a
91 TAP::Parser::Iterator for the parser to consume.
92 .PP
93 \&\f(CW\*(C`SourceHandlers\*(C'\fR must implement the \fIsource detection & handling\fR interface
94 used by TAP::Parser::IteratorFactory. At 2 methods, the interface is pretty
95 simple: "can_handle" and "make_source".
96 .PP
97 Unless you\*(Aqre writing a new TAP::Parser::SourceHandler, a plugin, or
98 subclassing TAP::Parser, you probably won\*(Aqt need to use this module directly.
99 .SH METHODS
100 .IX Header "METHODS"
101 .SS "Class Methods"
102 .IX Subsection "Class Methods"
103 \fR\f(CI\*(C`can_handle\*(C'\fR\fI\fR
104 .IX Subsection "can_handle"
105 .PP
106 \&\fIAbstract method\fR.
107 .PP
108 .Vb 1
109 \& my $vote = $class\->can_handle( $source );
110 .Ve
111 .PP
112 \&\f(CW$source\fR is a TAP::Parser::Source.
113 .PP
114 Returns a number between \f(CW0\fR & \f(CW1\fR reflecting how confidently the raw source
115 can be handled. For example, \f(CW0\fR means the source cannot handle it, \f(CW0.5\fR
116 means it may be able to, and \f(CW1\fR means it definitely can. See
117 "detect_source" in TAP::Parser::IteratorFactory for details on how this is used.
118 .PP
119 \fR\f(CI\*(C`make_iterator\*(C'\fR\fI\fR
120 .IX Subsection "make_iterator"
121 .PP
122 \&\fIAbstract method\fR.
123 .PP
124 .Vb 1
125 \& my $iterator = $class\->make_iterator( $source );
126 .Ve
127 .PP
128 \&\f(CW$source\fR is a TAP::Parser::Source.
129 .PP
130 Returns a new TAP::Parser::Iterator object for use by the TAP::Parser.
131 \&\f(CW\*(C`croak\*(C'\fRs on error.
132 .SH SUBCLASSING
133 .IX Header "SUBCLASSING"
134 Please see "SUBCLASSING" in TAP::Parser for a subclassing overview, and any
135 of the subclasses that ship with this module as an example. What follows is
136 a quick overview.
137 .PP
138 Start by familiarizing yourself with TAP::Parser::Source and
139 TAP::Parser::IteratorFactory. TAP::Parser::SourceHandler::RawTAP is
140 the easiest sub\-class to use as an example.
141 .PP
142 It\*(Aqs important to point out that if you want your subclass to be automatically
143 used by TAP::Parser you\*(Aqll have to and make sure it gets loaded somehow.
144 If you\*(Aqre using prove you can write an App::Prove plugin. If you\*(Aqre
145 using TAP::Parser or TAP::Harness directly (e.g. through a custom script,
146 ExtUtils::MakeMaker, or Module::Build) you can use the \f(CW\*(C`config\*(C'\fR option
147 which will cause "load_sources" in TAP::Parser::IteratorFactory to load your
148 subclass).
149 .PP
150 Don\*(Aqt forget to register your class with
151 "register_handler" in TAP::Parser::IteratorFactory.
152 .SS Example
153 .IX Subsection "Example"
154 .Vb 1
155 \& package MySourceHandler;
156 \&
157 \& use strict;
158 \&
159 \& use MySourceHandler; # see TAP::Parser::SourceHandler
160 \& use TAP::Parser::IteratorFactory;
161 \&
162 \& use base \*(AqTAP::Parser::SourceHandler\*(Aq;
163 \&
164 \& TAP::Parser::IteratorFactory\->register_handler( _\|_PACKAGE_\|_ );
165 \&
166 \& sub can_handle {
167 \& my ( $class, $src ) = @_;
168 \& my $meta = $src\->meta;
169 \& my $config = $src\->config_for( $class );
170 \&
171 \& if ($config\->{accept_all}) {
172 \& return 1.0;
173 \& } elsif (my $file = $meta\->{file}) {
174 \& return 0.0 unless $file\->{exists};
175 \& return 1.0 if $file\->{lc_ext} eq \*(Aq.tap\*(Aq;
176 \& return 0.9 if $file\->{shebang} && $file\->{shebang} =~ /^#!.+tap/;
177 \& return 0.5 if $file\->{text};
178 \& return 0.1 if $file\->{binary};
179 \& } elsif ($meta\->{scalar}) {
180 \& return 0.8 if $$raw_source_ref =~ /\ed\e.\e.\ed/;
181 \& return 0.6 if $meta\->{has_newlines};
182 \& } elsif ($meta\->{array}) {
183 \& return 0.8 if $meta\->{size} < 5;
184 \& return 0.6 if $raw_source_ref\->[0] =~ /foo/;
185 \& return 0.5;
186 \& } elsif ($meta\->{hash}) {
187 \& return 0.6 if $raw_source_ref\->{foo};
188 \& return 0.2;
189 \& }
190 \&
191 \& return 0;
192 \& }
193 \&
194 \& sub make_iterator {
195 \& my ($class, $source) = @_;
196 \& # this is where you manipulate the source and
197 \& # capture the stream of TAP in an iterator
198 \& # either pick a TAP::Parser::Iterator::* or write your own...
199 \& my $iterator = TAP::Parser::Iterator::Array\->new([ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ]);
200 \& return $iterator;
201 \& }
202 \&
203 \& 1;
204 .Ve
205 .SH AUTHORS
206 .IX Header "AUTHORS"
207 TAPx Developers.
208 .PP
209 Source detection stuff added by Steve Purkis
210 .SH "SEE ALSO"
211 .IX Header "SEE ALSO"
212 TAP::Object,
213 TAP::Parser,
214 TAP::Parser::Source,
215 TAP::Parser::Iterator,
216 TAP::Parser::IteratorFactory,
217 TAP::Parser::SourceHandler::Executable,
218 TAP::Parser::SourceHandler::Perl,
219 TAP::Parser::SourceHandler::File,
220 TAP::Parser::SourceHandler::Handle,
221 TAP::Parser::SourceHandler::RawTAP