1TAP::Parser(3) User Contributed Perl Documentation TAP::Parser(3)
2
6 TAP::Parser - Parse TAP output
7
9 Version 3.28
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/wiki/index.php/TAP::Parser_Cookbook>
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 to the
105 source 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 time when the Parser was created.
687 "end_time"
689 Returns the time when the end of TAP input was seen.
691 "has_problems"
693 if ( $parser->has_problems ) {
695 ...
696 }
697 This is a 'catch-all' method which returns true if any tests have
699 currently failed, any TODO tests unexpectedly succeeded, or any parse
700 errors occurred.
701 "version"
703 $parser->version;
705 Once the parser is done, this will return the version number for the
707 parsed TAP. Version numbers were introduced with TAP version 13 so if
708 no version number is found version 12 is assumed.
709 "exit"
711 $parser->exit;
713 Once the parser is done, this will return the exit status. If the
715 parser ran an executable, it returns the exit status of the executable.
716 "wait"
718 $parser->wait;
720 Once the parser is done, this will return the wait status. If the
722 parser ran an executable, it returns the wait status of the executable.
723 Otherwise, this merely returns the "exit" status.
724 "ignore_exit"
726 $parser->ignore_exit(1);
727 Tell the parser to ignore the exit status from the test when
729 determining whether the test passed. Normally tests with non-zero exit
730 status are considered to have failed even if all individual tests
731 passed. In cases where it is not possible to control the exit value of
732 the test script use this option to ignore it.
733 "parse_errors"
735 my @errors = $parser->parse_errors; # the parser errors
737 my $errors = $parser->parse_errors; # the number of parser_errors
738 Fortunately, all TAP output is perfect. In the event that it is not,
740 this method will return parser errors. Note that a junk line which the
741 parser does not recognize is "not" an error. This allows this parser
742 to handle future versions of TAP. The following are all TAP errors
743 reported by the parser:
744 · Misplaced plan
746 The plan (for example, '1..5'), must only come at the beginning or
748 end of the TAP output.
749 · No plan
751 Gotta have a plan!
753 · More than one plan
755 1..3
757 ok 1 - input file opened
758 not ok 2 - first line of the input valid # todo some data
759 ok 3 read the rest of the file
760 1..3
761 Right. Very funny. Don't do that.
763 · Test numbers out of sequence
765 1..3
767 ok 1 - input file opened
768 not ok 2 - first line of the input valid # todo some data
769 ok 2 read the rest of the file
770 That last test line above should have the number '3' instead of
772 '2'.
773 Note that it's perfectly acceptable for some lines to have test
775 numbers and others to not have them. However, when a test number
776 is found, it must be in sequence. The following is also an error:
777 1..3
779 ok 1 - input file opened
780 not ok - first line of the input valid # todo some data
781 ok 2 read the rest of the file
782 But this is not:
784 1..3
786 ok - input file opened
787 not ok - first line of the input valid # todo some data
788 ok 3 read the rest of the file
789 "get_select_handles"
791 Get an a list of file handles which can be passed to "select" to
793 determine the readiness of this parser.
794 "delete_spool"
796 Delete and return the spool.
798 my $fh = $parser->delete_spool;
800
802 As mentioned earlier, a "callback" key may be added to the
803 "TAP::Parser" constructor. If present, each callback corresponding to a
804 given result type will be called with the result as the argument if the
805 "run" method is used. The callback is expected to be a subroutine
806 reference (or anonymous subroutine) which is invoked with the parser
807 result as its argument.
808 my %callbacks = (
810 test => \&test_callback,
811 plan => \&plan_callback,
812 comment => \&comment_callback,
813 bailout => \&bailout_callback,
814 unknown => \&unknown_callback,
815 );
816 my $aggregator = TAP::Parser::Aggregator->new;
818 for my $file ( @test_files ) {
819 my $parser = TAP::Parser->new(
820 {
821 source => $file,
822 callbacks => \%callbacks,
823 }
824 );
825 $parser->run;
826 $aggregator->add( $file, $parser );
827 }
828 Callbacks may also be added like this:
830 $parser->callback( test => \&test_callback );
832 $parser->callback( plan => \&plan_callback );
833 The following keys allowed for callbacks. These keys are case-
835 sensitive.
836 · "test"
838 Invoked if "$result->is_test" returns true.
840 · "version"
842 Invoked if "$result->is_version" returns true.
844 · "plan"
846 Invoked if "$result->is_plan" returns true.
848 · "comment"
850 Invoked if "$result->is_comment" returns true.
852 · "bailout"
854 Invoked if "$result->is_unknown" returns true.
856 · "yaml"
858 Invoked if "$result->is_yaml" returns true.
860 · "unknown"
862 Invoked if "$result->is_unknown" returns true.
864 · "ELSE"
866 If a result does not have a callback defined for it, this callback
868 will be invoked. Thus, if all of the previous result types are
869 specified as callbacks, this callback will never be invoked.
870 · "ALL"
872 This callback will always be invoked and this will happen for each
874 result after one of the above callbacks is invoked. For example,
875 if Term::ANSIColor is loaded, you could use the following to color
876 your test output:
877 my %callbacks = (
879 test => sub {
880 my $test = shift;
881 if ( $test->is_ok && not $test->directive ) {
882 # normal passing test
883 print color 'green';
884 }
885 elsif ( !$test->is_ok ) { # even if it's TODO
886 print color 'white on_red';
887 }
888 elsif ( $test->has_skip ) {
889 print color 'white on_blue';
890 }
892 elsif ( $test->has_todo ) {
893 print color 'white';
894 }
895 },
896 ELSE => sub {
897 # plan, comment, and so on (anything which isn't a test line)
898 print color 'black on_white';
899 },
900 ALL => sub {
901 # now print them
902 print shift->as_string;
903 print color 'reset';
904 print "\n";
905 },
906 );
907 · "EOF"
909 Invoked when there are no more lines to be parsed. Since there is
911 no accompanying TAP::Parser::Result object the "TAP::Parser" object
912 is passed instead.
913
915 If you're looking for an EBNF grammar, see TAP::Parser::Grammar.
916
918 The Perl-QA list attempted to ensure backwards compatibility with
919 Test::Harness. However, there are some minor differences.
920 Differences
922 · TODO plans
923 A little-known feature of Test::Harness is that it supported TODO
925 lists in the plan:
926 1..2 todo 2
928 ok 1 - We have liftoff
929 not ok 2 - Anti-gravity device activated
930 Under Test::Harness, test number 2 would pass because it was listed
932 as a TODO test on the plan line. However, we are not aware of
933 anyone actually using this feature and hard-coding test numbers is
934 discouraged because it's very easy to add a test and break the test
935 number sequence. This makes test suites very fragile. Instead, the
936 following should be used:
937 1..2
939 ok 1 - We have liftoff
940 not ok 2 - Anti-gravity device activated # TODO
941 · 'Missing' tests
943 It rarely happens, but sometimes a harness might encounter 'missing
945 tests:
946 ok 1
948 ok 2
949 ok 15
950 ok 16
951 ok 17
952 Test::Harness would report tests 3-14 as having failed. For the
954 "TAP::Parser", these tests are not considered failed because
955 they've never run. They're reported as parse failures (tests out of
956 sequence).
957
959 If you find you need to provide custom functionality (as you would have
960 using Test::Harness::Straps), you're in luck: "TAP::Parser" and friends
961 are designed to be easily plugged-into and/or subclassed.
962 Before you start, it's important to know a few things:
964 1.
966 All "TAP::*" objects inherit from TAP::Object.
967 2.
969 Many "TAP::*" classes have a SUBCLASSING section to guide you.
970 3.
972 Note that "TAP::Parser" is designed to be the central "maker" - ie:
973 it is responsible for creating most new objects in the
974 "TAP::Parser::*" namespace.
975 This makes it possible for you to have a single point of configuring
977 what subclasses should be used, which means that in many cases you'll
978 find you only need to sub-class one of the parser's components.
979 The exception to this rule are SourceHandlers & Iterators, but those
981 are both created with customizable IteratorFactory.
982 4.
984 By subclassing, you may end up overriding undocumented methods.
985 That's not a bad thing per se, but be forewarned that undocumented
986 methods may change without warning from one release to the next - we
987 cannot guarantee backwards compatibility. If any documented method
988 needs changing, it will be deprecated first, and changed in a later
989 release.
990 Parser Components
992 Sources
993 A TAP parser consumes input from a single raw source of TAP, which
995 could come from anywhere (a file, an executable, a database, an IO
996 handle, a URI, etc..). The source gets bundled up in a
997 TAP::Parser::Source object which gathers some meta data about it. The
998 parser then uses a TAP::Parser::IteratorFactory to determine which
999 TAP::Parser::SourceHandler to use to turn the raw source into a stream
1000 of TAP by way of "Iterators".
1001 If you simply want "TAP::Parser" to handle a new source of TAP you
1003 probably don't need to subclass "TAP::Parser" itself. Rather, you'll
1004 need to create a new TAP::Parser::SourceHandler class, and just plug it
1005 into the parser using the sources param to "new". Before you start
1006 writing one, read through TAP::Parser::IteratorFactory to get a feel
1007 for how the system works first.
1008 If you find you really need to use your own iterator factory you can
1010 still do so without sub-classing "TAP::Parser" by setting
1011 "iterator_factory_class".
1012 If you just need to customize the objects on creation, subclass
1014 TAP::Parser and override "make_iterator_factory".
1015 Note that "make_source" & "make_perl_source" have been DEPRECATED and
1017 are now removed.
1018 Iterators
1020 A TAP parser uses iterators to loop through the stream of TAP read in
1022 from the source it was given. There are a few types of Iterators
1023 available by default, all sub-classes of TAP::Parser::Iterator.
1024 Choosing which iterator to use is the responsibility of the iterator
1025 factory, though it simply delegates to the Source Handler it uses.
1026 If you're writing your own TAP::Parser::SourceHandler, you may need to
1028 create your own iterators too. If so you'll need to subclass
1029 TAP::Parser::Iterator.
1030 Note that "make_iterator" has been DEPRECATED and is now removed.
1032 Results
1034 A TAP parser creates TAP::Parser::Results as it iterates through the
1036 input stream. There are quite a few result types available; choosing
1037 which class to use is the responsibility of the result factory.
1038 To create your own result types you have two options:
1040 option 1
1042 Subclass TAP::Parser::Result and register your new result type/class
1043 with the default TAP::Parser::ResultFactory.
1044 option 2
1046 Subclass TAP::Parser::ResultFactory itself and implement your own
1047 TAP::Parser::Result creation logic. Then you'll need to customize
1048 the class used by your parser by setting the "result_factory_class"
1049 parameter. See "new" for more details.
1050 If you need to customize the objects on creation, subclass TAP::Parser
1052 and override "make_result".
1053 Grammar
1055 TAP::Parser::Grammar is the heart of the parser. It tokenizes the TAP
1057 input stream and produces results. If you need to customize its
1058 behaviour you should probably familiarize yourself with the source
1059 first. Enough lecturing.
1060 Subclass TAP::Parser::Grammar and customize your parser by setting the
1062 "grammar_class" parameter. See "new" for more details.
1063 If you need to customize the objects on creation, subclass TAP::Parser
1065 and override "make_grammar"
1066
1068 All of the following have helped. Bug reports, patches, (im)moral
1069 support, or just words of encouragement have all been forthcoming.
1070 · Michael Schwern
1072 · Andy Lester
1074 · chromatic
1076 · GEOFFR
1078 · Shlomi Fish
1080 · Torsten Schoenfeld
1082 · Jerry Gay
1084 · Aristotle
1086 · Adam Kennedy
1088 · Yves Orton
1090 · Adrian Howard
1092 · Sean & Lil
1094 · Andreas J. Koenig
1096 · Florian Ragwitz
1098 · Corion
1100 · Mark Stosberg
1102 · Matt Kraai
1104 · David Wheeler
1106 · Alex Vandiver
1108 · Cosimo Streppone
1110 · Ville Skyttae
1112
1114 Curtis "Ovid" Poe <ovid@cpan.org>
1115 Andy Armstong <andy@hexten.net>
1117 Eric Wilhelm @ <ewilhelm at cpan dot org>
1119 Michael Peters <mpeters at plusthree dot com>
1121 Leif Eriksen <leif dot eriksen at bigpond dot com>
1123 Steve Purkis <spurkis@cpan.org>
1125 Nicholas Clark <nick@ccl4.org>
1127 Lee Johnson <notfadeaway at btinternet dot com>
1129 Philippe Bruhat <book@cpan.org>
1131
1133 Please report any bugs or feature requests to
1134 "bug-test-harness@rt.cpan.org", or through the web interface at
1135 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Harness>. We will
1136 be notified, and then you'll automatically be notified of progress on
1137 your bug as we make changes.
1138 Obviously, bugs which include patches are best. If you prefer, you can
1140 patch against bleed by via anonymous checkout of the latest version:
1141 git clone git://github.com/Perl-Toolchain-Gang/Test-Harness.git
1143
1145 Copyright 2006-2008 Curtis "Ovid" Poe, all rights reserved.
1146 This program is free software; you can redistribute it and/or modify it
1148 under the same terms as Perl itself.
1149
1151 Hey! The above document had some coding errors, which are explained
1152 below:
1153 Around line 1871:
1155 Non-ASCII character seen before =encoding in 'Skyttae'. Assuming
1156 UTF-8
1157perl v5.16.3 2013-05-02 TAP::Parser(3)