1TAP::Parser(3) User Contributed Perl Documentation TAP::Parser(3)
2
6 TAP::Parser - Parse TAP output
7
9 Version 3.44
10
12 use TAP::Parser;
13 my $parser = TAP::Parser->new( { source => $source } );
15 while ( my $result = $parser->next ) {
17 print $result->as_string;
18 }
19
21 "TAP::Parser" is designed to produce a proper parse of TAP output. For
22 an example of how to run tests through this module, see the simple
23 harnesses "examples/".
24 There's a wiki dedicated to the Test Anything Protocol:
26 <http://testanything.org>
28 It includes the TAP::Parser Cookbook:
30 <http://testanything.org/testing-with-tap/perl/tap::parser-cookbook.html>
32
34 Class Methods
35 "new"
36 my $parser = TAP::Parser->new(\%args);
38 Returns a new "TAP::Parser" object.
40 The arguments should be a hashref with one of the following keys:
42 • "source"
44 CHANGED in 3.18
46 This is the preferred method of passing input to the constructor.
48 The "source" is used to create a TAP::Parser::Source that is passed
50 to the "iterator_factory_class" which in turn figures out how to
51 handle the source and creates a <TAP::Parser::Iterator> for it.
52 The iterator is used by the parser to read in the TAP stream.
53 To configure the IteratorFactory use the "sources" parameter below.
55 Note that "source", "tap" and "exec" are mutually exclusive.
57 • "tap"
59 CHANGED in 3.18
61 The value should be the complete TAP output.
63 The tap is used to create a TAP::Parser::Source that is passed to
65 the "iterator_factory_class" which in turn figures out how to
66 handle the source and creates a <TAP::Parser::Iterator> for it.
67 The iterator is used by the parser to read in the TAP stream.
68 To configure the IteratorFactory use the "sources" parameter below.
70 Note that "source", "tap" and "exec" are mutually exclusive.
72 • "exec"
74 Must be passed an array reference.
76 The exec array ref is used to create a TAP::Parser::Source that is
78 passed to the "iterator_factory_class" which in turn figures out
79 how to handle the source and creates a <TAP::Parser::Iterator> for
80 it. The iterator is used by the parser to read in the TAP stream.
81 By default the TAP::Parser::SourceHandler::Executable class will
83 create a TAP::Parser::Iterator::Process object to handle the
84 source. This passes the array reference strings as command
85 arguments to IPC::Open3::open3:
86 exec => [ '/usr/bin/ruby', 't/my_test.rb' ]
88 If any "test_args" are given they will be appended to the end of
90 the command argument list.
91 To configure the IteratorFactory use the "sources" parameter below.
93 Note that "source", "tap" and "exec" are mutually exclusive.
95 The following keys are optional.
97 • "sources"
99 NEW to 3.18.
101 If set, "sources" must be a hashref containing the names of the
103 TAP::Parser::SourceHandlers to load and/or configure. The values
104 are a hash of configuration that will be accessible to the source
105 handlers via "config_for" in TAP::Parser::Source.
106 For example:
108 sources => {
110 Perl => { exec => '/path/to/custom/perl' },
111 File => { extensions => [ '.tap', '.txt' ] },
112 MyCustom => { some => 'config' },
113 }
114 This will cause "TAP::Parser" to pass custom configuration to two
116 of the built- in source handlers -
117 TAP::Parser::SourceHandler::Perl, TAP::Parser::SourceHandler::File
118 - and attempt to load the "MyCustom" class. See "load_handlers" in
119 TAP::Parser::IteratorFactory for more detail.
120 The "sources" parameter affects how "source", "tap" and "exec"
122 parameters are handled.
123 See TAP::Parser::IteratorFactory, TAP::Parser::SourceHandler and
125 subclasses for more details.
126 • "callback"
128 If present, each callback corresponding to a given result type will
130 be called with the result as the argument if the "run" method is
131 used:
132 my %callbacks = (
134 test => \&test_callback,
135 plan => \&plan_callback,
136 comment => \&comment_callback,
137 bailout => \&bailout_callback,
138 unknown => \&unknown_callback,
139 );
140 my $aggregator = TAP::Parser::Aggregator->new;
142 for my $file ( @test_files ) {
143 my $parser = TAP::Parser->new(
144 {
145 source => $file,
146 callbacks => \%callbacks,
147 }
148 );
149 $parser->run;
150 $aggregator->add( $file, $parser );
151 }
152 • "switches"
154 If using a Perl file as a source, optional switches may be passed
156 which will be used when invoking the perl executable.
157 my $parser = TAP::Parser->new( {
159 source => $test_file,
160 switches => [ '-Ilib' ],
161 } );
162 • "test_args"
164 Used in conjunction with the "source" and "exec" option to supply a
166 reference to an @ARGV style array of arguments to pass to the test
167 program.
168 • "spool"
170 If passed a filehandle will write a copy of all parsed TAP to that
172 handle.
173 • "merge"
175 If false, STDERR is not captured (though it is 'relayed' to keep it
177 somewhat synchronized with STDOUT.)
178 If true, STDERR and STDOUT are the same filehandle. This may cause
180 breakage if STDERR contains anything resembling TAP format, but
181 does allow exact synchronization.
182 Subtleties of this behavior may be platform-dependent and may
184 change in the future.
185 • "grammar_class"
187 This option was introduced to let you easily customize which
189 grammar class the parser should use. It defaults to
190 TAP::Parser::Grammar.
191 See also "make_grammar".
193 • "result_factory_class"
195 This option was introduced to let you easily customize which result
197 factory class the parser should use. It defaults to
198 TAP::Parser::ResultFactory.
199 See also "make_result".
201 • "iterator_factory_class"
203 CHANGED in 3.18
205 This option was introduced to let you easily customize which
207 iterator factory class the parser should use. It defaults to
208 TAP::Parser::IteratorFactory.
209 Instance Methods
211 "next"
212 my $parser = TAP::Parser->new( { source => $file } );
214 while ( my $result = $parser->next ) {
215 print $result->as_string, "\n";
216 }
217 This method returns the results of the parsing, one result at a time.
219 Note that it is destructive. You can't rewind and examine previous
220 results.
221 If callbacks are used, they will be issued before this call returns.
223 Each result returned is a subclass of TAP::Parser::Result. See that
225 module and related classes for more information on how to use them.
226 "run"
228 $parser->run;
230 This method merely runs the parser and parses all of the TAP.
232 "make_grammar"
234 Make a new TAP::Parser::Grammar object and return it. Passes through
236 any arguments given.
237 The "grammar_class" can be customized, as described in "new".
239 "make_result"
241 Make a new TAP::Parser::Result object using the parser's
243 TAP::Parser::ResultFactory, and return it. Passes through any
244 arguments given.
245 The "result_factory_class" can be customized, as described in "new".
247 "make_iterator_factory"
249 NEW to 3.18.
251 Make a new TAP::Parser::IteratorFactory object and return it. Passes
253 through any arguments given.
254 "iterator_factory_class" can be customized, as described in "new".
256
258 If you've read this far in the docs, you've seen this:
259 while ( my $result = $parser->next ) {
261 print $result->as_string;
262 }
263 Each result returned is a TAP::Parser::Result subclass, referred to as
265 result types.
266 Result types
268 Basically, you fetch individual results from the TAP. The six types,
269 with examples of each, are as follows:
270 • Version
272 TAP version 12
274 • Plan
276 1..42
278 • Pragma
280 pragma +strict
282 • Test
284 ok 3 - We should start with some foobar!
286 • Comment
288 # Hope we don't use up the foobar.
290 • Bailout
292 Bail out! We ran out of foobar!
294 • Unknown
296 ... yo, this ain't TAP! ...
298 Each result fetched is a result object of a different type. There are
300 common methods to each result object and different types may have
301 methods unique to their type. Sometimes a type method may be
302 overridden in a subclass, but its use is guaranteed to be identical.
303 Common type methods
305 "type"
306 Returns the type of result, such as "comment" or "test".
308 "as_string"
310 Prints a string representation of the token. This might not be the
312 exact output, however. Tests will have test numbers added if not
313 present, TODO and SKIP directives will be capitalized and, in general,
314 things will be cleaned up. If you need the original text for the
315 token, see the "raw" method.
316 "raw"
318 Returns the original line of text which was parsed.
320 "is_plan"
322 Indicates whether or not this is the test plan line.
324 "is_test"
326 Indicates whether or not this is a test line.
328 "is_comment"
330 Indicates whether or not this is a comment. Comments will generally
332 only appear in the TAP stream if STDERR is merged to STDOUT. See the
333 "merge" option.
334 "is_bailout"
336 Indicates whether or not this is bailout line.
338 "is_yaml"
340 Indicates whether or not the current item is a YAML block.
342 "is_unknown"
344 Indicates whether or not the current line could be parsed.
346 "is_ok"
348 if ( $result->is_ok ) { ... }
350 Reports whether or not a given result has passed. Anything which is
352 not a test result returns true. This is merely provided as a
353 convenient shortcut which allows you to do this:
354 my $parser = TAP::Parser->new( { source => $source } );
356 while ( my $result = $parser->next ) {
357 # only print failing results
358 print $result->as_string unless $result->is_ok;
359 }
360 "plan" methods
362 if ( $result->is_plan ) { ... }
363 If the above evaluates as true, the following methods will be available
365 on the $result object.
366 "plan"
368 if ( $result->is_plan ) {
370 print $result->plan;
371 }
372 This is merely a synonym for "as_string".
374 "directive"
376 my $directive = $result->directive;
378 If a SKIP directive is included with the plan, this method will return
380 it.
381 1..0 # SKIP: why bother?
383 "explanation"
385 my $explanation = $result->explanation;
387 If a SKIP directive was included with the plan, this method will return
389 the explanation, if any.
390 "pragma" methods
392 if ( $result->is_pragma ) { ... }
393 If the above evaluates as true, the following methods will be available
395 on the $result object.
396 "pragmas"
398 Returns a list of pragmas each of which is a + or - followed by the
400 pragma name.
401 "comment" methods
403 if ( $result->is_comment ) { ... }
404 If the above evaluates as true, the following methods will be available
406 on the $result object.
407 "comment"
409 if ( $result->is_comment ) {
411 my $comment = $result->comment;
412 print "I have something to say: $comment";
413 }
414 "bailout" methods
416 if ( $result->is_bailout ) { ... }
417 If the above evaluates as true, the following methods will be available
419 on the $result object.
420 "explanation"
422 if ( $result->is_bailout ) {
424 my $explanation = $result->explanation;
425 print "We bailed out because ($explanation)";
426 }
427 If, and only if, a token is a bailout token, you can get an
429 "explanation" via this method. The explanation is the text after the
430 mystical "Bail out!" words which appear in the tap output.
431 "unknown" methods
433 if ( $result->is_unknown ) { ... }
434 There are no unique methods for unknown results.
436 "test" methods
438 if ( $result->is_test ) { ... }
439 If the above evaluates as true, the following methods will be available
441 on the $result object.
442 "ok"
444 my $ok = $result->ok;
446 Returns the literal text of the "ok" or "not ok" status.
448 "number"
450 my $test_number = $result->number;
452 Returns the number of the test, even if the original TAP output did not
454 supply that number.
455 "description"
457 my $description = $result->description;
459 Returns the description of the test, if any. This is the portion after
461 the test number but before the directive.
462 "directive"
464 my $directive = $result->directive;
466 Returns either "TODO" or "SKIP" if either directive was present for a
468 test line.
469 "explanation"
471 my $explanation = $result->explanation;
473 If a test had either a "TODO" or "SKIP" directive, this method will
475 return the accompanying explanation, if present.
476 not ok 17 - 'Pigs can fly' # TODO not enough acid
478 For the above line, the explanation is not enough acid.
480 "is_ok"
482 if ( $result->is_ok ) { ... }
484 Returns a boolean value indicating whether or not the test passed.
486 Remember that for TODO tests, the test always passes.
487 Note: this was formerly "passed". The latter method is deprecated and
489 will issue a warning.
490 "is_actual_ok"
492 if ( $result->is_actual_ok ) { ... }
494 Returns a boolean value indicating whether or not the test passed,
496 regardless of its TODO status.
497 Note: this was formerly "actual_passed". The latter method is
499 deprecated and will issue a warning.
500 "is_unplanned"
502 if ( $test->is_unplanned ) { ... }
504 If a test number is greater than the number of planned tests, this
506 method will return true. Unplanned tests will always return false for
507 "is_ok", regardless of whether or not the test "has_todo" (see
508 TAP::Parser::Result::Test for more information about this).
509 "has_skip"
511 if ( $result->has_skip ) { ... }
513 Returns a boolean value indicating whether or not this test had a SKIP
515 directive.
516 "has_todo"
518 if ( $result->has_todo ) { ... }
520 Returns a boolean value indicating whether or not this test had a TODO
522 directive.
523 Note that TODO tests always pass. If you need to know whether or not
525 they really passed, check the "is_actual_ok" method.
526 "in_todo"
528 if ( $parser->in_todo ) { ... }
530 True while the most recent result was a TODO. Becomes true before the
532 TODO result is returned and stays true until just before the next non-
533 TODO test is returned.
534
536 After parsing the TAP, there are many methods available to let you dig
537 through the results and determine what is meaningful to you.
538 Individual Results
540 These results refer to individual tests which are run.
541 "passed"
543 my @passed = $parser->passed; # the test numbers which passed
545 my $passed = $parser->passed; # the number of tests which passed
546 This method lets you know which (or how many) tests passed. If a test
548 failed but had a TODO directive, it will be counted as a passed test.
549 "failed"
551 my @failed = $parser->failed; # the test numbers which failed
553 my $failed = $parser->failed; # the number of tests which failed
554 This method lets you know which (or how many) tests failed. If a test
556 passed but had a TODO directive, it will NOT be counted as a failed
557 test.
558 "actual_passed"
560 # the test numbers which actually passed
562 my @actual_passed = $parser->actual_passed;
563 # the number of tests which actually passed
565 my $actual_passed = $parser->actual_passed;
566 This method lets you know which (or how many) tests actually passed,
568 regardless of whether or not a TODO directive was found.
569 "actual_ok"
571 This method is a synonym for "actual_passed".
573 "actual_failed"
575 # the test numbers which actually failed
577 my @actual_failed = $parser->actual_failed;
578 # the number of tests which actually failed
580 my $actual_failed = $parser->actual_failed;
581 This method lets you know which (or how many) tests actually failed,
583 regardless of whether or not a TODO directive was found.
584 "todo"
586 my @todo = $parser->todo; # the test numbers with todo directives
588 my $todo = $parser->todo; # the number of tests with todo directives
589 This method lets you know which (or how many) tests had TODO
591 directives.
592 "todo_passed"
594 # the test numbers which unexpectedly succeeded
596 my @todo_passed = $parser->todo_passed;
597 # the number of tests which unexpectedly succeeded
599 my $todo_passed = $parser->todo_passed;
600 This method lets you know which (or how many) tests actually passed but
602 were declared as "TODO" tests.
603 "todo_failed"
605 # deprecated in favor of 'todo_passed'. This method was horribly misnamed.
607 This was a badly misnamed method. It indicates which TODO tests
609 unexpectedly succeeded. Will now issue a warning and call
610 "todo_passed".
611 "skipped"
613 my @skipped = $parser->skipped; # the test numbers with SKIP directives
615 my $skipped = $parser->skipped; # the number of tests with SKIP directives
616 This method lets you know which (or how many) tests had SKIP
618 directives.
619 Pragmas
621 "pragma"
622 Get or set a pragma. To get the state of a pragma:
624 if ( $p->pragma('strict') ) {
626 # be strict
627 }
628 To set the state of a pragma:
630 $p->pragma('strict', 1); # enable strict mode
632 "pragmas"
634 Get a list of all the currently enabled pragmas:
636 my @pragmas_enabled = $p->pragmas;
638 Summary Results
640 These results are "meta" information about the total results of an
641 individual test program.
642 "plan"
644 my $plan = $parser->plan;
646 Returns the test plan, if found.
648 "good_plan"
650 Deprecated. Use "is_good_plan" instead.
652 "is_good_plan"
654 if ( $parser->is_good_plan ) { ... }
656 Returns a boolean value indicating whether or not the number of tests
658 planned matches the number of tests run.
659 Note: this was formerly "good_plan". The latter method is deprecated
661 and will issue a warning.
662 And since we're on that subject ...
664 "tests_planned"
666 print $parser->tests_planned;
668 Returns the number of tests planned, according to the plan. For
670 example, a plan of '1..17' will mean that 17 tests were planned.
671 "tests_run"
673 print $parser->tests_run;
675 Returns the number of tests which actually were run. Hopefully this
677 will match the number of "$parser->tests_planned".
678 "skip_all"
680 Returns a true value (actually the reason for skipping) if all tests
682 were skipped.
683 "start_time"
685 Returns the wall-clock time when the Parser was created.
687 "end_time"
689 Returns the wall-clock time when the end of TAP input was seen.
691 "start_times"
693 Returns the CPU times (like "times" in perlfunc when the Parser was
695 created.
696 "end_times"
698 Returns the CPU times (like "times" in perlfunc when the end of TAP
700 input was seen.
701 "has_problems"
703 if ( $parser->has_problems ) {
705 ...
706 }
707 This is a 'catch-all' method which returns true if any tests have
709 currently failed, any TODO tests unexpectedly succeeded, or any parse
710 errors occurred.
711 "version"
713 $parser->version;
715 Once the parser is done, this will return the version number for the
717 parsed TAP. Version numbers were introduced with TAP version 13 so if
718 no version number is found version 12 is assumed.
719 "exit"
721 $parser->exit;
723 Once the parser is done, this will return the exit status. If the
725 parser ran an executable, it returns the exit status of the executable.
726 "wait"
728 $parser->wait;
730 Once the parser is done, this will return the wait status. If the
732 parser ran an executable, it returns the wait status of the executable.
733 Otherwise, this merely returns the "exit" status.
734 "ignore_exit"
736 $parser->ignore_exit(1);
737 Tell the parser to ignore the exit status from the test when
739 determining whether the test passed. Normally tests with non-zero exit
740 status are considered to have failed even if all individual tests
741 passed. In cases where it is not possible to control the exit value of
742 the test script use this option to ignore it.
743 "parse_errors"
745 my @errors = $parser->parse_errors; # the parser errors
747 my $errors = $parser->parse_errors; # the number of parser_errors
748 Fortunately, all TAP output is perfect. In the event that it is not,
750 this method will return parser errors. Note that a junk line which the
751 parser does not recognize is "not" an error. This allows this parser
752 to handle future versions of TAP. The following are all TAP errors
753 reported by the parser:
754 • Misplaced plan
756 The plan (for example, '1..5'), must only come at the beginning or
758 end of the TAP output.
759 • No plan
761 Gotta have a plan!
763 • More than one plan
765 1..3
767 ok 1 - input file opened
768 not ok 2 - first line of the input valid # todo some data
769 ok 3 read the rest of the file
770 1..3
771 Right. Very funny. Don't do that.
773 • Test numbers out of sequence
775 1..3
777 ok 1 - input file opened
778 not ok 2 - first line of the input valid # todo some data
779 ok 2 read the rest of the file
780 That last test line above should have the number '3' instead of
782 '2'.
783 Note that it's perfectly acceptable for some lines to have test
785 numbers and others to not have them. However, when a test number
786 is found, it must be in sequence. The following is also an error:
787 1..3
789 ok 1 - input file opened
790 not ok - first line of the input valid # todo some data
791 ok 2 read the rest of the file
792 But this is not:
794 1..3
796 ok - input file opened
797 not ok - first line of the input valid # todo some data
798 ok 3 read the rest of the file
799 "get_select_handles"
801 Get an a list of file handles which can be passed to "select" to
803 determine the readiness of this parser.
804 "delete_spool"
806 Delete and return the spool.
808 my $fh = $parser->delete_spool;
810
812 As mentioned earlier, a "callback" key may be added to the
813 "TAP::Parser" constructor. If present, each callback corresponding to a
814 given result type will be called with the result as the argument if the
815 "run" method is used. The callback is expected to be a subroutine
816 reference (or anonymous subroutine) which is invoked with the parser
817 result as its argument.
818 my %callbacks = (
820 test => \&test_callback,
821 plan => \&plan_callback,
822 comment => \&comment_callback,
823 bailout => \&bailout_callback,
824 unknown => \&unknown_callback,
825 );
826 my $aggregator = TAP::Parser::Aggregator->new;
828 for my $file ( @test_files ) {
829 my $parser = TAP::Parser->new(
830 {
831 source => $file,
832 callbacks => \%callbacks,
833 }
834 );
835 $parser->run;
836 $aggregator->add( $file, $parser );
837 }
838 Callbacks may also be added like this:
840 $parser->callback( test => \&test_callback );
842 $parser->callback( plan => \&plan_callback );
843 The following keys allowed for callbacks. These keys are case-
845 sensitive.
846 • "test"
848 Invoked if "$result->is_test" returns true.
850 • "version"
852 Invoked if "$result->is_version" returns true.
854 • "plan"
856 Invoked if "$result->is_plan" returns true.
858 • "comment"
860 Invoked if "$result->is_comment" returns true.
862 • "bailout"
864 Invoked if "$result->is_unknown" returns true.
866 • "yaml"
868 Invoked if "$result->is_yaml" returns true.
870 • "unknown"
872 Invoked if "$result->is_unknown" returns true.
874 • "ELSE"
876 If a result does not have a callback defined for it, this callback
878 will be invoked. Thus, if all of the previous result types are
879 specified as callbacks, this callback will never be invoked.
880 • "ALL"
882 This callback will always be invoked and this will happen for each
884 result after one of the above callbacks is invoked. For example,
885 if Term::ANSIColor is loaded, you could use the following to color
886 your test output:
887 my %callbacks = (
889 test => sub {
890 my $test = shift;
891 if ( $test->is_ok && not $test->directive ) {
892 # normal passing test
893 print color 'green';
894 }
895 elsif ( !$test->is_ok ) { # even if it's TODO
896 print color 'white on_red';
897 }
898 elsif ( $test->has_skip ) {
899 print color 'white on_blue';
900 }
902 elsif ( $test->has_todo ) {
903 print color 'white';
904 }
905 },
906 ELSE => sub {
907 # plan, comment, and so on (anything which isn't a test line)
908 print color 'black on_white';
909 },
910 ALL => sub {
911 # now print them
912 print shift->as_string;
913 print color 'reset';
914 print "\n";
915 },
916 );
917 • "EOF"
919 Invoked when there are no more lines to be parsed. Since there is
921 no accompanying TAP::Parser::Result object the "TAP::Parser" object
922 is passed instead.
923
925 If you're looking for an EBNF grammar, see TAP::Parser::Grammar.
926
928 The Perl-QA list attempted to ensure backwards compatibility with
929 Test::Harness. However, there are some minor differences.
930 Differences
932 • TODO plans
933 A little-known feature of Test::Harness is that it supported TODO
935 lists in the plan:
936 1..2 todo 2
938 ok 1 - We have liftoff
939 not ok 2 - Anti-gravity device activated
940 Under Test::Harness, test number 2 would pass because it was listed
942 as a TODO test on the plan line. However, we are not aware of
943 anyone actually using this feature and hard-coding test numbers is
944 discouraged because it's very easy to add a test and break the test
945 number sequence. This makes test suites very fragile. Instead, the
946 following should be used:
947 1..2
949 ok 1 - We have liftoff
950 not ok 2 - Anti-gravity device activated # TODO
951 • 'Missing' tests
953 It rarely happens, but sometimes a harness might encounter 'missing
955 tests:
956 ok 1
958 ok 2
959 ok 15
960 ok 16
961 ok 17
962 Test::Harness would report tests 3-14 as having failed. For the
964 "TAP::Parser", these tests are not considered failed because
965 they've never run. They're reported as parse failures (tests out of
966 sequence).
967
969 If you find you need to provide custom functionality (as you would have
970 using Test::Harness::Straps), you're in luck: "TAP::Parser" and friends
971 are designed to be easily plugged-into and/or subclassed.
972 Before you start, it's important to know a few things:
974 1.
976 All "TAP::*" objects inherit from TAP::Object.
977 2.
979 Many "TAP::*" classes have a SUBCLASSING section to guide you.
980 3.
982 Note that "TAP::Parser" is designed to be the central "maker" - ie:
983 it is responsible for creating most new objects in the
984 "TAP::Parser::*" namespace.
985 This makes it possible for you to have a single point of configuring
987 what subclasses should be used, which means that in many cases you'll
988 find you only need to sub-class one of the parser's components.
989 The exception to this rule are SourceHandlers & Iterators, but those
991 are both created with customizable IteratorFactory.
992 4.
994 By subclassing, you may end up overriding undocumented methods.
995 That's not a bad thing per se, but be forewarned that undocumented
996 methods may change without warning from one release to the next - we
997 cannot guarantee backwards compatibility. If any documented method
998 needs changing, it will be deprecated first, and changed in a later
999 release.
1000 Parser Components
1002 Sources
1003 A TAP parser consumes input from a single raw source of TAP, which
1005 could come from anywhere (a file, an executable, a database, an IO
1006 handle, a URI, etc..). The source gets bundled up in a
1007 TAP::Parser::Source object which gathers some meta data about it. The
1008 parser then uses a TAP::Parser::IteratorFactory to determine which
1009 TAP::Parser::SourceHandler to use to turn the raw source into a stream
1010 of TAP by way of "Iterators".
1011 If you simply want "TAP::Parser" to handle a new source of TAP you
1013 probably don't need to subclass "TAP::Parser" itself. Rather, you'll
1014 need to create a new TAP::Parser::SourceHandler class, and just plug it
1015 into the parser using the sources param to "new". Before you start
1016 writing one, read through TAP::Parser::IteratorFactory to get a feel
1017 for how the system works first.
1018 If you find you really need to use your own iterator factory you can
1020 still do so without sub-classing "TAP::Parser" by setting
1021 "iterator_factory_class".
1022 If you just need to customize the objects on creation, subclass
1024 TAP::Parser and override "make_iterator_factory".
1025 Note that "make_source" & "make_perl_source" have been DEPRECATED and
1027 are now removed.
1028 Iterators
1030 A TAP parser uses iterators to loop through the stream of TAP read in
1032 from the source it was given. There are a few types of Iterators
1033 available by default, all sub-classes of TAP::Parser::Iterator.
1034 Choosing which iterator to use is the responsibility of the iterator
1035 factory, though it simply delegates to the Source Handler it uses.
1036 If you're writing your own TAP::Parser::SourceHandler, you may need to
1038 create your own iterators too. If so you'll need to subclass
1039 TAP::Parser::Iterator.
1040 Note that "make_iterator" has been DEPRECATED and is now removed.
1042 Results
1044 A TAP parser creates TAP::Parser::Results as it iterates through the
1046 input stream. There are quite a few result types available; choosing
1047 which class to use is the responsibility of the result factory.
1048 To create your own result types you have two options:
1050 option 1
1052 Subclass TAP::Parser::Result and register your new result type/class
1053 with the default TAP::Parser::ResultFactory.
1054 option 2
1056 Subclass TAP::Parser::ResultFactory itself and implement your own
1057 TAP::Parser::Result creation logic. Then you'll need to customize
1058 the class used by your parser by setting the "result_factory_class"
1059 parameter. See "new" for more details.
1060 If you need to customize the objects on creation, subclass TAP::Parser
1062 and override "make_result".
1063 Grammar
1065 TAP::Parser::Grammar is the heart of the parser. It tokenizes the TAP
1067 input stream and produces results. If you need to customize its
1068 behaviour you should probably familiarize yourself with the source
1069 first. Enough lecturing.
1070 Subclass TAP::Parser::Grammar and customize your parser by setting the
1072 "grammar_class" parameter. See "new" for more details.
1073 If you need to customize the objects on creation, subclass TAP::Parser
1075 and override "make_grammar"
1076
1078 All of the following have helped. Bug reports, patches, (im)moral
1079 support, or just words of encouragement have all been forthcoming.
1080 • Michael Schwern
1082 • Andy Lester
1084 • chromatic
1086 • GEOFFR
1088 • Shlomi Fish
1090 • Torsten Schoenfeld
1092 • Jerry Gay
1094 • Aristotle
1096 • Adam Kennedy
1098 • Yves Orton
1100 • Adrian Howard
1102 • Sean & Lil
1104 • Andreas J. Koenig
1106 • Florian Ragwitz
1108 • Corion
1110 • Mark Stosberg
1112 • Matt Kraai
1114 • David Wheeler
1116 • Alex Vandiver
1118 • Cosimo Streppone
1120 • Ville Skyttä
1122
1124 Curtis "Ovid" Poe <ovid@cpan.org>
1125 Andy Armstong <andy@hexten.net>
1127 Eric Wilhelm @ <ewilhelm at cpan dot org>
1129 Michael Peters <mpeters at plusthree dot com>
1131 Leif Eriksen <leif dot eriksen at bigpond dot com>
1133 Steve Purkis <spurkis@cpan.org>
1135 Nicholas Clark <nick@ccl4.org>
1137 Lee Johnson <notfadeaway at btinternet dot com>
1139 Philippe Bruhat <book@cpan.org>
1141
1143 Please report any bugs or feature requests to
1144 "bug-test-harness@rt.cpan.org", or through the web interface at
1145 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Harness>. We will
1146 be notified, and then you'll automatically be notified of progress on
1147 your bug as we make changes.
1148 Obviously, bugs which include patches are best. If you prefer, you can
1150 patch against bleed by via anonymous checkout of the latest version:
1151 git clone git://github.com/Perl-Toolchain-Gang/Test-Harness.git
1153
1155 Copyright 2006-2008 Curtis "Ovid" Poe, all rights reserved.
1156 This program is free software; you can redistribute it and/or modify it
1158 under the same terms as Perl itself.
1159perl v5.34.1 2022-04-19 TAP::Parser(3)