Debian Codegraph @

upstream/debian-unstable/man3/TAP::Parser.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 3perl"
58 .TH TAP::Parser 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 \- Parse TAP output
65 .SH VERSION
66 .IX Header "VERSION"
67 Version 3.48
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use TAP::Parser;
72 \&
73 \& my $parser = TAP::Parser\->new( { source => $source } );
74 \&
75 \& while ( my $result = $parser\->next ) {
76 \& print $result\->as_string;
77 \& }
78 .Ve
79 .SH DESCRIPTION
80 .IX Header "DESCRIPTION"
81 \&\f(CW\*(C`TAP::Parser\*(C'\fR is designed to produce a proper parse of TAP output. For
82 an example of how to run tests through this module, see the simple
83 harnesses \f(CW\*(C`examples/\*(C'\fR.
84 .PP
85 There's a wiki dedicated to the Test Anything Protocol:
86 .PP
87 <http://testanything.org>
88 .PP
89 It includes the TAP::Parser Cookbook:
90 .PP
91 <http://testanything.org/testing\-with\-tap/perl/tap::parser\-cookbook.html>
92 .SH METHODS
93 .IX Header "METHODS"
94 .SS "Class Methods"
95 .IX Subsection "Class Methods"
96 \fR\f(CI\*(C`new\*(C'\fR\fI\fR
97 .IX Subsection "new"
98 .PP
99 .Vb 1
100 \& my $parser = TAP::Parser\->new(\e%args);
101 .Ve
102 .PP
103 Returns a new \f(CW\*(C`TAP::Parser\*(C'\fR object.
104 .PP
105 The arguments should be a hashref with \fIone\fR of the following keys:
106 .IP \(bu 4
107 \&\f(CW\*(C`source\*(C'\fR
108 .Sp
109 \&\fICHANGED in 3.18\fR
110 .Sp
111 This is the preferred method of passing input to the constructor.
112 .Sp
113 The \f(CW\*(C`source\*(C'\fR is used to create a TAP::Parser::Source that is passed to the
114 "iterator_factory_class" which in turn figures out how to handle the source and
115 creates a <TAP::Parser::Iterator> for it. The iterator is used by the parser to
116 read in the TAP stream.
117 .Sp
118 To configure the \fIIteratorFactory\fR use the \f(CW\*(C`sources\*(C'\fR parameter below.
119 .Sp
120 Note that \f(CW\*(C`source\*(C'\fR, \f(CW\*(C`tap\*(C'\fR and \f(CW\*(C`exec\*(C'\fR are \fImutually exclusive\fR.
121 .IP \(bu 4
122 \&\f(CW\*(C`tap\*(C'\fR
123 .Sp
124 \&\fICHANGED in 3.18\fR
125 .Sp
126 The value should be the complete TAP output.
127 .Sp
128 The \fItap\fR is used to create a TAP::Parser::Source that is passed to the
129 "iterator_factory_class" which in turn figures out how to handle the source and
130 creates a <TAP::Parser::Iterator> for it. The iterator is used by the parser to
131 read in the TAP stream.
132 .Sp
133 To configure the \fIIteratorFactory\fR use the \f(CW\*(C`sources\*(C'\fR parameter below.
134 .Sp
135 Note that \f(CW\*(C`source\*(C'\fR, \f(CW\*(C`tap\*(C'\fR and \f(CW\*(C`exec\*(C'\fR are \fImutually exclusive\fR.
136 .IP \(bu 4
137 \&\f(CW\*(C`exec\*(C'\fR
138 .Sp
139 Must be passed an array reference.
140 .Sp
141 The \fIexec\fR array ref is used to create a TAP::Parser::Source that is passed
142 to the "iterator_factory_class" which in turn figures out how to handle the
143 source and creates a <TAP::Parser::Iterator> for it. The iterator is used by
144 the parser to read in the TAP stream.
145 .Sp
146 By default the TAP::Parser::SourceHandler::Executable class will create a
147 TAP::Parser::Iterator::Process object to handle the source. This passes the
148 array reference strings as command arguments to IPC::Open3::open3:
149 .Sp
150 .Vb 1
151 \& exec => [ \*(Aq/usr/bin/ruby\*(Aq, \*(Aqt/my_test.rb\*(Aq ]
152 .Ve
153 .Sp
154 If any \f(CW\*(C`test_args\*(C'\fR are given they will be appended to the end of the command
155 argument list.
156 .Sp
157 To configure the \fIIteratorFactory\fR use the \f(CW\*(C`sources\*(C'\fR parameter below.
158 .Sp
159 Note that \f(CW\*(C`source\*(C'\fR, \f(CW\*(C`tap\*(C'\fR and \f(CW\*(C`exec\*(C'\fR are \fImutually exclusive\fR.
160 .PP
161 The following keys are optional.
162 .IP \(bu 4
163 \&\f(CW\*(C`sources\*(C'\fR
164 .Sp
165 \&\fINEW to 3.18\fR.
166 .Sp
167 If set, \f(CW\*(C`sources\*(C'\fR must be a hashref containing the names of the
168 TAP::Parser::SourceHandlers to load and/or configure. The values are a
169 hash of configuration that will be accessible to the source handlers via
170 "config_for" in TAP::Parser::Source.
171 .Sp
172 For example:
173 .Sp
174 .Vb 5
175 \& sources => {
176 \& Perl => { exec => \*(Aq/path/to/custom/perl\*(Aq },
177 \& File => { extensions => [ \*(Aq.tap\*(Aq, \*(Aq.txt\*(Aq ] },
178 \& MyCustom => { some => \*(Aqconfig\*(Aq },
179 \& }
180 .Ve
181 .Sp
182 This will cause \f(CW\*(C`TAP::Parser\*(C'\fR to pass custom configuration to two of the built\-
183 in source handlers \- TAP::Parser::SourceHandler::Perl,
184 TAP::Parser::SourceHandler::File \- and attempt to load the \f(CW\*(C`MyCustom\*(C'\fR
185 class. See "load_handlers" in TAP::Parser::IteratorFactory for more detail.
186 .Sp
187 The \f(CW\*(C`sources\*(C'\fR parameter affects how \f(CW\*(C`source\*(C'\fR, \f(CW\*(C`tap\*(C'\fR and \f(CW\*(C`exec\*(C'\fR parameters
188 are handled.
189 .Sp
190 See TAP::Parser::IteratorFactory, TAP::Parser::SourceHandler and subclasses for
191 more details.
192 .IP \(bu 4
193 \&\f(CW\*(C`callback\*(C'\fR
194 .Sp
195 If present, each callback corresponding to a given result type will be called
196 with the result as the argument if the \f(CW\*(C`run\*(C'\fR method is used:
197 .Sp
198 .Vb 7
199 \& my %callbacks = (
200 \& test => \e&test_callback,
201 \& plan => \e&plan_callback,
202 \& comment => \e&comment_callback,
203 \& bailout => \e&bailout_callback,
204 \& unknown => \e&unknown_callback,
205 \& );
206 \&
207 \& my $aggregator = TAP::Parser::Aggregator\->new;
208 \& for my $file ( @test_files ) {
209 \& my $parser = TAP::Parser\->new(
210 \& {
211 \& source => $file,
212 \& callbacks => \e%callbacks,
213 \& }
214 \& );
215 \& $parser\->run;
216 \& $aggregator\->add( $file, $parser );
217 \& }
218 .Ve
219 .IP \(bu 4
220 \&\f(CW\*(C`switches\*(C'\fR
221 .Sp
222 If using a Perl file as a source, optional switches may be passed which will
223 be used when invoking the perl executable.
224 .Sp
225 .Vb 4
226 \& my $parser = TAP::Parser\->new( {
227 \& source => $test_file,
228 \& switches => [ \*(Aq\-Ilib\*(Aq ],
229 \& } );
230 .Ve
231 .IP \(bu 4
232 \&\f(CW\*(C`test_args\*(C'\fR
233 .Sp
234 Used in conjunction with the \f(CW\*(C`source\*(C'\fR and \f(CW\*(C`exec\*(C'\fR option to supply a reference
235 to an \f(CW@ARGV\fR style array of arguments to pass to the test program.
236 .IP \(bu 4
237 \&\f(CW\*(C`spool\*(C'\fR
238 .Sp
239 If passed a filehandle will write a copy of all parsed TAP to that handle.
240 .IP \(bu 4
241 \&\f(CW\*(C`merge\*(C'\fR
242 .Sp
243 If false, STDERR is not captured (though it is 'relayed' to keep it
244 somewhat synchronized with STDOUT.)
245 .Sp
246 If true, STDERR and STDOUT are the same filehandle. This may cause
247 breakage if STDERR contains anything resembling TAP format, but does
248 allow exact synchronization.
249 .Sp
250 Subtleties of this behavior may be platform-dependent and may change in
251 the future.
252 .IP \(bu 4
253 \&\f(CW\*(C`grammar_class\*(C'\fR
254 .Sp
255 This option was introduced to let you easily customize which \fIgrammar\fR class
256 the parser should use. It defaults to TAP::Parser::Grammar.
257 .Sp
258 See also "make_grammar".
259 .IP \(bu 4
260 \&\f(CW\*(C`result_factory_class\*(C'\fR
261 .Sp
262 This option was introduced to let you easily customize which \fIresult\fR
263 factory class the parser should use. It defaults to
264 TAP::Parser::ResultFactory.
265 .Sp
266 See also "make_result".
267 .IP \(bu 4
268 \&\f(CW\*(C`iterator_factory_class\*(C'\fR
269 .Sp
270 \&\fICHANGED in 3.18\fR
271 .Sp
272 This option was introduced to let you easily customize which \fIiterator\fR
273 factory class the parser should use. It defaults to
274 TAP::Parser::IteratorFactory.
275 .SS "Instance Methods"
276 .IX Subsection "Instance Methods"
277 \fR\f(CI\*(C`next\*(C'\fR\fI\fR
278 .IX Subsection "next"
279 .PP
280 .Vb 4
281 \& my $parser = TAP::Parser\->new( { source => $file } );
282 \& while ( my $result = $parser\->next ) {
283 \& print $result\->as_string, "\en";
284 \& }
285 .Ve
286 .PP
287 This method returns the results of the parsing, one result at a time. Note
288 that it is destructive. You can't rewind and examine previous results.
289 .PP
290 If callbacks are used, they will be issued before this call returns.
291 .PP
292 Each result returned is a subclass of TAP::Parser::Result. See that
293 module and related classes for more information on how to use them.
294 .PP
295 \fR\f(CI\*(C`run\*(C'\fR\fI\fR
296 .IX Subsection "run"
297 .PP
298 .Vb 1
299 \& $parser\->run;
300 .Ve
301 .PP
302 This method merely runs the parser and parses all of the TAP.
303 .PP
304 \fR\f(CI\*(C`make_grammar\*(C'\fR\fI\fR
305 .IX Subsection "make_grammar"
306 .PP
307 Make a new TAP::Parser::Grammar object and return it. Passes through any
308 arguments given.
309 .PP
310 The \f(CW\*(C`grammar_class\*(C'\fR can be customized, as described in "new".
311 .PP
312 \fR\f(CI\*(C`make_result\*(C'\fR\fI\fR
313 .IX Subsection "make_result"
314 .PP
315 Make a new TAP::Parser::Result object using the parser's
316 TAP::Parser::ResultFactory, and return it. Passes through any arguments
317 given.
318 .PP
319 The \f(CW\*(C`result_factory_class\*(C'\fR can be customized, as described in "new".
320 .PP
321 \fR\f(CI\*(C`make_iterator_factory\*(C'\fR\fI\fR
322 .IX Subsection "make_iterator_factory"
323 .PP
324 \&\fINEW to 3.18\fR.
325 .PP
326 Make a new TAP::Parser::IteratorFactory object and return it. Passes through
327 any arguments given.
328 .PP
329 \&\f(CW\*(C`iterator_factory_class\*(C'\fR can be customized, as described in "new".
330 .SH "INDIVIDUAL RESULTS"
331 .IX Header "INDIVIDUAL RESULTS"
332 If you've read this far in the docs, you've seen this:
333 .PP
334 .Vb 3
335 \& while ( my $result = $parser\->next ) {
336 \& print $result\->as_string;
337 \& }
338 .Ve
339 .PP
340 Each result returned is a TAP::Parser::Result subclass, referred to as
341 \&\fIresult types\fR.
342 .SS "Result types"
343 .IX Subsection "Result types"
344 Basically, you fetch individual results from the TAP. The six types, with
345 examples of each, are as follows:
346 .IP \(bu 4
347 Version
348 .Sp
349 .Vb 1
350 \& TAP version 12
351 .Ve
352 .IP \(bu 4
353 Plan
354 .Sp
355 .Vb 1
356 \& 1..42
357 .Ve
358 .IP \(bu 4
359 Pragma
360 .Sp
361 .Vb 1
362 \& pragma +strict
363 .Ve
364 .IP \(bu 4
365 Test
366 .Sp
367 .Vb 1
368 \& ok 3 \- We should start with some foobar!
369 .Ve
370 .IP \(bu 4
371 Comment
372 .Sp
373 .Vb 1
374 \& # Hope we don\*(Aqt use up the foobar.
375 .Ve
376 .IP \(bu 4
377 Bailout
378 .Sp
379 .Vb 1
380 \& Bail out! We ran out of foobar!
381 .Ve
382 .IP \(bu 4
383 Unknown
384 .Sp
385 .Vb 1
386 \& ... yo, this ain\*(Aqt TAP! ...
387 .Ve
388 .PP
389 Each result fetched is a result object of a different type. There are common
390 methods to each result object and different types may have methods unique to
391 their type. Sometimes a type method may be overridden in a subclass, but its
392 use is guaranteed to be identical.
393 .SS "Common type methods"
394 .IX Subsection "Common type methods"
395 \fR\f(CI\*(C`type\*(C'\fR\fI\fR
396 .IX Subsection "type"
397 .PP
398 Returns the type of result, such as \f(CW\*(C`comment\*(C'\fR or \f(CW\*(C`test\*(C'\fR.
399 .PP
400 \fR\f(CI\*(C`as_string\*(C'\fR\fI\fR
401 .IX Subsection "as_string"
402 .PP
403 Prints a string representation of the token. This might not be the exact
404 output, however. Tests will have test numbers added if not present, TODO and
405 SKIP directives will be capitalized and, in general, things will be cleaned
406 up. If you need the original text for the token, see the \f(CW\*(C`raw\*(C'\fR method.
407 .PP
408 \fR\f(CI\*(C`raw\*(C'\fR\fI\fR
409 .IX Subsection "raw"
410 .PP
411 Returns the original line of text which was parsed.
412 .PP
413 \fR\f(CI\*(C`is_plan\*(C'\fR\fI\fR
414 .IX Subsection "is_plan"
415 .PP
416 Indicates whether or not this is the test plan line.
417 .PP
418 \fR\f(CI\*(C`is_test\*(C'\fR\fI\fR
419 .IX Subsection "is_test"
420 .PP
421 Indicates whether or not this is a test line.
422 .PP
423 \fR\f(CI\*(C`is_comment\*(C'\fR\fI\fR
424 .IX Subsection "is_comment"
425 .PP
426 Indicates whether or not this is a comment. Comments will generally only
427 appear in the TAP stream if STDERR is merged to STDOUT. See the
428 \&\f(CW\*(C`merge\*(C'\fR option.
429 .PP
430 \fR\f(CI\*(C`is_bailout\*(C'\fR\fI\fR
431 .IX Subsection "is_bailout"
432 .PP
433 Indicates whether or not this is bailout line.
434 .PP
435 \fR\f(CI\*(C`is_yaml\*(C'\fR\fI\fR
436 .IX Subsection "is_yaml"
437 .PP
438 Indicates whether or not the current item is a YAML block.
439 .PP
440 \fR\f(CI\*(C`is_unknown\*(C'\fR\fI\fR
441 .IX Subsection "is_unknown"
442 .PP
443 Indicates whether or not the current line could be parsed.
444 .PP
445 \fR\f(CI\*(C`is_ok\*(C'\fR\fI\fR
446 .IX Subsection "is_ok"
447 .PP
448 .Vb 1
449 \& if ( $result\->is_ok ) { ... }
450 .Ve
451 .PP
452 Reports whether or not a given result has passed. Anything which is \fBnot\fR a
453 test result returns true. This is merely provided as a convenient shortcut
454 which allows you to do this:
455 .PP
456 .Vb 5
457 \& my $parser = TAP::Parser\->new( { source => $source } );
458 \& while ( my $result = $parser\->next ) {
459 \& # only print failing results
460 \& print $result\->as_string unless $result\->is_ok;
461 \& }
462 .Ve
463 .ie n .SS """plan"" methods"
464 .el .SS "\f(CWplan\fP methods"
465 .IX Subsection "plan methods"
466 .Vb 1
467 \& if ( $result\->is_plan ) { ... }
468 .Ve
469 .PP
470 If the above evaluates as true, the following methods will be available on the
471 \&\f(CW$result\fR object.
472 .PP
473 \fR\f(CI\*(C`plan\*(C'\fR\fI\fR
474 .IX Subsection "plan"
475 .PP
476 .Vb 3
477 \& if ( $result\->is_plan ) {
478 \& print $result\->plan;
479 \& }
480 .Ve
481 .PP
482 This is merely a synonym for \f(CW\*(C`as_string\*(C'\fR.
483 .PP
484 \fR\f(CI\*(C`directive\*(C'\fR\fI\fR
485 .IX Subsection "directive"
486 .PP
487 .Vb 1
488 \& my $directive = $result\->directive;
489 .Ve
490 .PP
491 If a SKIP directive is included with the plan, this method will return it.
492 .PP
493 .Vb 1
494 \& 1..0 # SKIP: why bother?
495 .Ve
496 .PP
497 \fR\f(CI\*(C`explanation\*(C'\fR\fI\fR
498 .IX Subsection "explanation"
499 .PP
500 .Vb 1
501 \& my $explanation = $result\->explanation;
502 .Ve
503 .PP
504 If a SKIP directive was included with the plan, this method will return the
505 explanation, if any.
506 .ie n .SS """pragma"" methods"
507 .el .SS "\f(CWpragma\fP methods"
508 .IX Subsection "pragma methods"
509 .Vb 1
510 \& if ( $result\->is_pragma ) { ... }
511 .Ve
512 .PP
513 If the above evaluates as true, the following methods will be available on the
514 \&\f(CW$result\fR object.
515 .PP
516 \fR\f(CI\*(C`pragmas\*(C'\fR\fI\fR
517 .IX Subsection "pragmas"
518 .PP
519 Returns a list of pragmas each of which is a + or \- followed by the
520 pragma name.
521 .ie n .SS """comment"" methods"
522 .el .SS "\f(CWcomment\fP methods"
523 .IX Subsection "comment methods"
524 .Vb 1
525 \& if ( $result\->is_comment ) { ... }
526 .Ve
527 .PP
528 If the above evaluates as true, the following methods will be available on the
529 \&\f(CW$result\fR object.
530 .PP
531 \fR\f(CI\*(C`comment\*(C'\fR\fI\fR
532 .IX Subsection "comment"
533 .PP
534 .Vb 4
535 \& if ( $result\->is_comment ) {
536 \& my $comment = $result\->comment;
537 \& print "I have something to say: $comment";
538 \& }
539 .Ve
540 .ie n .SS """bailout"" methods"
541 .el .SS "\f(CWbailout\fP methods"
542 .IX Subsection "bailout methods"
543 .Vb 1
544 \& if ( $result\->is_bailout ) { ... }
545 .Ve
546 .PP
547 If the above evaluates as true, the following methods will be available on the
548 \&\f(CW$result\fR object.
549 .PP
550 \fR\f(CI\*(C`explanation\*(C'\fR\fI\fR
551 .IX Subsection "explanation"
552 .PP
553 .Vb 4
554 \& if ( $result\->is_bailout ) {
555 \& my $explanation = $result\->explanation;
556 \& print "We bailed out because ($explanation)";
557 \& }
558 .Ve
559 .PP
560 If, and only if, a token is a bailout token, you can get an "explanation" via
561 this method. The explanation is the text after the mystical "Bail out!" words
562 which appear in the tap output.
563 .ie n .SS """unknown"" methods"
564 .el .SS "\f(CWunknown\fP methods"
565 .IX Subsection "unknown methods"
566 .Vb 1
567 \& if ( $result\->is_unknown ) { ... }
568 .Ve
569 .PP
570 There are no unique methods for unknown results.
571 .ie n .SS """test"" methods"
572 .el .SS "\f(CWtest\fP methods"
573 .IX Subsection "test methods"
574 .Vb 1
575 \& if ( $result\->is_test ) { ... }
576 .Ve
577 .PP
578 If the above evaluates as true, the following methods will be available on the
579 \&\f(CW$result\fR object.
580 .PP
581 \fR\f(CI\*(C`ok\*(C'\fR\fI\fR
582 .IX Subsection "ok"
583 .PP
584 .Vb 1
585 \& my $ok = $result\->ok;
586 .Ve
587 .PP
588 Returns the literal text of the \f(CW\*(C`ok\*(C'\fR or \f(CW\*(C`not ok\*(C'\fR status.
589 .PP
590 \fR\f(CI\*(C`number\*(C'\fR\fI\fR
591 .IX Subsection "number"
592 .PP
593 .Vb 1
594 \& my $test_number = $result\->number;
595 .Ve
596 .PP
597 Returns the number of the test, even if the original TAP output did not supply
598 that number.
599 .PP
600 \fR\f(CI\*(C`description\*(C'\fR\fI\fR
601 .IX Subsection "description"
602 .PP
603 .Vb 1
604 \& my $description = $result\->description;
605 .Ve
606 .PP
607 Returns the description of the test, if any. This is the portion after the
608 test number but before the directive.
609 .PP
610 \fR\f(CI\*(C`directive\*(C'\fR\fI\fR
611 .IX Subsection "directive"
612 .PP
613 .Vb 1
614 \& my $directive = $result\->directive;
615 .Ve
616 .PP
617 Returns either \f(CW\*(C`TODO\*(C'\fR or \f(CW\*(C`SKIP\*(C'\fR if either directive was present for a test
618 line.
619 .PP
620 \fR\f(CI\*(C`explanation\*(C'\fR\fI\fR
621 .IX Subsection "explanation"
622 .PP
623 .Vb 1
624 \& my $explanation = $result\->explanation;
625 .Ve
626 .PP
627 If a test had either a \f(CW\*(C`TODO\*(C'\fR or \f(CW\*(C`SKIP\*(C'\fR directive, this method will return
628 the accompanying explanation, if present.
629 .PP
630 .Vb 1
631 \& not ok 17 \- \*(AqPigs can fly\*(Aq # TODO not enough acid
632 .Ve
633 .PP
634 For the above line, the explanation is \fInot enough acid\fR.
635 .PP
636 \fR\f(CI\*(C`is_ok\*(C'\fR\fI\fR
637 .IX Subsection "is_ok"
638 .PP
639 .Vb 1
640 \& if ( $result\->is_ok ) { ... }
641 .Ve
642 .PP
643 Returns a boolean value indicating whether or not the test passed. Remember
644 that for TODO tests, the test always passes.
645 .PP
646 \&\fBNote:\fR this was formerly \f(CW\*(C`passed\*(C'\fR. The latter method is deprecated and
647 will issue a warning.
648 .PP
649 \fR\f(CI\*(C`is_actual_ok\*(C'\fR\fI\fR
650 .IX Subsection "is_actual_ok"
651 .PP
652 .Vb 1
653 \& if ( $result\->is_actual_ok ) { ... }
654 .Ve
655 .PP
656 Returns a boolean value indicating whether or not the test passed, regardless
657 of its TODO status.
658 .PP
659 \&\fBNote:\fR this was formerly \f(CW\*(C`actual_passed\*(C'\fR. The latter method is deprecated
660 and will issue a warning.
661 .PP
662 \fR\f(CI\*(C`is_unplanned\*(C'\fR\fI\fR
663 .IX Subsection "is_unplanned"
664 .PP
665 .Vb 1
666 \& if ( $test\->is_unplanned ) { ... }
667 .Ve
668 .PP
669 If a test number is greater than the number of planned tests, this method will
670 return true. Unplanned tests will \fIalways\fR return false for \f(CW\*(C`is_ok\*(C'\fR,
671 regardless of whether or not the test \f(CW\*(C`has_todo\*(C'\fR (see
672 TAP::Parser::Result::Test for more information about this).
673 .PP
674 \fR\f(CI\*(C`has_skip\*(C'\fR\fI\fR
675 .IX Subsection "has_skip"
676 .PP
677 .Vb 1
678 \& if ( $result\->has_skip ) { ... }
679 .Ve
680 .PP
681 Returns a boolean value indicating whether or not this test had a SKIP
682 directive.
683 .PP
684 \fR\f(CI\*(C`has_todo\*(C'\fR\fI\fR
685 .IX Subsection "has_todo"
686 .PP
687 .Vb 1
688 \& if ( $result\->has_todo ) { ... }
689 .Ve
690 .PP
691 Returns a boolean value indicating whether or not this test had a TODO
692 directive.
693 .PP
694 Note that TODO tests \fIalways\fR pass. If you need to know whether or not
695 they really passed, check the \f(CW\*(C`is_actual_ok\*(C'\fR method.
696 .PP
697 \fR\f(CI\*(C`in_todo\*(C'\fR\fI\fR
698 .IX Subsection "in_todo"
699 .PP
700 .Vb 1
701 \& if ( $parser\->in_todo ) { ... }
702 .Ve
703 .PP
704 True while the most recent result was a TODO. Becomes true before the
705 TODO result is returned and stays true until just before the next non\-
706 TODO test is returned.
707 .SH "TOTAL RESULTS"
708 .IX Header "TOTAL RESULTS"
709 After parsing the TAP, there are many methods available to let you dig through
710 the results and determine what is meaningful to you.
711 .SS "Individual Results"
712 .IX Subsection "Individual Results"
713 These results refer to individual tests which are run.
714 .PP
715 \fR\f(CI\*(C`passed\*(C'\fR\fI\fR
716 .IX Subsection "passed"
717 .PP
718 .Vb 2
719 \& my @passed = $parser\->passed; # the test numbers which passed
720 \& my $passed = $parser\->passed; # the number of tests which passed
721 .Ve
722 .PP
723 This method lets you know which (or how many) tests passed. If a test failed
724 but had a TODO directive, it will be counted as a passed test.
725 .PP
726 \fR\f(CI\*(C`failed\*(C'\fR\fI\fR
727 .IX Subsection "failed"
728 .PP
729 .Vb 2
730 \& my @failed = $parser\->failed; # the test numbers which failed
731 \& my $failed = $parser\->failed; # the number of tests which failed
732 .Ve
733 .PP
734 This method lets you know which (or how many) tests failed. If a test passed
735 but had a TODO directive, it will \fBNOT\fR be counted as a failed test.
736 .PP
737 \fR\f(CI\*(C`actual_passed\*(C'\fR\fI\fR
738 .IX Subsection "actual_passed"
739 .PP
740 .Vb 2
741 \& # the test numbers which actually passed
742 \& my @actual_passed = $parser\->actual_passed;
743 \&
744 \& # the number of tests which actually passed
745 \& my $actual_passed = $parser\->actual_passed;
746 .Ve
747 .PP
748 This method lets you know which (or how many) tests actually passed,
749 regardless of whether or not a TODO directive was found.
750 .PP
751 \fR\f(CI\*(C`actual_ok\*(C'\fR\fI\fR
752 .IX Subsection "actual_ok"
753 .PP
754 This method is a synonym for \f(CW\*(C`actual_passed\*(C'\fR.
755 .PP
756 \fR\f(CI\*(C`actual_failed\*(C'\fR\fI\fR
757 .IX Subsection "actual_failed"
758 .PP
759 .Vb 2
760 \& # the test numbers which actually failed
761 \& my @actual_failed = $parser\->actual_failed;
762 \&
763 \& # the number of tests which actually failed
764 \& my $actual_failed = $parser\->actual_failed;
765 .Ve
766 .PP
767 This method lets you know which (or how many) tests actually failed,
768 regardless of whether or not a TODO directive was found.
769 .PP
770 \fR\f(CI\*(C`todo\*(C'\fR\fI\fR
771 .IX Subsection "todo"
772 .PP
773 .Vb 2
774 \& my @todo = $parser\->todo; # the test numbers with todo directives
775 \& my $todo = $parser\->todo; # the number of tests with todo directives
776 .Ve
777 .PP
778 This method lets you know which (or how many) tests had TODO directives.
779 .PP
780 \fR\f(CI\*(C`todo_passed\*(C'\fR\fI\fR
781 .IX Subsection "todo_passed"
782 .PP
783 .Vb 2
784 \& # the test numbers which unexpectedly succeeded
785 \& my @todo_passed = $parser\->todo_passed;
786 \&
787 \& # the number of tests which unexpectedly succeeded
788 \& my $todo_passed = $parser\->todo_passed;
789 .Ve
790 .PP
791 This method lets you know which (or how many) tests actually passed but were
792 declared as "TODO" tests.
793 .PP
794 \fR\f(CI\*(C`todo_failed\*(C'\fR\fI\fR
795 .IX Subsection "todo_failed"
796 .PP
797 .Vb 1
798 \& # deprecated in favor of \*(Aqtodo_passed\*(Aq. This method was horribly misnamed.
799 .Ve
800 .PP
801 This was a badly misnamed method. It indicates which TODO tests unexpectedly
802 succeeded. Will now issue a warning and call \f(CW\*(C`todo_passed\*(C'\fR.
803 .PP
804 \fR\f(CI\*(C`skipped\*(C'\fR\fI\fR
805 .IX Subsection "skipped"
806 .PP
807 .Vb 2
808 \& my @skipped = $parser\->skipped; # the test numbers with SKIP directives
809 \& my $skipped = $parser\->skipped; # the number of tests with SKIP directives
810 .Ve
811 .PP
812 This method lets you know which (or how many) tests had SKIP directives.
813 .SS Pragmas
814 .IX Subsection "Pragmas"
815 \fR\f(CI\*(C`pragma\*(C'\fR\fI\fR
816 .IX Subsection "pragma"
817 .PP
818 Get or set a pragma. To get the state of a pragma:
819 .PP
820 .Vb 3
821 \& if ( $p\->pragma(\*(Aqstrict\*(Aq) ) {
822 \& # be strict
823 \& }
824 .Ve
825 .PP
826 To set the state of a pragma:
827 .PP
828 .Vb 1
829 \& $p\->pragma(\*(Aqstrict\*(Aq, 1); # enable strict mode
830 .Ve
831 .PP
832 \fR\f(CI\*(C`pragmas\*(C'\fR\fI\fR
833 .IX Subsection "pragmas"
834 .PP
835 Get a list of all the currently enabled pragmas:
836 .PP
837 .Vb 1
838 \& my @pragmas_enabled = $p\->pragmas;
839 .Ve
840 .SS "Summary Results"
841 .IX Subsection "Summary Results"
842 These results are "meta" information about the total results of an individual
843 test program.
844 .PP
845 \fR\f(CI\*(C`plan\*(C'\fR\fI\fR
846 .IX Subsection "plan"
847 .PP
848 .Vb 1
849 \& my $plan = $parser\->plan;
850 .Ve
851 .PP
852 Returns the test plan, if found.
853 .PP
854 \fR\f(CI\*(C`good_plan\*(C'\fR\fI\fR
855 .IX Subsection "good_plan"
856 .PP
857 Deprecated. Use \f(CW\*(C`is_good_plan\*(C'\fR instead.
858 .PP
859 \fR\f(CI\*(C`is_good_plan\*(C'\fR\fI\fR
860 .IX Subsection "is_good_plan"
861 .PP
862 .Vb 1
863 \& if ( $parser\->is_good_plan ) { ... }
864 .Ve
865 .PP
866 Returns a boolean value indicating whether or not the number of tests planned
867 matches the number of tests run.
868 .PP
869 \&\fBNote:\fR this was formerly \f(CW\*(C`good_plan\*(C'\fR. The latter method is deprecated and
870 will issue a warning.
871 .PP
872 And since we're on that subject ...
873 .PP
874 \fR\f(CI\*(C`tests_planned\*(C'\fR\fI\fR
875 .IX Subsection "tests_planned"
876 .PP
877 .Vb 1
878 \& print $parser\->tests_planned;
879 .Ve
880 .PP
881 Returns the number of tests planned, according to the plan. For example, a
882 plan of '1..17' will mean that 17 tests were planned.
883 .PP
884 \fR\f(CI\*(C`tests_run\*(C'\fR\fI\fR
885 .IX Subsection "tests_run"
886 .PP
887 .Vb 1
888 \& print $parser\->tests_run;
889 .Ve
890 .PP
891 Returns the number of tests which actually were run. Hopefully this will
892 match the number of \f(CW\*(C`$parser\->tests_planned\*(C'\fR.
893 .PP
894 \fR\f(CI\*(C`skip_all\*(C'\fR\fI\fR
895 .IX Subsection "skip_all"
896 .PP
897 Returns a true value (actually the reason for skipping) if all tests
898 were skipped.
899 .PP
900 \fR\f(CI\*(C`start_time\*(C'\fR\fI\fR
901 .IX Subsection "start_time"
902 .PP
903 Returns the wall-clock time when the Parser was created.
904 .PP
905 \fR\f(CI\*(C`end_time\*(C'\fR\fI\fR
906 .IX Subsection "end_time"
907 .PP
908 Returns the wall-clock time when the end of TAP input was seen.
909 .PP
910 \fR\f(CI\*(C`start_times\*(C'\fR\fI\fR
911 .IX Subsection "start_times"
912 .PP
913 Returns the CPU times (like "times" in perlfunc when the Parser was created.
914 .PP
915 \fR\f(CI\*(C`end_times\*(C'\fR\fI\fR
916 .IX Subsection "end_times"
917 .PP
918 Returns the CPU times (like "times" in perlfunc when the end of TAP
919 input was seen.
920 .PP
921 \fR\f(CI\*(C`has_problems\*(C'\fR\fI\fR
922 .IX Subsection "has_problems"
923 .PP
924 .Vb 3
925 \& if ( $parser\->has_problems ) {
926 \& ...
927 \& }
928 .Ve
929 .PP
930 This is a 'catch\-all' method which returns true if any tests have currently
931 failed, any TODO tests unexpectedly succeeded, or any parse errors occurred.
932 .PP
933 \fR\f(CI\*(C`version\*(C'\fR\fI\fR
934 .IX Subsection "version"
935 .PP
936 .Vb 1
937 \& $parser\->version;
938 .Ve
939 .PP
940 Once the parser is done, this will return the version number for the
941 parsed TAP. Version numbers were introduced with TAP version 13 so if no
942 version number is found version 12 is assumed.
943 .PP
944 \fR\f(CI\*(C`exit\*(C'\fR\fI\fR
945 .IX Subsection "exit"
946 .PP
947 .Vb 1
948 \& $parser\->exit;
949 .Ve
950 .PP
951 Once the parser is done, this will return the exit status. If the parser ran
952 an executable, it returns the exit status of the executable.
953 .PP
954 \fR\f(CI\*(C`wait\*(C'\fR\fI\fR
955 .IX Subsection "wait"
956 .PP
957 .Vb 1
958 \& $parser\->wait;
959 .Ve
960 .PP
961 Once the parser is done, this will return the wait status. If the parser ran
962 an executable, it returns the wait status of the executable. Otherwise, this
963 merely returns the \f(CW\*(C`exit\*(C'\fR status.
964 .ie n .SS """ignore_exit"""
965 .el .SS \f(CWignore_exit\fP
966 .IX Subsection "ignore_exit"
967 .Vb 1
968 \& $parser\->ignore_exit(1);
969 .Ve
970 .PP
971 Tell the parser to ignore the exit status from the test when determining
972 whether the test passed. Normally tests with non-zero exit status are
973 considered to have failed even if all individual tests passed. In cases
974 where it is not possible to control the exit value of the test script
975 use this option to ignore it.
976 .PP
977 \fR\f(CI\*(C`parse_errors\*(C'\fR\fI\fR
978 .IX Subsection "parse_errors"
979 .PP
980 .Vb 2
981 \& my @errors = $parser\->parse_errors; # the parser errors
982 \& my $errors = $parser\->parse_errors; # the number of parser_errors
983 .Ve
984 .PP
985 Fortunately, all TAP output is perfect. In the event that it is not, this
986 method will return parser errors. Note that a junk line which the parser does
987 not recognize is \f(CW\*(C`not\*(C'\fR an error. This allows this parser to handle future
988 versions of TAP. The following are all TAP errors reported by the parser:
989 .IP \(bu 4
990 Misplaced plan
991 .Sp
992 The plan (for example, '1..5'), must only come at the beginning or end of the
993 TAP output.
994 .IP \(bu 4
995 No plan
996 .Sp
997 Gotta have a plan!
998 .IP \(bu 4
999 More than one plan
1000 .Sp
1001 .Vb 5
1002 \& 1..3
1003 \& ok 1 \- input file opened
1004 \& not ok 2 \- first line of the input valid # todo some data
1005 \& ok 3 read the rest of the file
1006 \& 1..3
1007 .Ve
1008 .Sp
1009 Right. Very funny. Don't do that.
1010 .IP \(bu 4
1011 Test numbers out of sequence
1012 .Sp
1013 .Vb 4
1014 \& 1..3
1015 \& ok 1 \- input file opened
1016 \& not ok 2 \- first line of the input valid # todo some data
1017 \& ok 2 read the rest of the file
1018 .Ve
1019 .Sp
1020 That last test line above should have the number '3' instead of '2'.
1021 .Sp
1022 Note that it's perfectly acceptable for some lines to have test numbers and
1023 others to not have them. However, when a test number is found, it must be in
1024 sequence. The following is also an error:
1025 .Sp
1026 .Vb 4
1027 \& 1..3
1028 \& ok 1 \- input file opened
1029 \& not ok \- first line of the input valid # todo some data
1030 \& ok 2 read the rest of the file
1031 .Ve
1032 .Sp
1033 But this is not:
1034 .Sp
1035 .Vb 4
1036 \& 1..3
1037 \& ok \- input file opened
1038 \& not ok \- first line of the input valid # todo some data
1039 \& ok 3 read the rest of the file
1040 .Ve
1041 .PP
1042 \fR\f(CI\*(C`get_select_handles\*(C'\fR\fI\fR
1043 .IX Subsection "get_select_handles"
1044 .PP
1045 Get an a list of file handles which can be passed to \f(CW\*(C`select\*(C'\fR to
1046 determine the readiness of this parser.
1047 .PP
1048 \fR\f(CI\*(C`delete_spool\*(C'\fR\fI\fR
1049 .IX Subsection "delete_spool"
1050 .PP
1051 Delete and return the spool.
1052 .PP
1053 .Vb 1
1054 \& my $fh = $parser\->delete_spool;
1055 .Ve
1056 .SH CALLBACKS
1057 .IX Header "CALLBACKS"
1058 As mentioned earlier, a "callback" key may be added to the
1059 \&\f(CW\*(C`TAP::Parser\*(C'\fR constructor. If present, each callback corresponding to a
1060 given result type will be called with the result as the argument if the
1061 \&\f(CW\*(C`run\*(C'\fR method is used. The callback is expected to be a subroutine
1062 reference (or anonymous subroutine) which is invoked with the parser
1063 result as its argument.
1064 .PP
1065 .Vb 7
1066 \& my %callbacks = (
1067 \& test => \e&test_callback,
1068 \& plan => \e&plan_callback,
1069 \& comment => \e&comment_callback,
1070 \& bailout => \e&bailout_callback,
1071 \& unknown => \e&unknown_callback,
1072 \& );
1073 \&
1074 \& my $aggregator = TAP::Parser::Aggregator\->new;
1075 \& for my $file ( @test_files ) {
1076 \& my $parser = TAP::Parser\->new(
1077 \& {
1078 \& source => $file,
1079 \& callbacks => \e%callbacks,
1080 \& }
1081 \& );
1082 \& $parser\->run;
1083 \& $aggregator\->add( $file, $parser );
1084 \& }
1085 .Ve
1086 .PP
1087 Callbacks may also be added like this:
1088 .PP
1089 .Vb 2
1090 \& $parser\->callback( test => \e&test_callback );
1091 \& $parser\->callback( plan => \e&plan_callback );
1092 .Ve
1093 .PP
1094 The following keys allowed for callbacks. These keys are case-sensitive.
1095 .IP \(bu 4
1096 \&\f(CW\*(C`test\*(C'\fR
1097 .Sp
1098 Invoked if \f(CW\*(C`$result\->is_test\*(C'\fR returns true.
1099 .IP \(bu 4
1100 \&\f(CW\*(C`version\*(C'\fR
1101 .Sp
1102 Invoked if \f(CW\*(C`$result\->is_version\*(C'\fR returns true.
1103 .IP \(bu 4
1104 \&\f(CW\*(C`plan\*(C'\fR
1105 .Sp
1106 Invoked if \f(CW\*(C`$result\->is_plan\*(C'\fR returns true.
1107 .IP \(bu 4
1108 \&\f(CW\*(C`comment\*(C'\fR
1109 .Sp
1110 Invoked if \f(CW\*(C`$result\->is_comment\*(C'\fR returns true.
1111 .IP \(bu 4
1112 \&\f(CW\*(C`bailout\*(C'\fR
1113 .Sp
1114 Invoked if \f(CW\*(C`$result\->is_unknown\*(C'\fR returns true.
1115 .IP \(bu 4
1116 \&\f(CW\*(C`yaml\*(C'\fR
1117 .Sp
1118 Invoked if \f(CW\*(C`$result\->is_yaml\*(C'\fR returns true.
1119 .IP \(bu 4
1120 \&\f(CW\*(C`unknown\*(C'\fR
1121 .Sp
1122 Invoked if \f(CW\*(C`$result\->is_unknown\*(C'\fR returns true.
1123 .IP \(bu 4
1124 \&\f(CW\*(C`ELSE\*(C'\fR
1125 .Sp
1126 If a result does not have a callback defined for it, this callback will
1127 be invoked. Thus, if all of the previous result types are specified as
1128 callbacks, this callback will \fInever\fR be invoked.
1129 .IP \(bu 4
1130 \&\f(CW\*(C`ALL\*(C'\fR
1131 .Sp
1132 This callback will always be invoked and this will happen for each
1133 result after one of the above callbacks is invoked. For example, if
1134 Term::ANSIColor is loaded, you could use the following to color your
1135 test output:
1136 .Sp
1137 .Vb 12
1138 \& my %callbacks = (
1139 \& test => sub {
1140 \& my $test = shift;
1141 \& if ( $test\->is_ok && not $test\->directive ) {
1142 \& # normal passing test
1143 \& print color \*(Aqgreen\*(Aq;
1144 \& }
1145 \& elsif ( !$test\->is_ok ) { # even if it\*(Aqs TODO
1146 \& print color \*(Aqwhite on_red\*(Aq;
1147 \& }
1148 \& elsif ( $test\->has_skip ) {
1149 \& print color \*(Aqwhite on_blue\*(Aq;
1150 \&
1151 \& }
1152 \& elsif ( $test\->has_todo ) {
1153 \& print color \*(Aqwhite\*(Aq;
1154 \& }
1155 \& },
1156 \& ELSE => sub {
1157 \& # plan, comment, and so on (anything which isn\*(Aqt a test line)
1158 \& print color \*(Aqblack on_white\*(Aq;
1159 \& },
1160 \& ALL => sub {
1161 \& # now print them
1162 \& print shift\->as_string;
1163 \& print color \*(Aqreset\*(Aq;
1164 \& print "\en";
1165 \& },
1166 \& );
1167 .Ve
1168 .IP \(bu 4
1169 \&\f(CW\*(C`EOF\*(C'\fR
1170 .Sp
1171 Invoked when there are no more lines to be parsed. Since there is no
1172 accompanying TAP::Parser::Result object the \f(CW\*(C`TAP::Parser\*(C'\fR object is
1173 passed instead.
1174 .SH "TAP GRAMMAR"
1175 .IX Header "TAP GRAMMAR"
1176 If you're looking for an EBNF grammar, see TAP::Parser::Grammar.
1177 .SH "BACKWARDS COMPATIBILITY"
1178 .IX Header "BACKWARDS COMPATIBILITY"
1179 The Perl-QA list attempted to ensure backwards compatibility with
1180 Test::Harness. However, there are some minor differences.
1181 .SS Differences
1182 .IX Subsection "Differences"
1183 .IP \(bu 4
1184 TODO plans
1185 .Sp
1186 A little-known feature of Test::Harness is that it supported TODO
1187 lists in the plan:
1188 .Sp
1189 .Vb 3
1190 \& 1..2 todo 2
1191 \& ok 1 \- We have liftoff
1192 \& not ok 2 \- Anti\-gravity device activated
1193 .Ve
1194 .Sp
1195 Under Test::Harness, test number 2 would \fIpass\fR because it was
1196 listed as a TODO test on the plan line. However, we are not aware of
1197 anyone actually using this feature and hard-coding test numbers is
1198 discouraged because it's very easy to add a test and break the test
1199 number sequence. This makes test suites very fragile. Instead, the
1200 following should be used:
1201 .Sp
1202 .Vb 3
1203 \& 1..2
1204 \& ok 1 \- We have liftoff
1205 \& not ok 2 \- Anti\-gravity device activated # TODO
1206 .Ve
1207 .IP \(bu 4
1208 \&'Missing' tests
1209 .Sp
1210 It rarely happens, but sometimes a harness might encounter
1211 \&'missing tests:
1212 .Sp
1213 .Vb 5
1214 \& ok 1
1215 \& ok 2
1216 \& ok 15
1217 \& ok 16
1218 \& ok 17
1219 .Ve
1220 .Sp
1221 Test::Harness would report tests 3\-14 as having failed. For the
1222 \&\f(CW\*(C`TAP::Parser\*(C'\fR, these tests are not considered failed because they've
1223 never run. They're reported as parse failures (tests out of sequence).
1224 .SH SUBCLASSING
1225 .IX Header "SUBCLASSING"
1226 If you find you need to provide custom functionality (as you would have using
1227 Test::Harness::Straps), you're in luck: \f(CW\*(C`TAP::Parser\*(C'\fR and friends are
1228 designed to be easily plugged-into and/or subclassed.
1229 .PP
1230 Before you start, it's important to know a few things:
1231 .IP 1. 2
1232 All \f(CW\*(C`TAP::*\*(C'\fR objects inherit from TAP::Object.
1233 .IP 2. 2
1234 Many \f(CW\*(C`TAP::*\*(C'\fR classes have a \fISUBCLASSING\fR section to guide you.
1235 .IP 3. 2
1236 Note that \f(CW\*(C`TAP::Parser\*(C'\fR is designed to be the central "maker" \- ie: it is
1237 responsible for creating most new objects in the \f(CW\*(C`TAP::Parser::*\*(C'\fR namespace.
1238 .Sp
1239 This makes it possible for you to have a single point of configuring what
1240 subclasses should be used, which means that in many cases you'll find
1241 you only need to sub-class one of the parser's components.
1242 .Sp
1243 The exception to this rule are \fISourceHandlers\fR & \fIIterators\fR, but those are
1244 both created with customizable \fIIteratorFactory\fR.
1245 .IP 4. 2
1246 By subclassing, you may end up overriding undocumented methods. That's not
1247 a bad thing per se, but be forewarned that undocumented methods may change
1248 without warning from one release to the next \- we cannot guarantee backwards
1249 compatibility. If any \fIdocumented\fR method needs changing, it will be
1250 deprecated first, and changed in a later release.
1251 .SS "Parser Components"
1252 .IX Subsection "Parser Components"
1253 \fISources\fR
1254 .IX Subsection "Sources"
1255 .PP
1256 A TAP parser consumes input from a single \fIraw source\fR of TAP, which could come
1257 from anywhere (a file, an executable, a database, an IO handle, a URI, etc..).
1258 The source gets bundled up in a TAP::Parser::Source object which gathers some
1259 meta data about it. The parser then uses a TAP::Parser::IteratorFactory to
1260 determine which TAP::Parser::SourceHandler to use to turn the raw source
1261 into a stream of TAP by way of "Iterators".
1262 .PP
1263 If you simply want \f(CW\*(C`TAP::Parser\*(C'\fR to handle a new source of TAP you probably
1264 don't need to subclass \f(CW\*(C`TAP::Parser\*(C'\fR itself. Rather, you'll need to create a
1265 new TAP::Parser::SourceHandler class, and just plug it into the parser using
1266 the \fIsources\fR param to "new". Before you start writing one, read through
1267 TAP::Parser::IteratorFactory to get a feel for how the system works first.
1268 .PP
1269 If you find you really need to use your own iterator factory you can still do
1270 so without sub-classing \f(CW\*(C`TAP::Parser\*(C'\fR by setting "iterator_factory_class".
1271 .PP
1272 If you just need to customize the objects on creation, subclass TAP::Parser
1273 and override "make_iterator_factory".
1274 .PP
1275 Note that \f(CW\*(C`make_source\*(C'\fR & \f(CW\*(C`make_perl_source\*(C'\fR have been \fIDEPRECATED\fR and
1276 are now removed.
1277 .PP
1278 \fIIterators\fR
1279 .IX Subsection "Iterators"
1280 .PP
1281 A TAP parser uses \fIiterators\fR to loop through the \fIstream\fR of TAP read in
1282 from the \fIsource\fR it was given. There are a few types of Iterators available
1283 by default, all sub-classes of TAP::Parser::Iterator. Choosing which
1284 iterator to use is the responsibility of the \fIiterator factory\fR, though it
1285 simply delegates to the \fISource Handler\fR it uses.
1286 .PP
1287 If you're writing your own TAP::Parser::SourceHandler, you may need to
1288 create your own iterators too. If so you'll need to subclass
1289 TAP::Parser::Iterator.
1290 .PP
1291 Note that "make_iterator" has been \fIDEPRECATED\fR and is now removed.
1292 .PP
1293 \fIResults\fR
1294 .IX Subsection "Results"
1295 .PP
1296 A TAP parser creates TAP::Parser::Results as it iterates through the
1297 input \fIstream\fR. There are quite a few result types available; choosing
1298 which class to use is the responsibility of the \fIresult factory\fR.
1299 .PP
1300 To create your own result types you have two options:
1301 .IP "option 1" 2
1302 .IX Item "option 1"
1303 Subclass TAP::Parser::Result and register your new result type/class with
1304 the default TAP::Parser::ResultFactory.
1305 .IP "option 2" 2
1306 .IX Item "option 2"
1307 Subclass TAP::Parser::ResultFactory itself and implement your own
1308 TAP::Parser::Result creation logic. Then you'll need to customize the
1309 class used by your parser by setting the \f(CW\*(C`result_factory_class\*(C'\fR parameter.
1310 See "new" for more details.
1311 .PP
1312 If you need to customize the objects on creation, subclass TAP::Parser and
1313 override "make_result".
1314 .PP
1315 \fIGrammar\fR
1316 .IX Subsection "Grammar"
1317 .PP
1318 TAP::Parser::Grammar is the heart of the parser. It tokenizes the TAP
1319 input \fIstream\fR and produces results. If you need to customize its behaviour
1320 you should probably familiarize yourself with the source first. Enough
1321 lecturing.
1322 .PP
1323 Subclass TAP::Parser::Grammar and customize your parser by setting the
1324 \&\f(CW\*(C`grammar_class\*(C'\fR parameter. See "new" for more details.
1325 .PP
1326 If you need to customize the objects on creation, subclass TAP::Parser and
1327 override "make_grammar"
1328 .SH ACKNOWLEDGMENTS
1329 .IX Header "ACKNOWLEDGMENTS"
1330 All of the following have helped. Bug reports, patches, (im)moral
1331 support, or just words of encouragement have all been forthcoming.
1332 .IP \(bu 4
1333 Michael Schwern
1334 .IP \(bu 4
1335 Andy Lester
1336 .IP \(bu 4
1337 chromatic
1338 .IP \(bu 4
1339 GEOFFR
1340 .IP \(bu 4
1341 Shlomi Fish
1342 .IP \(bu 4
1343 Torsten Schoenfeld
1344 .IP \(bu 4
1345 Jerry Gay
1346 .IP \(bu 4
1347 Aristotle
1348 .IP \(bu 4
1349 Adam Kennedy
1350 .IP \(bu 4
1351 Yves Orton
1352 .IP \(bu 4
1353 Adrian Howard
1354 .IP \(bu 4
1355 Sean & Lil
1356 .IP \(bu 4
1357 Andreas J. Koenig
1358 .IP \(bu 4
1359 Florian Ragwitz
1360 .IP \(bu 4
1361 Corion
1362 .IP \(bu 4
1363 Mark Stosberg
1364 .IP \(bu 4
1365 Matt Kraai
1366 .IP \(bu 4
1367 David Wheeler
1368 .IP \(bu 4
1369 Alex Vandiver
1370 .IP \(bu 4
1371 Cosimo Streppone
1372 .IP \(bu 4
1373 Ville Skyttä
1374 .SH AUTHORS
1375 .IX Header "AUTHORS"
1376 Curtis "Ovid" Poe <[email protected]>
1377 .PP
1378 Andy Armstong <[email protected]>
1379 .PP
1380 Eric Wilhelm @ <ewilhelm at cpan dot org>
1381 .PP
1382 Michael Peters <mpeters at plusthree dot com>
1383 .PP
1384 Leif Eriksen <leif dot eriksen at bigpond dot com>
1385 .PP
1386 Steve Purkis <[email protected]>
1387 .PP
1388 Nicholas Clark <[email protected]>
1389 .PP
1390 Lee Johnson <notfadeaway at btinternet dot com>
1391 .PP
1392 Philippe Bruhat <[email protected]>
1393 .SH BUGS
1394 .IX Header "BUGS"
1395 Please report any bugs or feature requests to
1396 \&\f(CW\*(C`bug\-test\[email protected]\*(C'\fR, or through the web interface at
1397 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test\-Harness>.
1398 We will be notified, and then you'll automatically be notified of
1399 progress on your bug as we make changes.
1400 .PP
1401 Obviously, bugs which include patches are best. If you prefer, you can
1402 patch against bleed by via anonymous checkout of the latest version:
1403 .PP
1404 .Vb 1
1405 \& git clone git://github.com/Perl\-Toolchain\-Gang/Test\-Harness.git
1406 .Ve
1407 .SH "COPYRIGHT & LICENSE"
1408 .IX Header "COPYRIGHT & LICENSE"
1409 Copyright 2006\-2008 Curtis "Ovid" Poe, all rights reserved.
1410 .PP
1411 This program is free software; you can redistribute it and/or modify it
1412 under the same terms as Perl itself.