File Coverage

blib/lib/TAP/Parser.pm
Criterion Covered Total %
statement 302 307 98.3
branch 112 120 93.3
condition 22 30 73.3
subroutine 64 65 98.4
pod 21 21 100.0
total 521 543 95.9


line stmt bran cond sub pod time code
1             package TAP::Parser;
2              
3 31     31   306524 use strict;
  31         49  
  31         901  
4 31     31   122 use warnings;
  31         84  
  31         833  
5              
6 31     31   12881 use TAP::Parser::Grammar ();
  31         65  
  31         684  
7 31     31   176 use TAP::Parser::Result ();
  31         33  
  31         453  
8 31     31   110 use TAP::Parser::ResultFactory ();
  31         31  
  31         382  
9 31     31   10873 use TAP::Parser::Source ();
  31         56  
  31         503  
10 31     31   8931 use TAP::Parser::Iterator ();
  31         43  
  31         495  
11 31     31   9498 use TAP::Parser::IteratorFactory ();
  31         51  
  31         489  
12 31     31   9523 use TAP::Parser::SourceHandler::Executable ();
  31         74  
  31         556  
13 31     31   9987 use TAP::Parser::SourceHandler::Perl ();
  31         57  
  31         536  
14 31     31   11910 use TAP::Parser::SourceHandler::File ();
  31         55  
  31         491  
15 31     31   10858 use TAP::Parser::SourceHandler::RawTAP ();
  31         60  
  31         535  
16 31     31   11079 use TAP::Parser::SourceHandler::Handle ();
  31         864  
  31         743  
17              
18 31     31   134 use Carp qw( confess );
  31         979  
  31         1519  
19              
20 31     31   118 use base 'TAP::Base';
  31         33  
  31         7639  
