Debian Codegraph @

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