Debian Codegraph @

upstream/debian-unstable/man3/TAP::Parser::SourceHandler.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (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 .\"
57 .IX Title "TAP::Parser::SourceHandler 3perl"
58 .TH TAP::Parser::SourceHandler 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 TAP::Parser::SourceHandler \- Base class for different TAP source handlers
65 .SH VERSION
66 .IX Header "VERSION"
67 Version 3.48
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& # abstract class \- don\*(Aqt use directly!
72 \& # see TAP::Parser::IteratorFactory for general usage
73 \&
74 \& # must be sub\-classed for use
75 \& package MySourceHandler;
76 \& use base \*(AqTAP::Parser::SourceHandler\*(Aq;
77 \& sub can_handle { return $confidence_level }
78 \& sub make_iterator { return $iterator }
79 \&
80 \& # see example below for more details
81 .Ve
82 .SH DESCRIPTION
83 .IX Header "DESCRIPTION"
84 This is an abstract base class for TAP::Parser::Source handlers / handlers.
85 .PP
86 A \f(CW\*(C`TAP::Parser::SourceHandler\*(C'\fR does whatever is necessary to produce & capture
87 a stream of TAP from the \fIraw\fR source, and package it up in a
88 TAP::Parser::Iterator for the parser to consume.
89 .PP
90 \&\f(CW\*(C`SourceHandlers\*(C'\fR must implement the \fIsource detection & handling\fR interface
91 used by TAP::Parser::IteratorFactory. At 2 methods, the interface is pretty
92 simple: "can_handle" and "make_source".
93 .PP
94 Unless you're writing a new TAP::Parser::SourceHandler, a plugin, or
95 subclassing TAP::Parser, you probably won't need to use this module directly.
96 .SH METHODS
97 .IX Header "METHODS"
98 .SS "Class Methods"
99 .IX Subsection "Class Methods"
100 \fR\f(CI\*(C`can_handle\*(C'\fR\fI\fR
101 .IX Subsection "can_handle"
102 .PP
103 \&\fIAbstract method\fR.
104 .PP
105 .Vb 1
106 \& my $vote = $class\->can_handle( $source );
107 .Ve
108 .PP
109 \&\f(CW$source\fR is a TAP::Parser::Source.
110 .PP
111 Returns a number between \f(CW0\fR & \f(CW1\fR reflecting how confidently the raw source
112 can be handled. For example, \f(CW0\fR means the source cannot handle it, \f(CW0.5\fR
113 means it may be able to, and \f(CW1\fR means it definitely can. See
114 "detect_source" in TAP::Parser::IteratorFactory for details on how this is used.
115 .PP
116 \fR\f(CI\*(C`make_iterator\*(C'\fR\fI\fR
117 .IX Subsection "make_iterator"
118 .PP
119 \&\fIAbstract method\fR.
120 .PP
121 .Vb 1
122 \& my $iterator = $class\->make_iterator( $source );
123 .Ve
124 .PP
125 \&\f(CW$source\fR is a TAP::Parser::Source.
126 .PP
127 Returns a new TAP::Parser::Iterator object for use by the TAP::Parser.
128 \&\f(CW\*(C`croak\*(C'\fRs on error.
129 .SH SUBCLASSING
130 .IX Header "SUBCLASSING"
131 Please see "SUBCLASSING" in TAP::Parser for a subclassing overview, and any
132 of the subclasses that ship with this module as an example. What follows is
133 a quick overview.
134 .PP
135 Start by familiarizing yourself with TAP::Parser::Source and
136 TAP::Parser::IteratorFactory. TAP::Parser::SourceHandler::RawTAP is
137 the easiest sub-class to use as an example.
138 .PP
139 It's important to point out that if you want your subclass to be automatically
140 used by TAP::Parser you'll have to and make sure it gets loaded somehow.
141 If you're using prove you can write an App::Prove plugin. If you're
142 using TAP::Parser or TAP::Harness directly (e.g. through a custom script,
143 ExtUtils::MakeMaker, or Module::Build) you can use the \f(CW\*(C`config\*(C'\fR option
144 which will cause "load_sources" in TAP::Parser::IteratorFactory to load your
145 subclass).
146 .PP
147 Don't forget to register your class with
148 "register_handler" in TAP::Parser::IteratorFactory.
149 .SS Example
150 .IX Subsection "Example"
151 .Vb 1
152 \& package MySourceHandler;
153 \&
154 \& use strict;
155 \&
156 \& use MySourceHandler; # see TAP::Parser::SourceHandler
157 \& use TAP::Parser::IteratorFactory;
158 \&
159 \& use base \*(AqTAP::Parser::SourceHandler\*(Aq;
160 \&
161 \& TAP::Parser::IteratorFactory\->register_handler( _\|_PACKAGE_\|_ );
162 \&
163 \& sub can_handle {
164 \& my ( $class, $src ) = @_;
165 \& my $meta = $src\->meta;
166 \& my $config = $src\->config_for( $class );
167 \&
168 \& if ($config\->{accept_all}) {
169 \& return 1.0;
170 \& } elsif (my $file = $meta\->{file}) {
171 \& return 0.0 unless $file\->{exists};
172 \& return 1.0 if $file\->{lc_ext} eq \*(Aq.tap\*(Aq;
173 \& return 0.9 if $file\->{shebang} && $file\->{shebang} =~ /^#!.+tap/;
174 \& return 0.5 if $file\->{text};
175 \& return 0.1 if $file\->{binary};
176 \& } elsif ($meta\->{scalar}) {
177 \& return 0.8 if $$raw_source_ref =~ /\ed\e.\e.\ed/;
178 \& return 0.6 if $meta\->{has_newlines};
179 \& } elsif ($meta\->{array}) {
180 \& return 0.8 if $meta\->{size} < 5;
181 \& return 0.6 if $raw_source_ref\->[0] =~ /foo/;
182 \& return 0.5;
183 \& } elsif ($meta\->{hash}) {
184 \& return 0.6 if $raw_source_ref\->{foo};
185 \& return 0.2;
186 \& }
187 \&
188 \& return 0;
189 \& }
190 \&
191 \& sub make_iterator {
192 \& my ($class, $source) = @_;
193 \& # this is where you manipulate the source and
194 \& # capture the stream of TAP in an iterator
195 \& # either pick a TAP::Parser::Iterator::* or write your own...
196 \& my $iterator = TAP::Parser::Iterator::Array\->new([ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ]);
197 \& return $iterator;
198 \& }
199 \&
200 \& 1;
201 .Ve
202 .SH AUTHORS
203 .IX Header "AUTHORS"
204 TAPx Developers.
205 .PP
206 Source detection stuff added by Steve Purkis
207 .SH "SEE ALSO"
208 .IX Header "SEE ALSO"
209 TAP::Object,
210 TAP::Parser,
211 TAP::Parser::Source,
212 TAP::Parser::Iterator,
213 TAP::Parser::IteratorFactory,
214 TAP::Parser::SourceHandler::Executable,
215 TAP::Parser::SourceHandler::Perl,
216 TAP::Parser::SourceHandler::File,
217 TAP::Parser::SourceHandler::Handle,
218 TAP::Parser::SourceHandler::RawTAP