21              
22             =encoding utf8
23              
24             =head1 NAME
25              
26             TAP::Parser - Parse L output
27              
28             =head1 VERSION
29              
30             Version 3.38
31              
32             =cut
33              
34             our $VERSION = '3.38';
35              
36             my $DEFAULT_TAP_VERSION = 12;
37             my $MAX_TAP_VERSION = 13;
38              
39             $ENV{TAP_VERSION} = $MAX_TAP_VERSION;
40              
41             END {
42              
43             # For VMS.
44 31     31   22005 delete $ENV{TAP_VERSION};
45             }
46              
47 0         0 BEGIN { # making accessors
48 31     31   327 __PACKAGE__->mk_methods(
49             qw(
50             _iterator
51             _spool
52             exec
53             exit
54             is_good_plan
55             plan
56             tests_planned
57             tests_run
58             wait
59             version
60             in_todo
61             start_time
62             end_time
63             start_times
64             end_times
65             skip_all
66             grammar_class
67             result_factory_class
68             iterator_factory_class
69             )
70             );
71              
72             sub _stream { # deprecated
73 1     1   2 my $self = shift;
74 1         4 $self->_iterator(@_);
75             }
76             } # done making accessors
77              
78             =head1 SYNOPSIS
79              
80             use TAP::Parser;
81              
82             my $parser = TAP::Parser->new( { source => $source } );
83              
84             while ( my $result = $parser->next ) {
85             print $result->as_string;
86             }
87              
88             =head1 DESCRIPTION
89              
90             C is designed to produce a proper parse of TAP output. For
91             an example of how to run tests through this module, see the simple
92             harnesses C.
93              
94             There's a wiki dedicated to the Test Anything Protocol:
95              
96             L
97              
98             It includes the TAP::Parser Cookbook:
99              
100             L
101              
102             =head1 METHODS
103              
104             =head2 Class Methods
105              
106             =head3 C
107              
108             my $parser = TAP::Parser->new(\%args);
109              
110             Returns a new C object.
111              
112             The arguments should be a hashref with I of the following keys:
113              
114             =over 4
115              
116             =item * C
117              
118             I
119              
120             This is the preferred method of passing input to the constructor.
121              
122             The C is used to create a L that is passed to the
123             L which in turn figures out how to handle the source and
124             creates a for it. The iterator is used by the parser to
125             read in the TAP stream.
126              
127             To configure the I use the C parameter below.
128              
129             Note that C, C and C are I.
130              
131             =item * C
132              
133             I
134              
135             The value should be the complete TAP output.
136              
137             The I is used to create a L that is passed to the
138             L which in turn figures out how to handle the source and
139             creates a for it. The iterator is used by the parser to
140             read in the TAP stream.
141              
142             To configure the I use the C parameter below.
143              
144             Note that C, C and C are I.
145              
146             =item * C
147              
148             Must be passed an array reference.
149              
150             The I array ref is used to create a L that is passed
151             to the L which in turn figures out how to handle the
152             source and creates a for it. The iterator is used by
153             the parser to read in the TAP stream.
154              
155             By default the L class will create a
156             L object to handle the source. This passes the
157             array reference strings as command arguments to L:
158              
159             exec => [ '/usr/bin/ruby', 't/my_test.rb' ]
160              
161             If any C are given they will be appended to the end of the command
162             argument list.
163              
164             To configure the I use the C parameter below.
165              
166             Note that C, C and C are I.
167              
168             =back
169              
170             The following keys are optional.
171              
172             =over 4
173              
174             =item * C
175              
176             I.
177              
178             If set, C must be a hashref containing the names of the
179             Ls to load and/or configure. The values are a
180             hash of configuration that will be accessible to the source handlers via
181             L.
182              
183             For example:
184              
185             sources => {
186             Perl => { exec => '/path/to/custom/perl' },
187             File => { extensions => [ '.tap', '.txt' ] },
188             MyCustom => { some => 'config' },
189             }
190              
191             This will cause C to pass custom configuration to two of the built-
192             in source handlers - L,
193             L - and attempt to load the C
194             class. See L for more detail.
195              
196             The C parameter affects how C, C and C parameters
197             are handled.
198              
199             See L, L and subclasses for
200             more details.
201              
202             =item * C
203              
204             If present, each callback corresponding to a given result type will be called
205             with the result as the argument if the C method is used:
206              
207             my %callbacks = (
208             test => \&test_callback,
209             plan => \&plan_callback,
210             comment => \&comment_callback,
211             bailout => \&bailout_callback,
212             unknown => \&unknown_callback,
213             );
214              
215             my $aggregator = TAP::Parser::Aggregator->new;
216             for my $file ( @test_files ) {
217             my $parser = TAP::Parser->new(
218             {
219             source => $file,
220             callbacks => \%callbacks,
221             }
222             );
223             $parser->run;
224             $aggregator->add( $file, $parser );
225             }
226              
227             =item * C
228              
229             If using a Perl file as a source, optional switches may be passed which will
230             be used when invoking the perl executable.
231              
232             my $parser = TAP::Parser->new( {
233             source => $test_file,
234             switches => [ '-Ilib' ],
235             } );
236              
237             =item * C
238              
239             Used in conjunction with the C and C option to supply a reference
240             to an C<@ARGV> style array of arguments to pass to the test program.
241              
242             =item * C
243              
244             If passed a filehandle will write a copy of all parsed TAP to that handle.
245              
246             =item * C
247              
248             If false, STDERR is not captured (though it is 'relayed' to keep it
249             somewhat synchronized with STDOUT.)
250              
251             If true, STDERR and STDOUT are the same filehandle. This may cause
252             breakage if STDERR contains anything resembling TAP format, but does
253             allow exact synchronization.
254              
255             Subtleties of this behavior may be platform-dependent and may change in
256             the future.
257              
258             =item * C
259              
260             This option was introduced to let you easily customize which I class
261             the parser should use. It defaults to L.
262              
263             See also L.
264              
265             =item * C
266              
267             This option was introduced to let you easily customize which I
268             factory class the parser should use. It defaults to
269             L.
270              
271             See also L.
272              
273             =item * C
274              
275             I
276              
277             This option was introduced to let you easily customize which I
278             factory class the parser should use. It defaults to
279             L.
280              
281             =back
282              
283             =cut
284              
285             # new() implementation supplied by TAP::Base
286              
287             # This should make overriding behaviour of the Parser in subclasses easier:
288 304     304   991 sub _default_grammar_class {'TAP::Parser::Grammar'}
289 304     304   875 sub _default_result_factory_class {'TAP::Parser::ResultFactory'}
290 304     304   766 sub _default_iterator_factory_class {'TAP::Parser::IteratorFactory'}
291              
292             ##############################################################################
293              
294             =head2 Instance Methods
295              
296             =head3 C
297              
298             my $parser = TAP::Parser->new( { source => $file } );
299             while ( my $result = $parser->next ) {
300             print $result->as_string, "\n";
301             }
302              
303             This method returns the results of the parsing, one result at a time. Note
304             that it is destructive. You can't rewind and examine previous results.
305              
306             If callbacks are used, they will be issued before this call returns.
307              
308             Each result returned is a subclass of L. See that
309             module and related classes for more information on how to use them.
310              
311             =cut
312              
313             sub next {
314 1581     1581 1 222327 my $self = shift;
315 1581   100     7466 return ( $self->{_iter} ||= $self->_iter )->();
316             }
317              
318             ##############################################################################
319              
320             =head3 C
321              
322             $parser->run;
323              
324             This method merely runs the parser and parses all of the TAP.
325              
326             =cut
327              
328             sub run {
329 20     20 1 2190 my $self = shift;
330 20         36 while ( defined( my $result = $self->next ) ) {
331              
332             # do nothing
333             }
334             }
335              
336             ##############################################################################
337              
338             =head3 C
339              
340             Make a new L object and return it. Passes through any
341             arguments given.
342              
343             The C can be customized, as described in L.
344              
345             =head3 C
346              
347             Make a new L object using the parser's
348             L, and return it. Passes through any arguments
349             given.
350              
351             The C can be customized, as described in L.
352              
353             =head3 C
354              
355             I.
356              
357             Make a new L object and return it. Passes through
358             any arguments given.
359              
360             C can be customized, as described in L.
361              
362             =cut
363              
364             # This should make overriding behaviour of the Parser in subclasses easier:
365 291     291 1 739 sub make_iterator_factory { shift->iterator_factory_class->new(@_); }
366 278     278 1 988 sub make_grammar { shift->grammar_class->new(@_); }
367 1325     1325 1 4324 sub make_result { shift->result_factory_class->make_result(@_); }
368              
369             {
370              
371             # of the following, anything beginning with an underscore is strictly
372             # internal and should not be exposed.
373             my %initialize = (
374             version => $DEFAULT_TAP_VERSION,
375             plan => '', # the test plan (e.g., 1..3)
376             tests_run => 0, # actual current test numbers
377             skipped => [], #
378             todo => [], #
379             passed => [], #
380             failed => [], #
381             actual_failed => [], # how many tests really failed
382             actual_passed => [], # how many tests really passed
383             todo_passed => [], # tests which unexpectedly succeed
384             parse_errors => [], # perfect TAP should have none
385             );
386              
387             # We seem to have this list hanging around all over the place. We could
388             # probably get it from somewhere else to avoid the repetition.
389             my @legal_callback = qw(
390             test
391             version
392             plan
393             comment
394             bailout
395             unknown
396             yaml
397             ALL
398             ELSE
399             EOF
400             );
401              
402             my @class_overrides = qw(
403             grammar_class
404             result_factory_class
405             iterator_factory_class
406             );
407              
408             sub _initialize {
409 305     305   559 my ( $self, $arg_for ) = @_;
410              
411             # everything here is basically designed to convert any TAP source to a
412             # TAP::Parser::Iterator.
413              
414             # Shallow copy
415 305 100       789 my %args = %{ $arg_for || {} };
  305         1811  
416              
417 305         2149 $self->SUPER::_initialize( \%args, \@legal_callback );
418              
419             # get any class overrides out first:
420 304         905 for my $key (@class_overrides) {
421 912         1528 my $default_method = "_default_$key";
422 912   66     8700 my $val = delete $args{$key} || $self->$default_method();
423 912         2344 $self->$key($val);
424             }
425              
426 304         563 my $iterator = delete $args{iterator};
427 304   66     1349 $iterator ||= delete $args{stream}; # deprecated
428 304         455 my $tap = delete $args{tap};
429 304         591 my $version = delete $args{version};
430 304         602 my $raw_source = delete $args{source};
431 304         433 my $sources = delete $args{sources};
432 304         505 my $exec = delete $args{exec};
433 304         487 my $merge = delete $args{merge};
434 304         399 my $spool = delete $args{spool};
435 304         377 my $switches = delete $args{switches};
436 304         384 my $ignore_exit = delete $args{ignore_exit};
437 304   100     1320 my $test_args = delete $args{test_args} || [];
438              
439 304 100       552 if ( 1 < grep {defined} $iterator, $tap, $raw_source, $exec ) {
  1216         2283  
440 1         3 $self->_croak(
441             "You may only choose one of 'exec', 'tap', 'source' or 'iterator'"
442             );
443             }
444              
445 303 50       1169 if ( my @excess = sort keys %args ) {
446 0         0 $self->_croak("Unknown options: @excess");
447             }
448              
449             # convert $tap & $exec to $raw_source equiv.
450 303         657 my $type = '';
451 303         2101 my $source = TAP::Parser::Source->new;
452 303 100       1485 if ($tap) {
    100          
    100          
    100          
453 60         57 $type = 'raw TAP';
454 60         129 $source->raw( \$tap );
455             }
456             elsif ($exec) {
457 11         27 $type = 'exec ' . $exec->[0];
458 11         43 $source->raw( { exec => $exec } );
459             }
460             elsif ($raw_source) {
461 220   33     913 $type = 'source ' . ref($raw_source) || $raw_source;
462 220 100       1225 $source->raw( ref($raw_source) ? $raw_source : \$raw_source );
463             }
464             elsif ($iterator) {
465 11         31 $type = 'iterator ' . ref($iterator);
466             }
467              
468 303 100       775 if ( $source->raw ) {
469 291         839 my $src_factory = $self->make_iterator_factory($sources);
470 291         1058 $source->merge($merge)->switches($switches)
471             ->test_args($test_args);
472 291         1066 $iterator = $src_factory->make_iterator($source);
473             }
474              
475 302 100       1470 unless ($iterator) {
476 1         8 $self->_croak(
477             "PANIC: could not determine iterator for input $type");
478             }
479              
480 301         2121 while ( my ( $k, $v ) = each %initialize ) {
481 3311 100       14325 $self->{$k} = 'ARRAY' eq ref $v ? [] : $v;
482             }
483              
484 301 50       743 $self->version($version) if $version;
485 301         2306 $self->_iterator($iterator);
486 301         887 $self->_spool($spool);
487 301         1326 $self->ignore_exit($ignore_exit);
488              
489 301         10518 return $self;
490             }
491             }
492              
493             =head1 INDIVIDUAL RESULTS
494              
495             If you've read this far in the docs, you've seen this:
496              
497             while ( my $result = $parser->next ) {
498             print $result->as_string;
499             }
500              
501             Each result returned is a L subclass, referred to as
502             I.
503              
504             =head2 Result types
505              
506             Basically, you fetch individual results from the TAP. The six types, with
507             examples of each, are as follows:
508              
509             =over 4
510              
511             =item * Version
512              
513             TAP version 12
514              
515             =item * Plan
516              
517             1..42
518              
519             =item * Pragma
520              
521             pragma +strict
522              
523             =item * Test
524              
525             ok 3 - We should start with some foobar!
526              
527             =item * Comment
528              
529             # Hope we don't use up the foobar.
530              
531             =item * Bailout
532              
533             Bail out! We ran out of foobar!
534              
535             =item * Unknown
536              
537             ... yo, this ain't TAP! ...
538              
539             =back
540              
541             Each result fetched is a result object of a different type. There are common
542             methods to each result object and different types may have methods unique to
543             their type. Sometimes a type method may be overridden in a subclass, but its
544             use is guaranteed to be identical.
545              
546             =head2 Common type methods
547              
548             =head3 C
549              
550             Returns the type of result, such as C or C.
551              
552             =head3 C
553              
554             Prints a string representation of the token. This might not be the exact
555             output, however. Tests will have test numbers added if not present, TODO and
556             SKIP directives will be capitalized and, in general, things will be cleaned
557             up. If you need the original text for the token, see the C method.
558              
559             =head3 C
560              
561             Returns the original line of text which was parsed.
562              
563             =head3 C
564              
565             Indicates whether or not this is the test plan line.
566              
567             =head3 C
568              
569             Indicates whether or not this is a test line.
570              
571             =head3 C
572              
573             Indicates whether or not this is a comment. Comments will generally only
574             appear in the TAP stream if STDERR is merged to STDOUT. See the
575             C option.
576              
577             =head3 C
578              
579             Indicates whether or not this is bailout line.
580              
581             =head3 C
582              
583             Indicates whether or not the current item is a YAML block.
584              
585             =head3 C
586              
587             Indicates whether or not the current line could be parsed.
588              
589             =head3 C
590              
591             if ( $result->is_ok ) { ... }
592              
593             Reports whether or not a given result has passed. Anything which is B a
594             test result returns true. This is merely provided as a convenient shortcut
595             which allows you to do this:
596              
597             my $parser = TAP::Parser->new( { source => $source } );
598             while ( my $result = $parser->next ) {
599             # only print failing results
600             print $result->as_string unless $result->is_ok;
601             }
602              
603             =head2 C methods
604              
605             if ( $result->is_plan ) { ... }
606              
607             If the above evaluates as true, the following methods will be available on the
608             C<$result> object.
609              
610             =head3 C
611              
612             if ( $result->is_plan ) {
613             print $result->plan;
614             }
615              
616             This is merely a synonym for C.
617              
618             =head3 C
619              
620             my $directive = $result->directive;
621              
622             If a SKIP directive is included with the plan, this method will return it.
623              
624             1..0 # SKIP: why bother?
625              
626             =head3 C
627              
628             my $explanation = $result->explanation;
629              
630             If a SKIP directive was included with the plan, this method will return the
631             explanation, if any.
632              
633             =head2 C methods
634              
635             if ( $result->is_pragma ) { ... }
636              
637             If the above evaluates as true, the following methods will be available on the
638             C<$result> object.
639              
640             =head3 C
641              
642             Returns a list of pragmas each of which is a + or - followed by the
643             pragma name.
644              
645             =head2 C methods
646              
647             if ( $result->is_comment ) { ... }
648              
649             If the above evaluates as true, the following methods will be available on the
650             C<$result> object.
651              
652             =head3 C
653              
654             if ( $result->is_comment ) {
655             my $comment = $result->comment;
656             print "I have something to say: $comment";
657             }
658              
659             =head2 C methods
660              
661             if ( $result->is_bailout ) { ... }
662              
663             If the above evaluates as true, the following methods will be available on the
664             C<$result> object.
665              
666             =head3 C
667              
668             if ( $result->is_bailout ) {
669             my $explanation = $result->explanation;
670             print "We bailed out because ($explanation)";
671             }
672              
673             If, and only if, a token is a bailout token, you can get an "explanation" via
674             this method. The explanation is the text after the mystical "Bail out!" words
675             which appear in the tap output.
676              
677             =head2 C methods
678              
679             if ( $result->is_unknown ) { ... }
680              
681             There are no unique methods for unknown results.
682              
683             =head2 C methods
684              
685             if ( $result->is_test ) { ... }
686              
687             If the above evaluates as true, the following methods will be available on the
688             C<$result> object.
689              
690             =head3 C
691              
692             my $ok = $result->ok;
693              
694             Returns the literal text of the C or C status.
695              
696             =head3 C
697              
698             my $test_number = $result->number;
699              
700             Returns the number of the test, even if the original TAP output did not supply
701             that number.
702              
703             =head3 C
704              
705             my $description = $result->description;
706              
707             Returns the description of the test, if any. This is the portion after the
708             test number but before the directive.
709              
710             =head3 C
711              
712             my $directive = $result->directive;
713              
714             Returns either C or C if either directive was present for a test
715             line.
716              
717             =head3 C
718              
719             my $explanation = $result->explanation;
720              
721             If a test had either a C or C directive, this method will return
722             the accompanying explanation, if present.
723              
724             not ok 17 - 'Pigs can fly' # TODO not enough acid
725              
726             For the above line, the explanation is I.
727              
728             =head3 C
729              
730             if ( $result->is_ok ) { ... }
731              
732             Returns a boolean value indicating whether or not the test passed. Remember
733             that for TODO tests, the test always passes.
734              
735             B this was formerly C. The latter method is deprecated and
736             will issue a warning.
737              
738             =head3 C
739              
740             if ( $result->is_actual_ok ) { ... }
741              
742             Returns a boolean value indicating whether or not the test passed, regardless
743             of its TODO status.
744              
745             B this was formerly C. The latter method is deprecated
746             and will issue a warning.
747              
748             =head3 C
749              
750             if ( $test->is_unplanned ) { ... }
751              
752             If a test number is greater than the number of planned tests, this method will
753             return true. Unplanned tests will I return false for C,
754             regardless of whether or not the test C (see
755             L for more information about this).
756              
757             =head3 C
758              
759             if ( $result->has_skip ) { ... }
760              
761             Returns a boolean value indicating whether or not this test had a SKIP
762             directive.
763              
764             =head3 C
765              
766             if ( $result->has_todo ) { ... }
767              
768             Returns a boolean value indicating whether or not this test had a TODO
769             directive.
770              
771             Note that TODO tests I pass. If you need to know whether or not
772             they really passed, check the C method.
773              
774             =head3 C
775              
776             if ( $parser->in_todo ) { ... }
777              
778             True while the most recent result was a TODO. Becomes true before the
779             TODO result is returned and stays true until just before the next non-
780             TODO test is returned.
781              
782             =head1 TOTAL RESULTS
783              
784             After parsing the TAP, there are many methods available to let you dig through
785             the results and determine what is meaningful to you.
786              
787             =head2 Individual Results
788              
789             These results refer to individual tests which are run.
790              
791             =head3 C
792              
793             my @passed = $parser->passed; # the test numbers which passed
794             my $passed = $parser->passed; # the number of tests which passed
795              
796             This method lets you know which (or how many) tests passed. If a test failed
797             but had a TODO directive, it will be counted as a passed test.
798              
799             =cut
800              
801             sub passed {
802 449         3596 return @{ $_[0]->{passed} }
803 655 100   655 1 58052 if ref $_[0]->{passed};
804 206 100       1281 return wantarray ? 1 .. $_[0]->{passed} : $_[0]->{passed};
805             }
806              
807             =head3 C
808              
809             my @failed = $parser->failed; # the test numbers which failed
810             my $failed = $parser->failed; # the number of tests which failed
811              
812             This method lets you know which (or how many) tests failed. If a test passed
813             but had a TODO directive, it will B be counted as a failed test.
814              
815             =cut
816              
817 849     849 1 64761 sub failed { @{ shift->{failed} } }
  849         3697  
