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