Debian Codegraph @

upstream/debian-unstable/man3/TAP::Parser::Source.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::Source 3perl"
58 .TH TAP::Parser::Source 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::Source \- a TAP source & meta data about it
65 .SH VERSION
66 .IX Header "VERSION"
67 Version 3.48
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 8
71 \& use TAP::Parser::Source;
72 \& my $source = TAP::Parser::Source\->new;
73 \& $source\->raw( \e\*(Aqreference to raw TAP source\*(Aq )
74 \& \->config( \e%config )
75 \& \->merge( $boolean )
76 \& \->switches( \e@switches )
77 \& \->test_args( \e@args )
78 \& \->assemble_meta;
79 \&
80 \& do { ... } if $source\->meta\->{is_file};
81 \& # see assemble_meta for a full list of data available
82 .Ve
83 .SH DESCRIPTION
84 .IX Header "DESCRIPTION"
85 A TAP \fIsource\fR is something that produces a stream of TAP for the parser to
86 consume, such as an executable file, a text file, an archive, an IO handle, a
87 database, etc. \f(CW\*(C`TAP::Parser::Source\*(C'\fRs encapsulate these \fIraw\fR sources, and
88 provide some useful meta data about them. They are used by
89 TAP::Parser::SourceHandlers, which do whatever is required to produce &
90 capture 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 Unless you're writing a new TAP::Parser::SourceHandler, a plugin or
94 subclassing TAP::Parser, you probably won't need to use this module directly.
95 .SH METHODS
96 .IX Header "METHODS"
97 .SS "Class Methods"
98 .IX Subsection "Class Methods"
99 \fR\f(CI\*(C`new\*(C'\fR\fI\fR
100 .IX Subsection "new"
101 .PP
102 .Vb 1
103 \& my $source = TAP::Parser::Source\->new;
104 .Ve
105 .PP
106 Returns a new \f(CW\*(C`TAP::Parser::Source\*(C'\fR object.
107 .SS "Instance Methods"
108 .IX Subsection "Instance Methods"
109 \fR\f(CI\*(C`raw\*(C'\fR\fI\fR
110 .IX Subsection "raw"
111 .PP
112 .Vb 2
113 \& my $raw = $source\->raw;
114 \& $source\->raw( $some_value );
115 .Ve
116 .PP
117 Chaining getter/setter for the raw TAP source. This is a reference, as it may
118 contain large amounts of data (eg: raw TAP).
119 .PP
120 \fR\f(CI\*(C`meta\*(C'\fR\fI\fR
121 .IX Subsection "meta"
122 .PP
123 .Vb 2
124 \& my $meta = $source\->meta;
125 \& $source\->meta({ %some_value });
126 .Ve
127 .PP
128 Chaining getter/setter for meta data about the source. This defaults to an
129 empty hashref. See "assemble_meta" for more info.
130 .PP
131 \fR\f(CI\*(C`has_meta\*(C'\fR\fI\fR
132 .IX Subsection "has_meta"
133 .PP
134 True if the source has meta data.
135 .PP
136 \fR\f(CI\*(C`config\*(C'\fR\fI\fR
137 .IX Subsection "config"
138 .PP
139 .Vb 2
140 \& my $config = $source\->config;
141 \& $source\->config({ %some_value });
142 .Ve
143 .PP
144 Chaining getter/setter for the source's configuration, if any has been provided
145 by the user. How it's used is up to you. This defaults to an empty hashref.
146 See "config_for" for more info.
147 .PP
148 \fR\f(CI\*(C`merge\*(C'\fR\fI\fR
149 .IX Subsection "merge"
150 .PP
151 .Vb 2
152 \& my $merge = $source\->merge;
153 \& $source\->config( $bool );
154 .Ve
155 .PP
156 Chaining getter/setter for the flag that dictates whether STDOUT and STDERR
157 should be merged (where appropriate). Defaults to undef.
158 .PP
159 \fR\f(CI\*(C`switches\*(C'\fR\fI\fR
160 .IX Subsection "switches"
161 .PP
162 .Vb 2
163 \& my $switches = $source\->switches;
164 \& $source\->config([ @switches ]);
165 .Ve
166 .PP
167 Chaining getter/setter for the list of command-line switches that should be
168 passed to the source (where appropriate). Defaults to undef.
169 .PP
170 \fR\f(CI\*(C`test_args\*(C'\fR\fI\fR
171 .IX Subsection "test_args"
172 .PP
173 .Vb 2
174 \& my $test_args = $source\->test_args;
175 \& $source\->config([ @test_args ]);
176 .Ve
177 .PP
178 Chaining getter/setter for the list of command-line arguments that should be
179 passed to the source (where appropriate). Defaults to undef.
180 .PP
181 \fR\f(CI\*(C`assemble_meta\*(C'\fR\fI\fR
182 .IX Subsection "assemble_meta"
183 .PP
184 .Vb 1
185 \& my $meta = $source\->assemble_meta;
186 .Ve
187 .PP
188 Gathers meta data about the "raw" source, stashes it in "meta" and returns
189 it as a hashref. This is done so that the TAP::Parser::SourceHandlers don't
190 have to repeat common checks. Currently this includes:
191 .PP
192 .Vb 3
193 \& is_scalar => $bool,
194 \& is_hash => $bool,
195 \& is_array => $bool,
196 \&
197 \& # for scalars:
198 \& length => $n
199 \& has_newlines => $bool
200 \&
201 \& # only done if the scalar looks like a filename
202 \& is_file => $bool,
203 \& is_dir => $bool,
204 \& is_symlink => $bool,
205 \& file => {
206 \& # only done if the scalar looks like a filename
207 \& basename => $string, # including ext
208 \& dir => $string,
209 \& ext => $string,
210 \& lc_ext => $string,
211 \& # system checks
212 \& exists => $bool,
213 \& stat => [ ... ], # perldoc \-f stat
214 \& empty => $bool,
215 \& size => $n,
216 \& text => $bool,
217 \& binary => $bool,
218 \& read => $bool,
219 \& write => $bool,
220 \& execute => $bool,
221 \& setuid => $bool,
222 \& setgid => $bool,
223 \& sticky => $bool,
224 \& is_file => $bool,
225 \& is_dir => $bool,
226 \& is_symlink => $bool,
227 \& # only done if the file\*(Aqs a symlink
228 \& lstat => [ ... ], # perldoc \-f lstat
229 \& # only done if the file\*(Aqs a readable text file
230 \& shebang => $first_line,
231 \& }
232 \&
233 \& # for arrays:
234 \& size => $n,
235 .Ve
236 .PP
237 \fR\f(CI\*(C`shebang\*(C'\fR\fI\fR
238 .IX Subsection "shebang"
239 .PP
240 Get the shebang line for a script file.
241 .PP
242 .Vb 1
243 \& my $shebang = TAP::Parser::Source\->shebang( $some_script );
244 .Ve
245 .PP
246 May be called as a class method
247 .PP
248 \fR\f(CI\*(C`config_for\*(C'\fR\fI\fR
249 .IX Subsection "config_for"
250 .PP
251 .Vb 1
252 \& my $config = $source\->config_for( $class );
253 .Ve
254 .PP
255 Returns "config" for the \f(CW$class\fR given. Class names may be fully qualified
256 or abbreviated, eg:
257 .PP
258 .Vb 3
259 \& # these are equivalent
260 \& $source\->config_for( \*(AqPerl\*(Aq );
261 \& $source\->config_for( \*(AqTAP::Parser::SourceHandler::Perl\*(Aq );
262 .Ve
263 .PP
264 If a fully qualified \f(CW$class\fR is given, its abbreviated version is checked first.
265 .SH AUTHORS
266 .IX Header "AUTHORS"
267 Steve Purkis.
268 .SH "SEE ALSO"
269 .IX Header "SEE ALSO"
270 TAP::Object,
271 TAP::Parser,
272 TAP::Parser::IteratorFactory,
273 TAP::Parser::SourceHandler