818              
819             =head3 C
820              
821             # the test numbers which actually passed
822             my @actual_passed = $parser->actual_passed;
823              
824             # the number of tests which actually passed
825             my $actual_passed = $parser->actual_passed;
826              
827             This method lets you know which (or how many) tests actually passed,
828             regardless of whether or not a TODO directive was found.
829              
830             =cut
831              
832             sub actual_passed {
833 138         1062 return @{ $_[0]->{actual_passed} }
834 294 100   294 1 51440 if ref $_[0]->{actual_passed};
835 156 100       1103 return wantarray ? 1 .. $_[0]->{actual_passed} : $_[0]->{actual_passed};
836             }
837             *actual_ok = \&actual_passed;
838              
839             =head3 C
840              
841             This method is a synonym for C.
842              
843             =head3 C
844              
845             # the test numbers which actually failed
846             my @actual_failed = $parser->actual_failed;
847              
848             # the number of tests which actually failed
849             my $actual_failed = $parser->actual_failed;
850              
851             This method lets you know which (or how many) tests actually failed,
852             regardless of whether or not a TODO directive was found.
853              
854             =cut
855              
856 178     178 1 40682 sub actual_failed { @{ shift->{actual_failed} } }
  178         1576  
857              
858             ##############################################################################
859              
860             =head3 C
861              
862             my @todo = $parser->todo; # the test numbers with todo directives
863             my $todo = $parser->todo; # the number of tests with todo directives
864              
865             This method lets you know which (or how many) tests had TODO directives.
866              
867             =cut
868              
869 351     351 1 61013 sub todo { @{ shift->{todo} } }
  351         2070  
