TAP::DOM - TAP as document data structure.
use TAP::DOM; my $tapdata = TAP::DOM->new( tap => $tap ); # same options as TAP::Parser print Dumper($tapdata);
The purpose of this module is A) to define a reliable data structure and B) to help create this structure from TAP.
That is useful when you want to analyze the TAP in detail with "data exploration tools", like Data::DPath.
``Reliable'' means that this structure is kind of an API that will not change, so your data tools can, well, rely on it.
Constructor which immediately triggers parsing the TAP via TAP::Parser and returns a big data structure containing the extracted results.
All parameters are passed through to TAP::Parser, except ignore, ignorelines and usebitsets, see sections "HOW TO STRIP DETAILS" and "USING BITSETS". Usually the options are just one of those:
ignore
ignorelines
usebitsets
tap => $some_tap_string
or
source => $test_file
But there are more, see TAP::Parser.
The data structure is basically a nested hash/array structure with keys named after the functions of TAP::Parser that you normally would use to extract results.
See the TAP example file in t/some_tap.txt and its corresponding result structure in t/some_tap.dom.
t/some_tap.txt
t/some_tap.dom
Here is a slightly commented and beautified excerpt of t/some_tap.dom. Due to it's beeing manually washed for readability there might be errors in it, so for final reference, dump a DOM by yourself.
bless( { # general TAP stats: 'version' => 13, 'plan' => '1..6', 'tests_planned' => 6 'tests_run' => 8, 'is_good_plan' => 0, 'has_problems' => 2, 'skip_all' => undef, 'parse_errors' => [ 'Bad plan. You planned 6 tests but ran 8.' ], 'pragmas' => [ 'strict' ], 'exit' => 0, 'start_time' => '1236463400.25151', 'end_time' => '1236463400.25468', # the used TAP::DOM specific options to TAP::DOM->new(): 'tapdom_config' => { 'ignorelines' => qr/(?-xism:^## )/, 'usebitsets' => undef, 'ignore' => {} }, # summary according to TAP::Parser::Aggregator: 'summary' => { 'status' => 'FAIL', 'total' => 8, 'passed' => 6, 'failed' => 2, 'all_passed' => 0, 'skipped' => 1, 'todo' => 4, 'todo_passed' => 2, 'parse_errors' => 1, 'has_errors' => 1, 'has_problems' => 1, 'exit' => 0, 'wait' => 0 'elapsed' => bless( [ 0, '0', 0, 0, 0, 0 ], 'Benchmark' ), 'elapsed_timestr' => ' 0 wallclock secs ( 0.00 usr + 0.00 sys = 0.00 CPU)', }, # all recognized TAP lines: 'lines' => [ { 'is_actual_ok' => 0, 'is_bailout' => 0, 'is_comment' => 0, 'is_plan' => 0, 'is_pragma' => 0, 'is_test' => 0, 'is_unknown' => 0, 'is_version' => 1, # <--- 'is_yaml' => 0, 'has_skip' => 0, 'has_todo' => 0, 'raw' => 'TAP version 13' 'as_string' => 'TAP version 13', }, { 'is_actual_ok' => 0, 'is_bailout' => 0, 'is_comment' => 0, 'is_plan' => 1, # <--- 'is_pragma' => 0, 'is_test' => 0, 'is_unknown' => 0, 'is_version' => 0, 'is_yaml' => 0, 'has_skip' => 0, 'has_todo' => 0, 'raw' => '1..6' 'as_string' => '1..6', }, { 'is_actual_ok' => 0, 'is_bailout' => 0, 'is_comment' => 0, 'is_ok' => 1, # <--- 'is_plan' => 0, 'is_pragma' => 0, 'is_test' => 1, # <--- 'is_unknown' => 0, 'is_unplanned' => 0, 'is_version' => 0, 'is_yaml' => 0, 'has_skip' => 0, 'has_todo' => 0, 'number' => '1', # <--- 'type' => 'test', 'raw' => 'ok 1 - use Data::DPath;' 'as_string' => 'ok 1 - use Data::DPath;', 'description' => '- use Data::DPath;', 'directive' => '', 'explanation' => '', '_children' => [ # ----- children are the subsequent comment/yaml lines ----- { 'is_actual_ok' => 0, 'is_unknown' => 0, 'has_todo' => 0, 'is_bailout' => 0, 'is_pragma' => 0, 'is_version' => 0, 'is_comment' => 0, 'has_skip' => 0, 'is_test' => 0, 'is_yaml' => 1, # <--- 'is_plan' => 0, 'raw' => ' --- - name: \'Hash one\' value: 1 - name: \'Hash two\' value: 2 ...' 'as_string' => ' --- - name: \'Hash one\' value: 1 - name: \'Hash two\' value: 2 ...', 'data' => [ { 'value' => '1', 'name' => 'Hash one' }, { 'value' => '2', 'name' => 'Hash two' } ], } ], }, { 'is_actual_ok' => 0, 'is_bailout' => 0, 'is_comment' => 0, 'is_ok' => 1, # <--- 'is_plan' => 0, 'is_pragma' => 0, 'is_test' => 1, # <--- 'is_unknown' => 0, 'is_unplanned' => 0, 'is_version' => 0, 'is_yaml' => 0, 'has_skip' => 0, 'has_todo' => 0, 'explanation' => '', 'number' => '2', # <--- 'type' => 'test', 'description' => '- KEYs + PARENT', 'directive' => '', 'raw' => 'ok 2 - KEYs + PARENT' 'as_string' => 'ok 2 - KEYs + PARENT', }, # etc., see the rest in t/some_tap.dom ... ], }, 'TAP::DOM') # blessed
As you can see above, diagnostic lines (comment or yaml) are nested into the line before under a key _children which simply contains an array of those comment/yaml line elements.
_children
With this you can recognize where the diagnostic lines semantically belong.
You can make the DOM a bit more terse (i.e., less blown up) if you do not need every detail.
For this provide the ignore option to new(). It is an array ref specifying keys that should not be contained in the TAP-DOM. Currently supported are:
has_todo has_skip directive as_string explanation description is_unplanned is_actual_ok is_bailout is_unknown is_version is_bailout is_comment is_pragma is_plan is_test is_yaml is_ok number type raw
Use it like this:
$tapdom = TAP::DOM->new (tap => $tap, ignore => [ qw( raw as_string ) ], );
You can ignore complete lines from the input TAP as if they weren't existing. Of course you can break the TAP with this, so usually you only apply this to non-TAP lines or diagnostics you are not interested in.
My primary use-case is TAP with large parts of logfiles included with a prefixed "## " just for dual-using the TAP also as an archive of the log. When evaluating the TAP later I leave those log lines out because they only blow up the memory for the TAP-DOM:
$tapdom = TAP::DOM->new (tap => $tap, ignorelines => qr/^## /, );
See t/some_tap_ignore_lines.t for an example.
t/some_tap_ignore_lines.t
You can make the DOM even smaller by using the option usebitsets:
$tapdom = TAP::DOM->new (tap => $tap, usebitsets => 1 );
In this case all the 'has_*' and 'is_*' attributes are stored in a common bitset entry 'is_has' with their respective bits set.
This reduces the memory footprint of a TAP::DOM remarkably (for large TAP-DOMs ~40%) and is meant as an optimization option for memory constrained problems.
You can get the actual values of 'is_*' and 'has_*' attributes regardless of their storage as hash entries or bitsets by using the respective methods on single entries:
if ($tapdom->{lines}[4]->is_test) {...} if ($tapdom->{lines}[4]->is_ok) {...} ...
or with even less direct hash access
if ($tapdom->lines->[4]->is_test) {...} if ($tapdom->lines->[4]->is_ok) {...} ...
You can also use constants that represent the respective bits in expressions like this:
if ($tapdom->{lines}[4]{is_has} | $TAP::DOM::IS_TEST) {...}
And the constants can be imported into your namespace:
use TAP::DOM ':constants'; if ($tapdom->{lines}[4]{is_has} | $IS_TEST ) {...}
Steffen Schwigon, <schwigon at cpan.org>
<schwigon at cpan.org>
Currently I'm not yet sure whether the structure is already ``reliable'' and ``stable'' as is stated in the DESCRIPTION. I will probably call it version 1.0 once I'm fine with it.
1.0
Please report any bugs or feature requests to bug-tap-data at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=TAP-DOM. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-tap-data at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc TAP::DOM
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=TAP-DOM
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/TAP-DOM
CPAN Ratings
http://cpanratings.perl.org/d/TAP-DOM
Search CPAN
http://search.cpan.org/dist/TAP-DOM
The public repository is hosted on github:
git clone git://github.com/renormalist/tap-dom.git
Copyright 2009 Steffen Schwigon, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install TAP::DOM, copy and paste the appropriate command in to your terminal.
cpanm
cpanm TAP::DOM
CPAN shell
perl -MCPAN -e shell install TAP::DOM
For more information on module installation, please visit the detailed CPAN module installation guide.