NAME
TAP::DOM - TAP as document data structure.
SYNOPSIS
use TAP::DOM;
my $tapdata = new TAP::DOM( tap => $tap ); # same options as TAP::Parser
print Dumper($tapdata);DESCRIPTION
The purpose of this module is A) to define a reliable data structure and B) to help create this structure from TAP.
That's 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.
FUNCTIONS
new
Constructor which immediately triggers parsing the TAP via TAP::Parser and returns a big data structure containing the extracted results.
Parameters are passed through to TAP::Parser, usually one of these:
tap => $some_tap_stringor
source => $test_fileBut there are more, see TAP::Parser.
STRUCTURE
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.
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( {
'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',
# for the meaning of this summary see also 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)',
},
'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') # blessedNESTED LINES
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.
With this you can recognize where the diagnostic lines semantically belong.
AUTHOR
Steffen Schwigon, <schwigon at cpan.org>
BUGS
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.
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.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc TAP::DOMYou can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
REPOSITORY
The public repository is hosted on github:
git clone git://github.com/renormalist/tap-dom.gitCOPYRIGHT & LICENSE
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.