tap::parser.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

Returns a boolean value indicating whether or not the number of tests planned
matches the number of tests run.
.PP
\&\fBNote:\fR  this was formerly \f(CW\*(C`good_plan\*(C'\fR.  The latter method is deprecated and
will issue a warning.
.PP
And since we're on that subject ...
.PP
\fI\f(CI\*(C`tests_planned\*(C'\fI\fR
.IX Subsection "tests_planned"
.PP
.Vb 1
\&  print $parser\->tests_planned;
.Ve
.PP
Returns the number of tests planned, according to the plan.  For example, a
plan of '1..17' will mean that 17 tests were planned.
.PP
\fI\f(CI\*(C`tests_run\*(C'\fI\fR
.IX Subsection "tests_run"
.PP
.Vb 1
\&  print $parser\->tests_run;
.Ve
.PP
Returns the number of tests which actually were run.  Hopefully this will
match the number of \f(CW\*(C`$parser\->tests_planned\*(C'\fR.
.PP
\fI\f(CI\*(C`skip_all\*(C'\fI\fR
.IX Subsection "skip_all"
.PP
Returns a true value (actually the reason for skipping) if all tests
were skipped.
.PP
\fI\f(CI\*(C`start_time\*(C'\fI\fR
.IX Subsection "start_time"
.PP
Returns the time when the Parser was created.
.PP
\fI\f(CI\*(C`end_time\*(C'\fI\fR
.IX Subsection "end_time"
.PP
Returns the time when the end of \s-1TAP\s0 input was seen.
.PP
\fI\f(CI\*(C`has_problems\*(C'\fI\fR
.IX Subsection "has_problems"
.PP
.Vb 3
\&  if ( $parser\->has_problems ) {
\&      ...
\&  }
.Ve
.PP
This is a 'catch\-all' method which returns true if any tests have currently
failed, any \s-1TODO\s0 tests unexpectedly succeeded, or any parse errors occurred.
.PP
\fI\f(CI\*(C`version\*(C'\fI\fR
.IX Subsection "version"
.PP
.Vb 1
\&  $parser\->version;
.Ve
.PP
Once the parser is done, this will return the version number for the
parsed \s-1TAP\s0. Version numbers were introduced with \s-1TAP\s0 version 13 so if no
version number is found version 12 is assumed.
.PP
\fI\f(CI\*(C`exit\*(C'\fI\fR
.IX Subsection "exit"
.PP
.Vb 1
\&  $parser\->exit;
.Ve
.PP
Once the parser is done, this will return the exit status.  If the parser ran
an executable, it returns the exit status of the executable.
.PP
\fI\f(CI\*(C`wait\*(C'\fI\fR
.IX Subsection "wait"
.PP
.Vb 1
\&  $parser\->wait;
.Ve
.PP
Once the parser is done, this will return the wait status.  If the parser ran
an executable, it returns the wait status of the executable.  Otherwise, this
mererely returns the \f(CW\*(C`exit\*(C'\fR status.
.PP
\fI\f(CI\*(C`parse_errors\*(C'\fI\fR
.IX Subsection "parse_errors"
.PP
.Vb 2
\& my @errors = $parser\->parse_errors; # the parser errors
\& my $errors = $parser\->parse_errors; # the number of parser_errors
.Ve
.PP
Fortunately, all \s-1TAP\s0 output is perfect.  In the event that it is not, this
method will return parser errors.  Note that a junk line which the parser does
not recognize is \f(CW\*(C`not\*(C'\fR an error.  This allows this parser to handle future
versions of \s-1TAP\s0.  The following are all \s-1TAP\s0 errors reported by the parser:
.IP "\(bu" 4
Misplaced plan
.Sp
The plan (for example, '1..5'), must only come at the beginning or end of the
\&\s-1TAP\s0 output.
.IP "\(bu" 4
No plan
.Sp
Gotta have a plan!
.IP "\(bu" 4
More than one plan
.Sp
.Vb 5
\& 1..3
\& ok 1 \- input file opened
\& not ok 2 \- first line of the input valid # todo some data
\& ok 3 read the rest of the file
\& 1..3
.Ve
.Sp
Right.  Very funny.  Don't do that.
.IP "\(bu" 4
Test numbers out of sequence
.Sp
.Vb 4
\& 1..3
\& ok 1 \- input file opened
\& not ok 2 \- first line of the input valid # todo some data
\& ok 2 read the rest of the file
.Ve
.Sp
That last test line above should have the number '3' instead of '2'.
.Sp
Note that it's perfectly acceptable for some lines to have test numbers and
others to not have them.  However, when a test number is found, it must be in
sequence.  The following is also an error:
.Sp
.Vb 4
\& 1..3
\& ok 1 \- input file opened
\& not ok \- first line of the input valid # todo some data
\& ok 2 read the rest of the file
.Ve
.Sp
But this is not:
.Sp
.Vb 4
\& 1..3
\& ok  \- input file opened
\& not ok \- first line of the input valid # todo some data
\& ok 3 read the rest of the file
.Ve
.PP
\fI\f(CI\*(C`get_select_handles\*(C'\fI\fR
.IX Subsection "get_select_handles"
.PP
Get an a list of file handles which can be passed to \f(CW\*(C`select\*(C'\fR to
determine the readiness of this parser.
.PP
\fI\f(CI\*(C`delete_spool\*(C'\fI\fR
.IX Subsection "delete_spool"
.PP
Delete and return the spool.
.PP
.Vb 1
\&  my $fh = $parser\->delete_spool;
.Ve
.SH "CALLBACKS"
.IX Header "CALLBACKS"
As mentioned earlier, a \*(L"callback\*(R" key may be added to the
\&\f(CW\*(C`TAP::Parser\*(C'\fR constructor. If present, each callback corresponding to a
given result type will be called with the result as the argument if the
\&\f(CW\*(C`run\*(C'\fR method is used. The callback is expected to be a subroutine
reference (or anonymous subroutine) which is invoked with the parser
result as its argument.
.PP
.Vb 7
\& my %callbacks = (
\&     test    => \e&test_callback,
\&     plan    => \e&plan_callback,
\&     comment => \e&comment_callback,
\&     bailout => \e&bailout_callback,
\&     unknown => \e&unknown_callback,
\& );
\&
\& my $aggregator = TAP::Parser::Aggregator\->new;
\& foreach my $file ( @test_files ) {
\&     my $parser = TAP::Parser\->new(
\&         {
\&             source    => $file,
\&             callbacks => \e%callbacks,
\&         }
\&     );
\&     $parser\->run;
\&     $aggregator\->add( $file, $parser );
\& }
.Ve
.PP
Callbacks may also be added like this:
.PP
.Vb 2
\& $parser\->callback( test => \e&test_callback );
\& $parser\->callback( plan => \e&plan_callback );
.Ve
.PP
The following keys allowed for callbacks. These keys are case-sensitive.
.IP "\(bu" 4
\&\f(CW\*(C`test\*(C'\fR
.Sp
Invoked if \f(CW\*(C`$result\->is_test\*(C'\fR returns true.
.IP "\(bu" 4
\&\f(CW\*(C`version\*(C'\fR
.Sp
Invoked if \f(CW\*(C`$result\->is_version\*(C'\fR returns true.
.IP "\(bu" 4
\&\f(CW\*(C`plan\*(C'\fR
.Sp
Invoked if \f(CW\*(C`$result\->is_plan\*(C'\fR returns true.
.IP "\(bu" 4
\&\f(CW\*(C`comment\*(C'\fR
.Sp
Invoked if \f(CW\*(C`$result\->is_comment\*(C'\fR returns true.
.IP "\(bu" 4
\&\f(CW\*(C`bailout\*(C'\fR
.Sp
Invoked if \f(CW\*(C`$result\->is_unknown\*(C'\fR returns true.
.IP "\(bu" 4
\&\f(CW\*(C`yaml\*(C'\fR
.Sp
Invoked if \f(CW\*(C`$result\->is_yaml\*(C'\fR returns true.
.IP "\(bu" 4
\&\f(CW\*(C`unknown\*(C'\fR
.Sp
Invoked if \f(CW\*(C`$result\->is_unknown\*(C'\fR returns true.
.IP "\(bu" 4
\&\f(CW\*(C`ELSE\*(C'\fR
.Sp
If a result does not have a callback defined for it, this callback will
be invoked. Thus, if all of the previous result types are specified as
callbacks, this callback will \fInever\fR be invoked.
.IP "\(bu" 4
\&\f(CW\*(C`ALL\*(C'\fR
.Sp
This callback will always be invoked and this will happen for each
result after one of the above callbacks is invoked.  For example, if
Term::ANSIColor is loaded, you could use the following to color your
test output:
.Sp
.Vb 12
\& my %callbacks = (
\&     test => sub {
\&         my $test = shift;
\&         if ( $test\->is_ok && not $test\->directive ) {
\&             # normal passing test
\&             print color \*(Aqgreen\*(Aq;
\&         }
\&         elsif ( !$test\->is_ok ) {    # even if it\*(Aqs TODO
\&             print color \*(Aqwhite on_red\*(Aq;
\&         }
\&         elsif ( $test\->has_skip ) {
\&             print color \*(Aqwhite on_blue\*(Aq;
\&
\&         }
\&         elsif ( $test\->has_todo ) {
\&             print color \*(Aqwhite\*(Aq;
\&         }
\&     },
\&     ELSE => sub {
\&         # plan, comment, and so on (anything which isn\*(Aqt a test line)
\&         print color \*(Aqblack on_white\*(Aq;
\&     },
\&     ALL => sub {
\&         # now print them
\&         print shift\->as_string;
\&         print color \*(Aqreset\*(Aq;
\&         print "\en";
\&     },
\& );
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`EOF\*(C'\fR
.Sp
Invoked when there are no more lines to be parsed. Since there is no
accompanying TAP::Parser::Result object the \f(CW\*(C`TAP::Parser\*(C'\fR object is
passed instead.
.SH "TAP GRAMMAR"
.IX Header "TAP GRAMMAR"
If you're looking for an \s-1EBNF\s0 grammar, see TAP::Parser::Grammar.
.SH "BACKWARDS COMPATABILITY"
.IX Header "BACKWARDS COMPATABILITY"
The Perl-QA list attempted to ensure backwards compatability with
Test::Harness.  However, there are some minor differences.
.Sh "Differences"
.IX Subsection "Differences"
.IP "\(bu" 4
\&\s-1TODO\s0 plans
.Sp
A little-known feature of Test::Harness is that it supported \s-1TODO\s0
lists in the plan:
.Sp
.Vb 3
\& 1..2 todo 2
\& ok 1 \- We have liftoff
\& not ok 2 \- Anti\-gravity device activated
.Ve
.Sp
Under Test::Harness, test number 2 would \fIpass\fR because it was
listed as a \s-1TODO\s0 test on the plan line. However, we are not aware of
anyone actually using this feature and hard-coding test numbers is
discouraged because it's very easy to add a test and break the test
number sequence. This makes test suites very fragile. Instead, the
following should be used:
.Sp
.Vb 3
\& 1..2
\& ok 1 \- We have liftoff
\& not ok 2 \- Anti\-gravity device activated # TODO
.Ve
.IP "\(bu" 4
\&'Missing' tests
.Sp
It rarely happens, but sometimes a harness might encounter
\&'missing tests:
.Sp
.Vb 5
\& ok 1
\& ok 2
\& ok 15
\& ok 16
\& ok 17
.Ve
.Sp
Test::Harness would report tests 3\-14 as having failed. For the
\&\f(CW\*(C`TAP::Parser\*(C'\fR, these tests are not considered failed because they've
never run. They're reported as parse failures (tests out of sequence).
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
All of the following have helped. Bug reports, patches, (im)moral
support, or just words of encouragement have all been forthcoming.
.IP "\(bu" 4
Michael Schwern
.IP "\(bu" 4
Andy Lester
.IP "\(bu" 4
chromatic
.IP "\(bu" 4
\&\s-1GEOFFR\s0
.IP "\(bu" 4
Shlomi Fish
.IP "\(bu" 4
Torsten Schoenfeld
.IP "\(bu" 4
Jerry Gay
.IP "\(bu" 4
Aristotle
.IP "\(bu" 4
Adam Kennedy
.IP "\(bu" 4
Yves Orton
.IP "\(bu" 4
Adrian Howard
.IP "\(bu" 4
Sean & Lil
.IP "\(bu" 4
Andreas J. Koenig
.IP "\(bu" 4
Florian Ragwitz
.IP "\(bu" 4
Corion
.IP "\(bu" 4
Mark Stosberg
.IP "\(bu" 4
Matt Kraai
.SH "AUTHORS"
.IX Header "AUTHORS"
Curtis \*(L"Ovid\*(R" Poe <[e-mail]>
.PP
Andy Armstong <[e-mail]>
.PP
Eric Wilhelm @ <ewilhelm at cpan dot org>
.PP
Michael Peters <mpeters at plusthree dot com>
.PP
Leif Eriksen <leif dot eriksen at bigpond dot com>
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-tapx\[e-mail]\*(C'\fR, or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=TAP\-Parser>.
We will be notified, and then you'll automatically be notified of
progress on your bug as we make changes.
.PP
Obviously, bugs which include patches are best. If you prefer, you can
patch against bleed by via anonymous checkout of the latest version:
.PP
.Vb 1
\& svn checkout http://svn.hexten.net/tapx
.Ve
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2006\-2008 Curtis \*(L"Ovid\*(R" Poe, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.