NAME
TAP::DOM - TAP as Document Object Model.
SYNOPSIS
# Create a DOM from TAP
use TAP::DOM;
my $tapdom = TAP::DOM->new( tap => $tap ); # same options as TAP::Parser
print Dumper($tapdom);
# Recreate TAP from DOM
my $tap2 = $tapdom->to_tap;DESCRIPTION
The purpose of this module is
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.
METHODS
new
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:
tap => $some_tap_stringor
source => $test_fileBut there are more, see TAP::Parser.
to_tap
Called on a TAP::DOM object it returns a string that is TAP.
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( {
# 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') # 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.
HOW TO STRIP DETAILS
You can make the DOM a bit more terse (i.e., less blown up) if you do not need every detail.
Strip unneccessary TAP-DOM fields
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
rawUse it like this:
$tapdom = TAP::DOM->new (tap => $tap,
ignore => [ qw( raw as_string ) ],
);Strip unneccessary lines
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.
USING BITSETS
Option "usebitsets"
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.
Access bitset attributes via methods
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) {...}
...Access bitset attributes via bit comparisons
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 ) {...}ACCESSORS
end_time
exit
has_problems
is_good_plan
parse_errors
plan
pragmas
skip_all
start_time
summary
tapdom_config
document_data
A document can contain comment lines which actually contain key/value data, like this:
# Test-vendor-id: GenuineIntel
# Test-cpu-model: Intel(R) Core(TM) i7-3667U CPU @ 2.00GHz
# Test-cpu-family: 6
# Test-flags.fpu: 1Those lines are converted into a hash by splitting it at the : delimiter and stripping the # Test- prefix. The resulting data structure looks like this:
# ... inside TAP::DOM ...
document_data => {
'vendor-id' => 'GenuineIntel',
'cpu-model' => #Intel(R) Core(TM) i7-3667U CPU @ 2.00GHz',
'cpu-family' => 6,
'flags.fpu' => 1,
},tests_planned
tests_run
version
AUTHOR
Steffen Schwigon <ss5@renormalist.net>
COPYRIGHT AND LICENSE
This software is copyright (c) 2017 by Steffen Schwigon.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.