Debian Codegraph @

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