870              
871             =head3 C
872              
873             # the test numbers which unexpectedly succeeded
874             my @todo_passed = $parser->todo_passed;
875              
876             # the number of tests which unexpectedly succeeded
877             my $todo_passed = $parser->todo_passed;
878              
879             This method lets you know which (or how many) tests actually passed but were
880             declared as "TODO" tests.
881              
882             =cut
883              
884 460     460 1 42150 sub todo_passed { @{ shift->{todo_passed} } }
  460         2438  
885              
886             ##############################################################################
887              
888             =head3 C
889              
890             # deprecated in favor of 'todo_passed'. This method was horribly misnamed.
891              
892             This was a badly misnamed method. It indicates which TODO tests unexpectedly
893             succeeded. Will now issue a warning and call C.
894              
895             =cut
896              
897             sub todo_failed {
898 1     1 1 31 warn
899             '"todo_failed" is deprecated. Please use "todo_passed". See the docs.';
900 1         8 goto &todo_passed;
901             }
902              
903             =head3 C
904              
905             my @skipped = $parser->skipped; # the test numbers with SKIP directives
906             my $skipped = $parser->skipped; # the number of tests with SKIP directives
907              
908             This method lets you know which (or how many) tests had SKIP directives.
909              
910             =cut
911              
912 383     383 1 64984 sub skipped { @{ shift->{skipped} } }
  383         2171  
913              
914             =head2 Pragmas
915              
916             =head3 C
917              
918             Get or set a pragma. To get the state of a pragma:
919              
920             if ( $p->pragma('strict') ) {
921             # be strict
922             }
923              
924             To set the state of a pragma:
925              
926             $p->pragma('strict', 1); # enable strict mode
927              
928             =cut
929              
930             sub pragma {
931 657     657 1 1684 my ( $self, $pragma ) = splice @_, 0, 2;
932              
933 657 100       2371 return $self->{pragma}->{$pragma} unless @_;
934              
935 313 100       878 if ( my $state = shift ) {
936 10         22 $self->{pragma}->{$pragma} = 1;
937             }
938             else {
939 303         854 delete $self->{pragma}->{$pragma};
940             }
941              
942 313         464 return;
943             }
944              
945             =head3 C
946              
947             Get a list of all the currently enabled pragmas:
948              
949             my @pragmas_enabled = $p->pragmas;
950              
951             =cut
952              
953 0 0   0 1 0 sub pragmas { sort keys %{ shift->{pragma} || {} } }
  0         0  
954              
955             =head2 Summary Results
956              
957             These results are "meta" information about the total results of an individual
958             test program.
959              
960             =head3 C
961              
962             my $plan = $parser->plan;
963              
964             Returns the test plan, if found.
965              
966             =head3 C
967              
968             Deprecated. Use C instead.
969              
970             =cut
971              
972             sub good_plan {
973 86     86 1 45013 warn 'good_plan() is deprecated. Please use "is_good_plan()"';
974 86         30650 goto &is_good_plan;
975             }
976              
977             ##############################################################################
978              
979             =head3 C
980              
981             if ( $parser->is_good_plan ) { ... }
982              
983             Returns a boolean value indicating whether or not the number of tests planned
984             matches the number of tests run.
985              
986             B this was formerly C. The latter method is deprecated and
987             will issue a warning.
988              
989             And since we're on that subject ...
990              
991             =head3 C
992              
993             print $parser->tests_planned;
994              
995             Returns the number of tests planned, according to the plan. For example, a
996             plan of '1..17' will mean that 17 tests were planned.
997              
998             =head3 C
999              
1000             print $parser->tests_run;
1001              
1002             Returns the number of tests which actually were run. Hopefully this will
1003             match the number of C<< $parser->tests_planned >>.
1004              
1005             =head3 C
1006              
1007             Returns a true value (actually the reason for skipping) if all tests
1008             were skipped.
1009              
1010             =head3 C
1011              
1012             Returns the wall-clock time when the Parser was created.
1013              
1014             =head3 C
1015              
1016             Returns the wall-clock time when the end of TAP input was seen.
1017              
1018             =head3 C
1019              
1020             Returns the CPU times (like L when the Parser was created.
1021              
1022             =head3 C
1023              
1024             Returns the CPU times (like L when the end of TAP
1025             input was seen.
1026              
1027             =head3 C
1028              
1029             if ( $parser->has_problems ) {
1030             ...
1031             }
1032              
1033             This is a 'catch-all' method which returns true if any tests have currently
1034             failed, any TODO tests unexpectedly succeeded, or any parse errors occurred.
1035              
1036             =cut
1037              
1038             sub has_problems {
1039 159     159 1 195 my $self = shift;
1040             return
1041 159   66     244 $self->failed
1042             || $self->parse_errors
1043             || ( !$self->ignore_exit && ( $self->wait || $self->exit ) );
1044             }
1045              
1046             =head3 C
1047              
1048             $parser->version;
1049              
1050             Once the parser is done, this will return the version number for the
1051             parsed TAP. Version numbers were introduced with TAP version 13 so if no
1052             version number is found version 12 is assumed.
1053              
1054             =head3 C
1055              
1056             $parser->exit;
1057              
1058             Once the parser is done, this will return the exit status. If the parser ran
1059             an executable, it returns the exit status of the executable.
1060              
1061             =head3 C
1062              
1063             $parser->wait;
1064              
1065             Once the parser is done, this will return the wait status. If the parser ran
1066             an executable, it returns the wait status of the executable. Otherwise, this
1067             merely returns the C status.
1068              
1069             =head2 C
1070              
1071             $parser->ignore_exit(1);
1072              
1073             Tell the parser to ignore the exit status from the test when determining
1074             whether the test passed. Normally tests with non-zero exit status are
1075             considered to have failed even if all individual tests passed. In cases
1076             where it is not possible to control the exit value of the test script
1077             use this option to ignore it.
1078              
1079             =cut
1080              
1081 622     622 1 1846 sub ignore_exit { shift->pragma( 'ignore_exit', @_ ) }
1082              
1083             =head3 C
1084              
1085             my @errors = $parser->parse_errors; # the parser errors
1086             my $errors = $parser->parse_errors; # the number of parser_errors
1087              
1088             Fortunately, all TAP output is perfect. In the event that it is not, this
1089             method will return parser errors. Note that a junk line which the parser does
1090             not recognize is C an error. This allows this parser to handle future
1091             versions of TAP. The following are all TAP errors reported by the parser:
1092              
1093             =over 4
1094              
1095             =item * Misplaced plan
1096              
1097             The plan (for example, '1..5'), must only come at the beginning or end of the
1098             TAP output.
1099              
1100             =item * No plan
1101              
1102             Gotta have a plan!
1103              
1104             =item * More than one plan
1105              
1106             1..3
1107             ok 1 - input file opened
1108             not ok 2 - first line of the input valid # todo some data
1109             ok 3 read the rest of the file
1110             1..3
1111              
1112             Right. Very funny. Don't do that.
1113              
1114             =item * Test numbers out of sequence
1115              
1116             1..3
1117             ok 1 - input file opened
1118             not ok 2 - first line of the input valid # todo some data
1119             ok 2 read the rest of the file
1120              
1121             That last test line above should have the number '3' instead of '2'.
1122              
1123             Note that it's perfectly acceptable for some lines to have test numbers and
1124             others to not have them. However, when a test number is found, it must be in
1125             sequence. The following is also an error:
1126              
1127             1..3
1128             ok 1 - input file opened
1129             not ok - first line of the input valid # todo some data
1130             ok 2 read the rest of the file
1131              
1132             But this is not:
1133              
1134             1..3
1135             ok - input file opened
1136             not ok - first line of the input valid # todo some data
1137             ok 3 read the rest of the file
1138              
1139             =back
1140              
1141             =cut
1142              
1143 758     758 1 73227 sub parse_errors { @{ shift->{parse_errors} } }
  758         3463  
1144              
1145             sub _add_error {
1146 142     142   299 my ( $self, $error ) = @_;
1147 142         156 push @{ $self->{parse_errors} } => $error;
  142         364  
1148 142         260 return $self;
1149             }
1150              
1151             sub _make_state_table {
1152 278     278   442 my $self = shift;
1153 278         343 my %states;
1154 278         572 my %planned_todo = ();
1155              
1156             # These transitions are defaults for all states
1157             my %state_globals = (
1158             comment => {},
1159             bailout => {},
1160             yaml => {},
1161             version => {
1162             act => sub {
1163 3     3   23 $self->_add_error(
1164             'If TAP version is present it must be the first line of output'
1165             );
1166             },
1167             },
1168             unknown => {
1169             act => sub {
1170 31     31   47 my $unk = shift;
1171 31 100       91 if ( $self->pragma('strict') ) {
1172 2         12 $self->_add_error(
1173             'Unknown TAP token: "' . $unk->raw . '"' );
1174             }
1175             },
1176             },
1177             pragma => {
1178             act => sub {
1179 4     4   10 my ($pragma) = @_;
1180 4         29 for my $pr ( $pragma->pragmas ) {
1181 4 50       46 if ( $pr =~ /^ ([-+])(\w+) $/x ) {
1182 4         28 $self->pragma( $2, $1 eq '+' );
1183             }
1184             }
1185             },
1186             },
1187 278         8309 );
1188              
1189             # Provides default elements for transitions
1190             my %state_defaults = (
1191             plan => {
1192             act => sub {
1193 254     254   377 my ($plan) = @_;
1194 254         1312 $self->tests_planned( $plan->tests_planned );
1195 254         945 $self->plan( $plan->plan );
1196 254 100       820 if ( $plan->has_skip ) {
1197 8   100     44 $self->skip_all( $plan->explanation
1198             || '(no reason given)' );
1199             }
1200              
1201 254         362 $planned_todo{$_}++ for @{ $plan->todo_list };
  254         814  
1202             },
1203             },
1204             test => {
1205             act => sub {
1206 861     861   1315 my ($test) = @_;
1207              
1208             my ( $number, $tests_run )
1209 861         3006 = ( $test->number, ++$self->{tests_run} );
1210              
1211             # Fake TODO state
1212 861 100 66     3461 if ( defined $number && delete $planned_todo{$number} ) {
1213 4         36 $test->set_directive('TODO');
1214             }
1215              
1216 861         2235 my $has_todo = $test->has_todo;
1217              
1218 861         2505 $self->in_todo($has_todo);
1219 861 100       2030 if ( defined( my $tests_planned = $self->tests_planned ) ) {
1220 709 100       1504 if ( $tests_run > $tests_planned ) {
1221 50         149 $test->is_unplanned(1);
1222             }
1223             }
1224              
1225 861 100       1559 if ( defined $number ) {
1226 815 100       1687 if ( $number != $tests_run ) {
1227 82         160 my $count = $tests_run;
1228 82         445 $self->_add_error( "Tests out of sequence. Found "
1229             . "($number) but expected ($count)" );
1230             }
1231             }
1232             else {
1233 46         172 $test->_number( $number = $tests_run );
1234             }
1235              
1236 861 100       1487 push @{ $self->{todo} } => $number if $has_todo;
  57         138  
1237 861 100       2606 push @{ $self->{todo_passed} } => $number
  16         49  
1238             if $test->todo_passed;
1239 861 100       2077 push @{ $self->{skipped} } => $number
  23         67  
1240             if $test->has_skip;
1241              
1242 861 100       1081 push @{ $self->{ $test->is_ok ? 'passed' : 'failed' } } =>
  861         2215  
1243             $number;
1244             push @{
1245 861         901 $self->{
1246 861 100       2175 $test->is_actual_ok
1247             ? 'actual_passed'
1248             : 'actual_failed'
1249             }
1250             } => $number;
1251             },
1252             },
1253       10     yaml => { act => sub { }, },
1254 278         7177 );
1255              
1256             # Each state contains a hash the keys of which match a token type. For
1257             # each token
1258             # type there may be:
1259             # act A coderef to run
1260             # goto The new state to move to. Stay in this state if
1261             # missing
1262             # continue Goto the new state and run the new state for the
1263             # current token
1264             %states = (
1265             INIT => {
1266             version => {
1267             act => sub {
1268 25     25   35 my ($version) = @_;
1269 25         139 my $ver_num = $version->version;
1270 25 100       119 if ( $ver_num <= $DEFAULT_TAP_VERSION ) {
1271 3         14 my $ver_min = $DEFAULT_TAP_VERSION + 1;
1272 3         31 $self->_add_error(
1273             "Explicit TAP version must be at least "
1274             . "$ver_min. Got version $ver_num" );
1275 3         6 $ver_num = $DEFAULT_TAP_VERSION;
1276             }
1277 25 100       64 if ( $ver_num > $MAX_TAP_VERSION ) {
1278 1         4 $self->_add_error(
1279             "TAP specified version $ver_num but "
1280             . "we don't know about versions later "
1281             . "than $MAX_TAP_VERSION" );
1282 1         1 $ver_num = $MAX_TAP_VERSION;
1283             }
1284 25         97 $self->version($ver_num);
1285 25         53 $self->_grammar->set_version($ver_num);
1286             },
1287             goto => 'PLAN'
1288             },
1289             plan => { goto => 'PLANNED' },
1290             test => { goto => 'UNPLANNED' },
1291             },
1292             PLAN => {
1293             plan => { goto => 'PLANNED' },
1294             test => { goto => 'UNPLANNED' },
1295             },
1296             PLANNED => {
1297             test => { goto => 'PLANNED_AFTER_TEST' },
1298             plan => {
1299             act => sub {
1300 3     3   6 my ($version) = @_;
1301 3         10 $self->_add_error(
1302             'More than one plan found in TAP output');
1303             },
1304             },
1305             },
1306             PLANNED_AFTER_TEST => {
1307             test => { goto => 'PLANNED_AFTER_TEST' },
1308       3     plan => { act => sub { }, continue => 'PLANNED' },
1309             yaml => { goto => 'PLANNED' },
1310             },
1311             GOT_PLAN => {
1312             test => {
1313             act => sub {
1314 5     5   18 my ($plan) = @_;
1315 5         25 my $line = $self->plan;
1316 5         33 $self->_add_error(
1317             "Plan ($line) must be at the beginning "
1318             . "or end of the TAP output" );
1319 5         22 $self->is_good_plan(0);
1320             },
1321             continue => 'PLANNED'
1322             },
1323             plan => { continue => 'PLANNED' },
1324             },
1325             UNPLANNED => {
1326             test => { goto => 'UNPLANNED_AFTER_TEST' },
1327             plan => { goto => 'GOT_PLAN' },
1328             },
1329             UNPLANNED_AFTER_TEST => {
1330       76     test => { act => sub { }, continue => 'UNPLANNED' },
1331 278     30   17251 plan => { act => sub { }, continue => 'UNPLANNED' },
1332             yaml => { goto => 'UNPLANNED' },
1333             },
1334             );
1335              
1336             # Apply globals and defaults to state table
1337 278         1420 for my $name ( keys %states ) {
1338              
1339             # Merge with globals
1340 1946         2878 my $st = { %state_globals, %{ $states{$name} } };
  1946         7381  
1341              
1342             # Add defaults
1343 1946         2445 for my $next ( sort keys %{$st} ) {
  1946         8004  
1344 15568 100       22884 if ( my $default = $state_defaults{$next} ) {
1345 5838         3983 for my $def ( sort keys %{$default} ) {
  5838         8219  
1346 5838   66     16434 $st->{$next}->{$def} ||= $default->{$def};
1347             }
1348             }
1349             }
1350              
1351             # Stuff back in table
1352 1946         4763 $states{$name} = $st;
1353             }
1354              
1355 278         1212 return \%states;
1356             }
1357              
1358             =head3 C
1359              
1360             Get an a list of file handles which can be passed to C
1361             determine the readiness of this parser.
1362              
1363             =cut
1364              
1365 25     25 1 51 sub get_select_handles { shift->_iterator->get_select_handles }
1366              
1367             sub _grammar {
1368 576     576   807 my $self = shift;
1369 576 100       1577 return $self->{_grammar} = shift if @_;
1370              
1371 305   66     2066 return $self->{_grammar} ||= $self->make_grammar(
1372             { iterator => $self->_iterator,
1373             parser => $self,
1374             version => $self->version
1375             }
1376             );
1377             }
1378              
1379             sub _iter {
1380 278     278   554 my $self = shift;
1381 278         1057 my $iterator = $self->_iterator;
1382 278         936 my $grammar = $self->_grammar;
1383 278         1199 my $spool = $self->_spool;
1384 278         657 my $state = 'INIT';
1385 278         990 my $state_table = $self->_make_state_table;
1386              
1387 278         1703 $self->start_time( $self->get_time );
1388 278         1010 $self->start_times( $self->get_times );
1389              
1390             # Make next_state closure
1391             my $next_state = sub {
1392 1310     1310   1583 my $token = shift;
1393 1310         3737 my $type = $token->type;
1394             TRANS: {
1395 1310 100       1319 my $state_spec = $state_table->{$state}
  1424         3672  
1396             or die "Illegal state: $state";
1397              
1398 1423 50       2905 if ( my $next = $state_spec->{$type} ) {
1399 1423 100       3114 if ( my $act = $next->{act} ) {
1400 1305         2742 $act->($token);
1401             }
1402 1423 100       5123 if ( my $cont = $next->{continue} ) {
    100          
1403 114         137 $state = $cont;
1404 114         250 redo TRANS;
1405             }
1406             elsif ( my $goto = $next->{goto} ) {
1407 1151         1705 $state = $goto;
1408             }
1409             }
1410             else {
1411 0         0 confess("Unhandled token type: $type\n");
1412             }
1413             }
1414 1309         1624 return $token;
1415 278         1897 };
1416              
1417             # Handle end of stream - which means either pop a block or finish
1418             my $end_handler = sub {
1419 269     269   899 $self->exit( $iterator->exit );
1420 269         941 $self->wait( $iterator->wait );
1421 269         900 $self->_finish;
1422 268         395 return;
1423 278         1400 };
1424              
1425             # Finally make the closure that we return. For performance reasons
1426             # there are two versions of the returned function: one that handles
1427             # callbacks and one that does not.
1428 278 100       2754 if ( $self->_has_callbacks ) {
1429             return sub {
1430 340     340   405 my $result = eval { $grammar->tokenize };
  340         806  
1431 340 100       546 $self->_add_error($@) if $@;
1432              
1433 340 100       465 if ( defined $result ) {
1434 278         435 $result = $next_state->($result);
1435              
1436 278 100       541 if ( my $code = $self->_callback_for( $result->type ) ) {
1437 64         69 $_->($result) for @{$code};
  64         237  
1438             }
1439             else {
1440 214         388 $self->_make_callback( 'ELSE', $result );
1441             }
1442              
1443 278         540 $self->_make_callback( 'ALL', $result );
1444              
1445             # Echo TAP to spool file
1446 278 100       520 print {$spool} $result->raw, "\n" if $spool;
  12         19  
1447             }
1448             else {
1449 62         123 $result = $end_handler->();
1450 62 50       242 $self->_make_callback( 'EOF', $self )
1451             unless defined $result;
1452             }
1453              
1454 340         5392 return $result;
1455 62         556 };
1456             } # _has_callbacks
1457             else {
1458             return sub {
1459 1239     1239   1863 my $result = eval { $grammar->tokenize };
  1239         11486  
1460 1239 100       2340 $self->_add_error($@) if $@;
1461              
1462 1239 100       2398 if ( defined $result ) {
1463 1032         2338 $result = $next_state->($result);
1464              
1465             # Echo TAP to spool file
1466 1031 100       2053 print {$spool} $result->raw, "\n" if $spool;
  18         44  
1467             }
1468             else {
1469 207         457 $result = $end_handler->();
1470             }
1471              
1472 1237         20967 return $result;
1473 216         2442 };
1474             } # no callbacks
1475             }
1476              
1477             sub _finish {
1478 269     269   355 my $self = shift;
1479              
1480 269         1027 $self->end_time( $self->get_time );
1481 269         897 $self->end_times( $self->get_times );
1482              
1483             # Avoid leaks
1484 269         857 $self->_iterator(undef);
1485 269         647 $self->_grammar(undef);
1486              
1487             # If we just delete the iter we won't get a fault if it's recreated.
1488             # Instead we set it to a sub that returns an infinite
1489             # stream of undef. This segfaults on 5.5.4, presumably because
1490             # we're still executing the closure that gets replaced and it hasn't
1491             # been protected with a refcount.
1492 1     1   4 $self->{_iter} = sub {return}
1493 269 50       2177 if $] >= 5.006;
1494              
1495             # sanity checks
1496 269 100       858 if ( !$self->plan ) {
1497 23         94 $self->_add_error('No plan found in TAP output');
1498             }
1499             else {
1500 246 100       728 $self->is_good_plan(1) unless defined $self->is_good_plan;
1501             }
1502 269 100 100     844 if ( $self->tests_run != ( $self->tests_planned || 0 ) ) {
1503 24         85 $self->is_good_plan(0);
1504 24 100       72 if ( defined( my $planned = $self->tests_planned ) ) {
1505 18         76 my $ran = $self->tests_run;
1506 18         209 $self->_add_error(
1507             "Bad plan. You planned $planned tests but ran $ran.");
1508             }
1509             }
1510 269 100       759 if ( $self->tests_run != ( $self->passed + $self->failed ) ) {
1511              
1512             # this should never happen
1513 1         7 my $actual = $self->tests_run;
1514 1         3 my $passed = $self->passed;
1515 1         2 my $failed = $self->failed;
1516 1         7 $self->_croak( "Panic: planned test count ($actual) did not equal "
1517             . "sum of passed ($passed) and failed ($failed) tests!" );
1518             }
1519              
1520 268 100       845 $self->is_good_plan(0) unless defined $self->is_good_plan;
1521              
1522 268 100       2227 unless ( $self->parse_errors ) {
1523             # Optimise storage where possible
1524 211 100       458 if ( $self->tests_run == @{$self->{passed}} ) {
  211         649  
1525 165         363 $self->{passed} = $self->tests_run;
1526             }
1527 211 100       656 if ( $self->tests_run == @{$self->{actual_passed}} ) {
  211         583  
1528 151         317 $self->{actual_passed} = $self->tests_run;
1529             }
1530             }
1531              
1532 268         561 return $self;
1533             }
1534              
1535             =head3 C
1536              
1537             Delete and return the spool.
1538              
1539             my $fh = $parser->delete_spool;
1540              
1541             =cut
1542              
1543             sub delete_spool {
1544 106     106 1 130 my $self = shift;
1545              
1546 106         368 return delete $self->{_spool};
1547             }
1548              
1549             ##############################################################################
1550              
1551             =head1 CALLBACKS
1552              
1553             As mentioned earlier, a "callback" key may be added to the
1554             C constructor. If present, each callback corresponding to a
1555             given result type will be called with the result as the argument if the
1556             C method is used. The callback is expected to be a subroutine
1557             reference (or anonymous subroutine) which is invoked with the parser
1558             result as its argument.
1559              
1560             my %callbacks = (
1561             test => \&test_callback,
1562             plan => \&plan_callback,
1563             comment => \&comment_callback,
1564             bailout => \&bailout_callback,
1565             unknown => \&unknown_callback,
1566             );
1567              
1568             my $aggregator = TAP::Parser::Aggregator->new;
1569             for my $file ( @test_files ) {
1570             my $parser = TAP::Parser->new(
1571             {
1572             source => $file,
1573             callbacks => \%callbacks,
1574             }
1575             );
1576             $parser->run;
1577             $aggregator->add( $file, $parser );
1578             }
1579              
1580             Callbacks may also be added like this:
1581              
1582             $parser->callback( test => \&test_callback );
1583             $parser->callback( plan => \&plan_callback );
1584              
1585             The following keys allowed for callbacks. These keys are case-sensitive.
1586              
1587             =over 4
1588              
1589             =item * C
1590              
1591             Invoked if C<< $result->is_test >> returns true.
1592              
1593             =item * C
1594              
1595             Invoked if C<< $result->is_version >> returns true.
1596              
1597             =item * C
1598              
1599             Invoked if C<< $result->is_plan >> returns true.
1600              
1601             =item * C
1602              
1603             Invoked if C<< $result->is_comment >> returns true.
1604              
1605             =item * C
1606              
1607             Invoked if C<< $result->is_unknown >> returns true.
1608              
1609             =item * C
1610              
1611             Invoked if C<< $result->is_yaml >> returns true.
1612              
1613             =item * C
1614              
1615             Invoked if C<< $result->is_unknown >> returns true.
1616              
1617             =item * C
1618              
1619             If a result does not have a callback defined for it, this callback will
1620             be invoked. Thus, if all of the previous result types are specified as
1621             callbacks, this callback will I be invoked.
1622              
1623             =item * C
1624              
1625             This callback will always be invoked and this will happen for each
1626             result after one of the above callbacks is invoked. For example, if
1627             L is loaded, you could use the following to color your
1628             test output:
1629              
1630             my %callbacks = (
1631             test => sub {
1632             my $test = shift;
1633             if ( $test->is_ok && not $test->directive ) {
1634             # normal passing test
1635             print color 'green';
1636             }
1637             elsif ( !$test->is_ok ) { # even if it's TODO
1638             print color 'white on_red';
1639             }
1640             elsif ( $test->has_skip ) {
1641             print color 'white on_blue';
1642              
1643             }
1644             elsif ( $test->has_todo ) {
1645             print color 'white';
1646             }
1647             },
1648             ELSE => sub {
1649             # plan, comment, and so on (anything which isn't a test line)
1650             print color 'black on_white';
1651             },
1652             ALL => sub {
1653             # now print them
1654             print shift->as_string;
1655             print color 'reset';
1656             print "\n";
1657             },
1658             );
1659              
1660             =item * C
1661              
1662             Invoked when there are no more lines to be parsed. Since there is no
1663             accompanying L object the C object is
1664             passed instead.
1665              
1666             =back
1667              
1668             =head1 TAP GRAMMAR
1669              
1670             If you're looking for an EBNF grammar, see L.
1671              
1672             =head1 BACKWARDS COMPATIBILITY
1673              
1674             The Perl-QA list attempted to ensure backwards compatibility with
1675             L. However, there are some minor differences.
1676              
1677             =head2 Differences
1678              
1679             =over 4
1680              
1681             =item * TODO plans
1682              
1683             A little-known feature of L is that it supported TODO
1684             lists in the plan:
1685              
1686             1..2 todo 2
1687             ok 1 - We have liftoff
1688             not ok 2 - Anti-gravity device activated
1689              
1690             Under L, test number 2 would I because it was
1691             listed as a TODO test on the plan line. However, we are not aware of
1692             anyone actually using this feature and hard-coding test numbers is
1693             discouraged because it's very easy to add a test and break the test
1694             number sequence. This makes test suites very fragile. Instead, the
1695             following should be used:
1696              
1697             1..2
1698             ok 1 - We have liftoff
1699             not ok 2 - Anti-gravity device activated # TODO
1700              
1701             =item * 'Missing' tests
1702              
1703             It rarely happens, but sometimes a harness might encounter
1704             'missing tests:
1705              
1706             ok 1
1707             ok 2
1708             ok 15
1709             ok 16
1710             ok 17
1711              
1712             L would report tests 3-14 as having failed. For the
1713             C, these tests are not considered failed because they've
1714             never run. They're reported as parse failures (tests out of sequence).
1715              
1716             =back
1717              
1718             =head1 SUBCLASSING
1719              
1720             If you find you need to provide custom functionality (as you would have using
1721             L), you're in luck: C and friends are
1722             designed to be easily plugged-into and/or subclassed.
1723              
1724             Before you start, it's important to know a few things:
1725              
1726             =over 2
1727              
1728             =item 1
1729              
1730             All C objects inherit from L.
1731              
1732             =item 2
1733              
1734             Many C classes have a I section to guide you.
1735              
1736             =item 3
1737              
1738             Note that C is designed to be the central "maker" - ie: it is
1739             responsible for creating most new objects in the C namespace.
1740              
1741             This makes it possible for you to have a single point of configuring what
1742             subclasses should be used, which means that in many cases you'll find
1743             you only need to sub-class one of the parser's components.
1744              
1745             The exception to this rule are I & I, but those are
1746             both created with customizable I.
1747              
1748             =item 4
1749              
1750             By subclassing, you may end up overriding undocumented methods. That's not
1751             a bad thing per se, but be forewarned that undocumented methods may change
1752             without warning from one release to the next - we cannot guarantee backwards
1753             compatibility. If any I method needs changing, it will be
1754             deprecated first, and changed in a later release.
1755              
1756             =back
1757              
1758             =head2 Parser Components
1759              
1760             =head3 Sources
1761              
1762             A TAP parser consumes input from a single I of TAP, which could come
1763             from anywhere (a file, an executable, a database, an IO handle, a URI, etc..).
1764             The source gets bundled up in a L object which gathers some
1765             meta data about it. The parser then uses a L to
1766             determine which L to use to turn the raw source
1767             into a stream of TAP by way of L.
1768              
1769             If you simply want C to handle a new source of TAP you probably
1770             don't need to subclass C itself. Rather, you'll need to create a
1771             new L class, and just plug it into the parser using
1772             the I param to L. Before you start writing one, read through
1773             L to get a feel for how the system works first.
1774              
1775             If you find you really need to use your own iterator factory you can still do
1776             so without sub-classing C by setting L.
1777              
1778             If you just need to customize the objects on creation, subclass L
1779             and override L.
1780              
1781             Note that C & C have been I and
1782             are now removed.
1783              
1784             =head3 Iterators
1785              
1786             A TAP parser uses I to loop through the I of TAP read in
1787             from the I it was given. There are a few types of Iterators available
1788             by default, all sub-classes of L. Choosing which
1789             iterator to use is the responsibility of the I, though it
1790             simply delegates to the I it uses.
1791              
1792             If you're writing your own L, you may need to
1793             create your own iterators too. If so you'll need to subclass
1794             L.
1795              
1796             Note that L has been I and is now removed.
1797              
1798             =head3 Results
1799              
1800             A TAP parser creates Ls as it iterates through the
1801             input I. There are quite a few result types available; choosing
1802             which class to use is the responsibility of the I.
1803              
1804             To create your own result types you have two options:
1805              
1806             =over 2
1807              
1808             =item option 1
1809              
1810             Subclass L and register your new result type/class with
1811             the default L.
1812              
1813             =item option 2
1814              
1815             Subclass L itself and implement your own
1816             L creation logic. Then you'll need to customize the
1817             class used by your parser by setting the C parameter.
1818             See L for more details.
1819              
1820             =back
1821              
1822             If you need to customize the objects on creation, subclass L and
1823             override L.
1824              
1825             =head3 Grammar
1826              
1827             L is the heart of the parser. It tokenizes the TAP
1828             input I and produces results. If you need to customize its behaviour
1829             you should probably familiarize yourself with the source first. Enough
1830             lecturing.
1831              
1832             Subclass L and customize your parser by setting the
1833             C parameter. See L for more details.
1834              
1835             If you need to customize the objects on creation, subclass L and
1836             override L
1837              
1838             =head1 ACKNOWLEDGMENTS
1839              
1840             All of the following have helped. Bug reports, patches, (im)moral
1841             support, or just words of encouragement have all been forthcoming.
1842              
1843             =over 4
1844              
1845             =item * Michael Schwern
1846              
1847             =item * Andy Lester
1848              
1849             =item * chromatic
1850              
1851             =item * GEOFFR
1852              
1853             =item * Shlomi Fish
1854              
1855             =item * Torsten Schoenfeld
1856              
1857             =item * Jerry Gay
1858              
1859             =item * Aristotle
1860              
1861             =item * Adam Kennedy
1862              
1863             =item * Yves Orton
1864              
1865             =item * Adrian Howard
1866              
1867             =item * Sean & Lil
1868              
1869             =item * Andreas J. Koenig
1870              
1871             =item * Florian Ragwitz
1872              
1873             =item * Corion
1874              
1875             =item * Mark Stosberg
1876              
1877             =item * Matt Kraai
1878              
1879             =item * David Wheeler
1880              
1881             =item * Alex Vandiver
1882              
1883             =item * Cosimo Streppone
1884              
1885             =item * Ville Skyttä
1886              
1887             =back
1888              
1889             =head1 AUTHORS
1890              
1891             Curtis "Ovid" Poe
1892              
1893             Andy Armstong
1894              
1895             Eric Wilhelm @
1896              
1897             Michael Peters
1898              
1899             Leif Eriksen
1900              
1901             Steve Purkis
1902              
1903             Nicholas Clark
1904              
1905             Lee Johnson
1906              
1907             Philippe Bruhat
1908              
1909             =head1 BUGS
1910              
1911             Please report any bugs or feature requests to
1912             C, or through the web interface at
1913             L.
1914             We will be notified, and then you'll automatically be notified of
1915             progress on your bug as we make changes.
1916              
1917             Obviously, bugs which include patches are best. If you prefer, you can
1918             patch against bleed by via anonymous checkout of the latest version:
1919              
1920             git clone git://github.com/Perl-Toolchain-Gang/Test-Harness.git
1921              
1922             =head1 COPYRIGHT & LICENSE
1923              
1924             Copyright 2006-2008 Curtis "Ovid" Poe, all rights reserved.
1925              
1926             This program is free software; you can redistribute it and/or modify it
1927             under the same terms as Perl itself.
1928              
1929             =cut
1930              
1931             1;