CAB/Format.pm

filter: Statementstmt 17.8% 53 / 297 Branchbran 0.6% 1 / 162 Conditioncond 0.0% 0 / 56 MC/DCmcdc 0.0% 0 / 36 Subroutinesub 23.6% 17 / 72 Podpod 63.6% 35 / 55 totaltotal 15.6% 106 / 678 CC 107 SCAR 42.0
CC
107
Cov
10%
blockAppend
265.4
forceDocument
210.0
blockStore
110.0
CRAP 66.7
« CAB/Format/TEIws.pm ↑ Summary CAB/Format/Raw/Perl.pm »
1 ## -*- Mode: CPerl -*-
2 ##
3 ## File: DTA::CAB::Format.pm
4 ## Author: Bryan Jurish <moocow@cpan.org>
5 ## Description: Base class for datum I/O
6  
7 package DTA::CAB::Format;
8 1 ▶use DTA::CAB::Format::Registry; ##-- registry
Subroutine BEGIN: called CC=1 SCAR=0.0
9 1 ▶use DTA::CAB::Utils;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 1 ▶use DTA::CAB::Persistent;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 1 ▶use DTA::CAB::Logger;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 1 ▶use DTA::CAB::Datum;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 1 ▶use DTA::CAB::Token;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 1 ▶use DTA::CAB::Sentence;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 1 ▶use DTA::CAB::Document;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 1 ▶use IO::File;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 1 ▶use IO::Handle;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 1 ▶use File::Map qw();
Subroutine BEGIN: called CC=1 SCAR=0.0
19 1 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 ##==============================================================================
23 ## Globals
24 ##==============================================================================
25  
26 1 our @ISA = qw(DTA::CAB::Persistent DTA::CAB::Logger);
27  
28 ## $CLASS_DEFAULT
29 ## + default format class for newFormat()
30 1 our $CLASS_DEFAULT = 'DTA::CAB::Format::TT';
31  
32 ## $REG
33 ## + global format registry, a DTA::CAB::Format::Registry object
34 1 our ($REG);
35 1 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
36 1 $REG = DTA::CAB::Format::Registry->new();
37 }
38  
39 1 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
40 1 *isa = \&UNIVERSAL::isa;
41 1 *can = \&UNIVERSAL::can;
42 }
43  
44 1 our $LL_BLK_DEBUG = undef; ##-- log level for block debugging
45  
46 ##==============================================================================
47 ## Constructors etc.
48 ##==============================================================================
49  
50 ## $fmt = CLASS_OR_OBJ->new(%args)
51 ## + object structure: assumed HASH
52 ## {
53 ## ##-- DTA::CAB::IO: common
54 ## utf8 => $bool, ##-- use UTF-8 I/O, where applicable; default=1
55 ##
56 ## ##-- DTA::CAB::IO: input parsing
57 ## #(none)
58 ##
59 ## ##-- DTA::CAB::IO: output formatting
60 ## level => $formatLevel, ##-- formatting level, where applicable
61 ## outbuf => $stringBuffer, ##-- output buffer, where applicable
62 ## }
63 0 ▶sub new {
Subroutine new: not called CC=2 SCAR=17.9
Pod documented
64 0 my $that = shift;
65 0 ▶ my $fmt = bless({
Condition0%0/3
ref $that || $that
l!l&&r!l&&!r
000
MC/DC0%0/2
ref $that || $that
ref $that $that
Truth table0%0/3
A || B
A= ref $thatB= $that
ABresult
1X1
011
000
66 ##-- DTA::CAB::IO: common
67 utf8 => 1,
68  
69 ##-- DTA::CAB::IO: input parsing
70 #(none)
71  
72 ##-- DTA::CAB::IO: output formatting
73 #level => undef,
74 #outbuf => undef,
75  
76 ##-- user args
77 @_
78 }, ref($that)||$that);
79 0 return $fmt;
80 }
81  
82 ## undef = $fmt->DESTROY()
83 ## + destructor
84 ## + default implementation calls close()
85 0 ▶sub DESTROY {
Subroutine DESTROY: not called CC=1 SCAR=6.9
86 0 $_[0]->close();
87 }
88  
89 ## $fmt = CLASS->newFormat($class_or_short_or_class_suffix, %opts)
90 ## + wrapper for DTA::CAB::Format::Registry::newFormat(); accepts %opts qw(class file)
91 0 ▶sub newFormat {
Subroutine newFormat: not called CC=1 SCAR=6.9
Pod documented
92 0 my ($that,$class,%opts) = @_;
93 0 return $REG->newFormat($class,%opts);
94 }
95  
96 ## $fmt = CLASS->newReader(%opts)
97 ## + wraper for DTA::CAB::Format::Registry::newReader; accepts %opts qw(class file)
98 0 ▶sub newReader {
Subroutine newReader: not called CC=2 SCAR=17.9
Pod documented
99 0 my ($that,%opts) = @_;
100 0 ▶ return $REG->newReader(%opts) // $CLASS_DEFAULT->new(%opts);
Condition0%0/3
$DTA::CAB::Format::REG->newReader(%opts) // $DTA::CAB::Format::CLASS_DEFAULT->new(%opts)
l!l&&r!l&&!r
000
MC/DC0%0/2
$DTA::CAB::Format::REG->newReader(%opts) // $DTA::CAB::Format::CLASS_DEFAULT->new(%opts)
$DTA::CAB::Format::REG->newReader(%opts) $DTA::CAB::Format::CLASS_DEFAULT->new(%opts)
Truth table0%0/3
A // B
A= $DTA::CAB::Format::REG->newReader(%opts)B= $DTA::CAB::Format::CLASS_DEFAULT->new(%opts)
ABresult
1X1
011
000
101 }
102  
103 ## $fmt = CLASS->newWriter(%opts)
104 ## + wraper for DTA::CAB::Format::Registry::newWriter; accepts %opts qw(class file)
105 0 ▶sub newWriter {
Subroutine newWriter: not called CC=2 SCAR=17.9
Pod documented
106 0 my ($that,%opts) = @_;
107 0 ▶ return $REG->newWriter(%opts) // $CLASS_DEFAULT->new(%opts);
Condition0%0/3
$DTA::CAB::Format::REG->newWriter(%opts) // $DTA::CAB::Format::CLASS_DEFAULT->new(%opts)
l!l&&r!l&&!r
000
MC/DC0%0/2
$DTA::CAB::Format::REG->newWriter(%opts) // $DTA::CAB::Format::CLASS_DEFAULT->new(%opts)
$DTA::CAB::Format::REG->newWriter(%opts) $DTA::CAB::Format::CLASS_DEFAULT->new(%opts)
Truth table0%0/3
A // B
A= $DTA::CAB::Format::REG->newWriter(%opts)B= $DTA::CAB::Format::CLASS_DEFAULT->new(%opts)
ABresult
1X1
011
000
108 }
109  
110 ##==============================================================================
111 ## Methods: Global Format Registry
112  
113 ## \%registered = $CLASS_OR_OBJ->registerFormat(%opts)
114 ## + wrapper for DTA::CAB::Format::Registry::register()
115 23 ▶sub registerFormat {
Subroutine registerFormat: called CC=3 SCAR=14.2
Pod documented
116 23 my ($that,%opts) = @_;
117 23 ▶ $opts{name} = (ref($that)||$that) if (!defined($opts{name}));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $opts{"name"} 0 23 23
Condition0%0/3
ref $that || $that
l!l&&r!l&&!r
000
MC/DC0%0/2
ref $that || $that
ref $that $that
Truth table0%0/3
A || B
A= ref $thatB= $that
ABresult
1X1
011
000
118 23 return $REG->register(%opts);
119 }
120  
121 ## \%registered_or_undef = $CLASS_OR_OBJ->guessFilenameFormat($filename)
122 ## + wrapper for DTA::CAB::Format::Registry::guessFilenameFormat()
123 0 ▶sub guessFilenameFormat {
Subroutine guessFilenameFormat: not called CC=1 SCAR=6.9
Pod documented
124 0 return $REG->guessFilenameFormat($_[1]);
125 }
126  
127 ## $readerClass_or_undef = $CLASS_OR_OBJ->fileReaderClass($filename)
128 ## + wrapper for DTA::CAB::Format::Registry::fileReaderClass()
129 0 ▶sub fileReaderClass {
Subroutine fileReaderClass: not called CC=1 SCAR=6.9
Pod documented
130 0 return $REG->fileReaderClass($_[1]);
131 }
132  
133 ## $readerClass_or_undef = $CLASS_OR_OBJ->fileWriterClass($filename)
134 ## + wrapper for DTA::CAB::Format::Registry::fileWriterClass()
135 0 ▶sub fileWriterClass {
Subroutine fileWriterClass: not called CC=1 SCAR=6.9
Pod documented
136 0 return $REG->fileWriterClass($_[1]);
137 }
138  
139 ## $registered_or_undef = $CLASS_OR_OBJ->short2reg($shortname)
140 ## + wrapper for DTA::CAB::Format::Registry::short2reg()
141 0 ▶sub short2reg {
Subroutine short2reg: not called CC=1 SCAR=6.9
Pod documented
142 0 return $REG->short2reg($_[1]);
143 }
144  
145 ## $registered_or_undef = $CLASS_OR_OBJ->base2reg($basename)
146 ## + wrapper for DTA::CAB::Format::Registry::base2reg()
147 0 ▶sub base2reg {
Subroutine base2reg: not called CC=1 SCAR=6.9
Pod documented
148 0 return $REG->base2reg($_[1]);
149 }
150  
151  
152 ##==============================================================================
153 ## Methods: Persistence
154 ##==============================================================================
155  
156 ## @keys = $class_or_obj->noSaveKeys()
157 ## + returns list of keys not to be saved
158 ## + default returns qw(outbuf fh tmpfh)
159 0 ▶sub noSaveKeys {
Subroutine noSaveKeys: not called CC=1 SCAR=6.9
Pod documented
160 0 return qw(outbuf fh tmpfh);
161 }
162  
163 ## $loadedObj = $CLASS_OR_OBJ->loadPerlRef($ref)
164 ## + default inherited from DTA::CAB::Persistent
165  
166 ##==============================================================================
167 ## Methods: I/O : Generic
168 ##==============================================================================
169  
170 ## $fmt = $fmt->close()
171 ## $fmt = $fmt->close($savetmp)
172 ## + close current input source, if any
173 ## + default calls $fmt->{tmpfh}->close() if available and $savetmp is false (default)
174 ## + always deletes $fmt->{fh} and $fmt->{doc}
175 0 ▶sub close {
Subroutine close: not called CC=4 SCAR=30.0
Pod documented
176 0 ▶ if (!$_[1] && $_[0]{tmpfh}) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $_[1] and $_[0]{"tmpfh"}) 0 0 0
Condition0%0/3
not $_[1] and $_[0]{"tmpfh"}
!ll&&!rl&&r
000
MC/DC0%0/2
not $_[1] and $_[0]{"tmpfh"}
not $_[1] $_[0]{"tmpfh"}
Truth table0%0/3
not(A) and B
A= not $_[1]B= $_[0]{"tmpfh"}
ABresult
0X0
100
111
177 0 ▶ $_[0]{tmpfh}->close() if ($_[0]{tmpfh}->opened);
Branch: 1 branch
BranchTrueFalseTotal
if $_[0]{"tmpfh"}->opened 0 0 0
178 0 delete($_[0]{tmpfh});
179 }
180 #$_[0]{fh}->close() if ($_[0]{fh} && $_[0]{fh}->opened());
181 0 delete(@{$_[0]}{qw(fh doc)});
182 0 return $_[0];
183 }
184  
185 ## @layers = $fmt->iolayers()
186 ## + returns PerlIO layers to use for I/O handles
187 ## + default returns ':utf8' if $fmt->{utf8} is true, otherwise ':raw'
188 0 ▶sub iolayers {
Subroutine iolayers: not called CC=2 SCAR=17.9
Pod undocumented
189 0 ▶ return ($_[0]{utf8} ? ':utf8' : ':raw');
Branch: 1 branch
BranchTrueFalseTotal
$_[0]{'utf8'} ? : 0 0 0
190 }
191  
192 ## $fmt = $fmt->setLayers()
193 ## $fmt = $fmt->setLayers($fh)
194 ## $fmt = $fmt->setLayers($fh,@layers)
195 ## + wrapper for binmode($fh,$_) foreach (@layers ? @layers : $fmt->iolayers)
196 0 ▶sub setLayers {
Subroutine setLayers: not called CC=5 SCAR=34.0
Pod undocumented
197 0 my ($fmt,$fh,@layers) = @_;
198 0 ▶ $fh = $fmt->{fh} if (!defined($fh));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $fh 0 0 0
199 0 ▶ return $fmt if (!defined($fh));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $fh 0 0 0
200 0 ▶ binmode($fh,$_) foreach (@layers ? @layers : $fmt->iolayers);
Branch: 1 branch
BranchTrueFalseTotal
@layers ? : 0 0 0
201 0 return $fmt;
202 }
203  
204  
205 ##==============================================================================
206 ## Methods: I/O: Block-wise
207 ##==============================================================================
208  
209 ##--------------------------------------------------------------
210 ## Methods: I/O: Block-wise: Generic
211  
212 ## %blockOpts = $CLASS_OR_OBJECT->blockDefaults()
213 ## + returns default block options as for blockOptions()
214 ## + default implementation just returns (bsize=>(128*1024), eob=>'s')
215 0 ▶sub blockDefaults {
Subroutine blockDefaults: not called CC=1 SCAR=6.9
Pod undocumented
216 0 return (bsize=>(128*1024), eob=>'s');
217 }
218  
219 ## %blockOpts = $CLASS_OR_OBJECT->blockOptions($block_spec)
220 ## + parses $block_spec as a block-boundary spec, which is a string of the form
221 ## MIN_BYTES[{k,M,G,T}][@EOB]
222 ## where:
223 ## - MIN_BYTES[{k,M,G,T}] is the minimum block size in bytes, with optional SI suffix
224 ## - EOB indicates desired block boundary: either 's' (sentence) or 'w' (word)
225 ## + returns a hash with 'size' and 'where' keys
226 ## + pukes if not parseable
227 0 ▶sub blockOptions {
Subroutine blockOptions: not called CC=9 SCAR=45.0
Pod undocumented
228 0 my ($fmt,$bspec) = @_;
229 0 ▶ if (($bspec||'') =~ /^([0-9\.]*)([bkmgt])?(?:[:\@](.*))?$/i) {
Branch: 1 branch
BranchTrueFalseTotal
if (($bspec || "") =~ /^([0-9\.]*)([bkmgt])?(?:[:\@](.*))?$/i) 0 0 0
Condition0%0/2
$bspec || ''
l!l
00
MC/DC0%0/1
$bspec || ''
$bspec
Truth table0%0/2
A
A= $bspec
Aresult
11
00
230 0 my ($n,$suff,$eob) = ($1,lc($2),$3);
231 0 ▶ $n *= 2**10 if ($suff eq 'k');
Branch: 1 branch
BranchTrueFalseTotal
if $suff eq "k" 0 0 0
232 0 ▶ $n *= 2**20 if ($suff eq 'm');
Branch: 1 branch
BranchTrueFalseTotal
if $suff eq "m" 0 0 0
233 0 ▶ $n *= 2**30 if ($suff eq 'g');
Branch: 1 branch
BranchTrueFalseTotal
if $suff eq "g" 0 0 0
234 0 ▶ $n *= 2**40 if ($suff eq 't');
Branch: 1 branch
BranchTrueFalseTotal
if $suff eq "t" 0 0 0
235 0 ▶ return ($fmt->blockDefaults(), ($n ? (bsize=>$n) : qw()), ($eob ? (eob=>$eob) : qw()));
Branch: 2 branches
BranchTrueFalseTotal
$n ? : 0 0 0
$eob ? : 0 0 0
236 }
237 0 $fmt->logconfess("parseBlockOpts(): could not parse block specification '$bspec'");
238 0 return $fmt->blockDefaults();
239 }
240  
241 ##--------------------------------------------------------------
242 ## Methods: I/O: Block-wise: Input
243  
244 ## \@blocks = $fmt->blockScan($infile, %opts)
245 ## + scans $filename for block boundaries according to %opts, which may contain:
246 ## (
247 ## bsize => $bytes, ##-- minimum block-size in bytes
248 ## eob => $eob, ##-- block boundary type; either 's' (sentence) or 't' (word); default='w'
249 ## )
250 ## + sets local keys in %opts passed to sub-methods blockScan{Head,Body,Foot}()
251 ## (
252 ## ifile => $infile, ##-- (in) input filename
253 ## ifsize => $bytes, ##-- (in) total size of $infile in bytes (-s $infile)
254 ## ihead => [$off,$len], ##-- (in) offset, length of header in $infile
255 ## ifoot => [$off,$len], ##-- (in) offset, length of footer in $infile
256 ## ibody => \@iblocks, ##-- (in) blocks computed by blockScanBody()
257 ## ohead => [$off,$len], ##-- (out) offset, length of header in $$odata
258 ## ofoot => [$off,$len], ##-- (out) offset, length of footer in $$odata
259 ## )
260 ## + returns an ARRAY ref of block specifications \@blocks = [$blk1,$blk2,...]
261 ## where each $blk \in @blocks is a HASH-ref containing at least the following keys:
262 ## {
263 ## ifile => $infile, ##-- (in) input filename
264 ## #isize => $bytes, ##-- (in) total size of $filename in bytes (-s $filename)
265 ## ioff => $offset, ##-- (in) byte-offset of block beginning in $infile
266 ## ilen => $len, ##-- (in) byte-length of block in $infile
267 ## id => [$i,$N] ##-- (in/out) indices s.t. $blk=$blocks[$i], $N=$#blocks
268 ## }
269 ## + additionally, $blk may contain the following keys:
270 ## {
271 ## ihead => [$off,$len], ##-- (in) set by blockScanHead() for $infile
272 ## ifoot => [$off,$len], ##-- (in) set by blockScanFoot() for $infile
273 ## ibody => \@iblocks, ##-- (in) blocks computed by blockScanBody()
274 ## eos => $bool, ##-- (in/out) true if block ends on a sentence boundary (for TT, TJ)
275 ## odata => \$odata, ##-- (out) block data octets (for blockAppend())
276 ## ohead => [$off,$len], ##-- (out) set by blockScanHead() for $odata
277 ## ofoot => [$off,$len], ##-- (out) set by blockScanFoot() for $odata
278 ## ofile => $ofilename, ##-- (out) output filename (for Queue::Server::addblock())
279 ## ofmt => $class, ##-- (out) output formatter class or short name (for Queue::Server::addblock())
280 ## }
281 ## + default implementation here calls $fmt->blockScanHead(), $fmt->blockScanBody(), $fmt->blockScanFoot();
282 ## then sets @$blk{qw(ifile ihead ifoot id)} for each body block
283 0 ▶sub blockScan {
Subroutine blockScan: not called CC=8 SCAR=42.8
Pod undocumented
284 0 my ($fmt,$infile,%opts) = @_;
285 0 ▶ $opts{bsize} = 128*1024 if (!defined($opts{bsize}));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $opts{"bsize"} 0 0 0
286 0 ▶ $opts{eob} = 'w' if (!defined($opts{eob}));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $opts{"eob"} 0 0 0
287 0 $fmt->vlog('trace', "blockScan(size=$opts{bsize}, eob=$opts{eob}, file=$infile)");
288  
289 ##-- mmap file
290 0 $opts{ifile} = $infile;
291 0 $opts{ifsize} = (-s $infile);
292 0 my ($buf);
293 0 File::Map::map_file($buf, $infile,'<',0,$opts{fsize});
294  
295 ##-- scan blocks into head, body, foot
296 0 my $ihead = $opts{ihead} = $fmt->blockScanHead(\$buf,'i',\%opts);
297 0 my $ibody = $opts{ibody} = $fmt->blockScanBody(\$buf, \%opts);
298 0 my $ifoot = $opts{ifoot} = $fmt->blockScanFoot(\$buf,'i',\%opts);
299  
300 ##-- adopt 'n', 'head', 'foot' keys into body blocks
301 0 my ($blk);
302 0 my $llBlockScan = undef;
303 0 $fmt->vlog($llBlockScan, "blockScan: $infile \[head]: $ihead->[0] +$ihead->[1] =".($ihead->[0]+$ihead->[1])." <$opts{ifsize}");
304 0 foreach (0..$#$ibody) {
305 0 $blk = $ibody->[$_];
306 0 ▶ $blk->{id} = [$_,$#$ibody] if (!defined($blk->{id}));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $blk->{"id"} 0 0 0
307 0 ▶ $blk->{ifile} = $infile if (!defined($blk->{ifile}));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $blk->{"ifile"} 0 0 0
308 0 ▶ $blk->{ihead} = $ihead if (!defined($blk->{ihead}));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $blk->{"ihead"} 0 0 0
309 0 ▶ $blk->{ifoot} = $ifoot if (!defined($blk->{ifoot}));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $blk->{"ifoot"} 0 0 0
310 0 $fmt->vlog($llBlockScan, "blockScan: $infile \[".($_+1)."/".($#$ibody+1)."]: $blk->{ioff} +$blk->{ilen} =".($blk->{ioff}+$blk->{ilen})." <$opts{ifsize}");
311 }
312 0 $fmt->vlog($llBlockScan, "blockScan: $infile \[foot]: $ifoot->[0] +$ifoot->[1] =".($ifoot->[0]+$ifoot->[1])." <$opts{ifsize}");
313  
314 ##-- cleanup & return
315 0 File::Map::unmap($buf);
316 0 return $ibody;
317 }
318  
319 ## \@head = $fmt->blockScanHead(\$buf,$io,\%opts)
320 ## + scans for block header (${io}head); returns [$offset,$length] for block header in (mmaped) \$buf
321 ## + defatult implementation just returns [0,0] (empty header)
322 0 ▶sub blockScanHead {
Subroutine blockScanHead: not called CC=1 SCAR=6.9
Pod undocumented
323 0 my ($fmt,$bufr,$io,$opts) = @_;
324 0 return [0,0];
325 }
326  
327 ## \@foot = $fmt->blockScanFoot(\$buf,$io,\%opts)
328 ## + scans for block footer (${io}foot); returns [$offset,$length] for block footer in (mmaped) \$buf
329 ## + may adjust contents of $opts{${io}body}
330 ## + default implementation just returns [0,0] (empty footer)
331 0 ▶sub blockScanFoot {
Subroutine blockScanFoot: not called CC=1 SCAR=6.9
Pod undocumented
332 0 my ($fmt,$bufr,$io,$opts) = @_;
333 0 return [0,0];
334 }
335  
336 ## \@blocks = $fmt->blockScanBody(\$buf,\%opts)
337 ## + guts for blockScan(); input only
338 ## + default implementation just dies
339 0 ▶sub blockScanBody {
Subroutine blockScanBody: not called CC=1 SCAR=6.9
Pod undocumented
340 0 my ($fmt,$bufr,$opts) = @_;
341 0 $fmt->logconfess("blockScanBody(): method not implemented in abstract base class ", __PACKAGE__);
342 }
343  
344  
345 ## \$buf = $fmt->blockReadChunk($fh,$f_off,$f_len, \$buf, $b_off=length($buf))
346 ## + append a string of $f_len bytes starting from $f_off in file $fh to buffer \$buf at $b_off
347 0 ▶sub blockReadChunk {
Subroutine blockReadChunk: not called CC=5 SCAR=34.0
Pod undocumented
348 0 my ($fmt, $fh,$off,$len, $bufr,$boff) = @_;
349 0 ▶ $boff = defined($$bufr) ? length($$bufr) : 0 if (!defined($boff));
Branch: 2 branches
BranchTrueFalseTotal
unless defined $boff 0 0 0
defined $$bufr ? : 0 0 0
350 0 ▶ sysseek($fh, $off, SEEK_SET)
Branch: 1 branch
BranchTrueFalseTotal
sysseek $fh, $off, 0 or $fmt->logconfess("blockReadChunk(): sysseek($off) failed: $!") 0 0 0
351 or $fmt->logconfess("blockReadChunk(): sysseek($off) failed: $!");
352 0 ▶ sysread($fh, $$bufr, $len, $boff)==$len
Branch: 1 branch
BranchTrueFalseTotal
sysread($fh, $$bufr, $len, $boff) == $len or $fmt->logconfess("blockReadChunk(): sysread() failed for chunk of length ${len}: $!") 0 0 0
353 or $fmt->logconfess("blockReadChunk(): sysread() failed for chunk of length $len: $!");
354 0 return $bufr;
355 }
356  
357 ## \$buf = $fmt->blockRead(\%blk)
358 ## \$buf = $fmt->blockRead(\%blk,\$buf)
359 ## + reads block input data for \%blk into \$bufr
360 ## + default implementation just appends raw bytes for:
361 ## - block header @{$blk{ihead}}
362 ## - block body @blk{qw(ioff ilen)}
363 ## - block footer @{$blk{ifoot}}
364 0 ▶sub blockRead {
Subroutine blockRead: not called CC=9 SCAR=45.0
Pod undocumented
365 0 my ($fmt,$blk,$bufr) = @_;
366 0 ▶ $bufr = \(my $buf) if (!defined($bufr));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $bufr 0 0 0
367 0 $$bufr = '';
368 0 ▶ my $infile = ($blk->{ifile} || $blk->{file});
Condition0%0/3
$blk->{'ifile'} || $blk->{'file'}
l!l&&r!l&&!r
000
MC/DC0%0/2
$blk->{'ifile'} || $blk->{'file'}
$blk->{'ifile'} $blk->{'file'}
Truth table0%0/3
A || B
A= $blk->{'ifile'}B= $blk->{'file'}
ABresult
1X1
011
000
369 0 ▶ my $infh = IO::File->new("<$infile")
Branch: 1 branch
BranchTrueFalseTotal
my $infh = "IO::File"->new("<$infile") or $fmt->logconfess("blockRead(): open failed for '${infile}': $!") 0 0 0
370 or $fmt->logconfess("blockRead(): open failed for '$infile': $!");
371 0 binmode($infh,':raw');
372  
373 0 ▶ $fmt->blockReadChunk($infh, @{$blk->{ihead}}, $bufr) if ($blk->{ihead} && $blk->{ihead}[1]); ##-- head
Branch: 1 branch
BranchTrueFalseTotal
if $blk->{"ihead"} and $blk->{"ihead"}[1] 0 0 0
Condition0%0/3
$blk->{"ihead"} and $blk->{"ihead"}[1]
!ll&&!rl&&r
000
MC/DC0%0/2
$blk->{"ihead"} and $blk->{"ihead"}[1]
$blk->{"ihead"} $blk->{"ihead"}[1]
Truth table0%0/3
A and B
A= $blk->{"ihead"}B= $blk->{"ihead"}[1]
ABresult
0X0
100
111
374 0 ▶ $fmt->blockReadChunk($infh, @$blk{qw(ioff ilen)}, $bufr) if ($blk->{ilen}); ##-- body
Branch: 1 branch
BranchTrueFalseTotal
if $blk->{"ilen"} 0 0 0
375 0 ▶ $fmt->blockReadChunk($infh, @{$blk->{ifoot}}, $bufr) if ($blk->{ifoot} && $blk->{ifoot}[1]); ##-- foot
Branch: 1 branch
BranchTrueFalseTotal
if $blk->{"ifoot"} and $blk->{"ifoot"}[1] 0 0 0
Condition0%0/3
$blk->{"ifoot"} and $blk->{"ifoot"}[1]
!ll&&!rl&&r
000
MC/DC0%0/2
$blk->{"ifoot"} and $blk->{"ifoot"}[1]
$blk->{"ifoot"} $blk->{"ifoot"}[1]
Truth table0%0/3
A and B
A= $blk->{"ifoot"}B= $blk->{"ifoot"}[1]
ABresult
0X0
100
111
376  
377 0 $infh->close();
378 0 return $bufr;
379 }
380  
381 ## $doc = $fmt->parseBlock(\%blk)
382 ## + parses a block into a DTA::CAB::Document
383 ## + wrapper for blockRead(), parseString(), close()
384 0 ▶sub parseBlock {
Subroutine parseBlock: not called CC=1 SCAR=6.9
Pod undocumented
385 0 my ($fmt,$blk) = @_;
386 0 my $ibufr = $fmt->blockRead($blk);
387 0 my $doc = $fmt->parseString($ibufr);
388 0 $fmt->close();
389 0 return $doc;
390 }
391  
392  
393 ##--------------------------------------------------------------
394 ## Methods: I/O: Block-wise: Output
395  
396 ## $blk = $fmt->blockStore(\$odata,$blk,\%bopt={})
397 ## + store output buffer \$buf in $blk->{odata}
398 ## + additionally store keys qw(ofmt ohead odata ofoot) relative to $blk->{odata}
399 ## + default calls blockScanHead(), blockScanFoot() with dummy options only if not already set in $blk
400 0 ▶sub blockStore {
Subroutine blockStore: not called CC=10 SCAR=47.0
Pod undocumented
401 0 my ($fmt,$bufr,$blk,$bopt) = @_;
402  
403 0 ▶ $bopt = {} if (!defined($bopt));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $bopt 0 0 0
404 0 ▶ $blk->{id} = [0,0] if (!defined($blk->{id}));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $blk->{"id"} 0 0 0
405 0 ▶ $blk->{ohead} = ($blk->{id}[0]==0 ? [0,0] : $fmt->blockScanHead($bufr,'o',{%$blk,%$bopt})) if (!defined($blk->{ohead}));
Branch: 2 branches
BranchTrueFalseTotal
unless defined $blk->{"ohead"} 0 0 0
$blk->{'id'}[0] == 0 ? : 0 0 0
406 0 ▶ $blk->{obody} = [$blk] if (!defined($blk->{obody}));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $blk->{"obody"} 0 0 0
407 0 ▶ $blk->{ofoot} = ($blk->{id}[0]==$blk->{id}[1] ? [0,0] : $fmt->blockScanFoot($bufr,'o',{%$blk,%$bopt})) if (!defined($blk->{ofoot}));
Branch: 2 branches
BranchTrueFalseTotal
unless defined $blk->{"ofoot"} 0 0 0
$blk->{'id'}[0] == $blk->{'id'}[1] ? : 0 0 0
408 0 ▶ $blk->{odata} = $bufr if (!defined($blk->{odata}));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $blk->{"odata"} 0 0 0
409 0 ▶ $blk->{ofmt} = $fmt->shortName if (!defined($blk->{ofmt}));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $blk->{"ofmt"} 0 0 0
410  
411 0 return $blk;
412 }
413  
414 ## $fmt = $fmt->putDocumentBlock($doc,$blk)
415 ## + wrapper for $fmt->toString(\(my $buf))->putDocumentRaw()->flush()->blockStore(\$buf,$blk)
416 0 ▶sub putDocumentBlock {
Subroutine putDocumentBlock: not called CC=1 SCAR=6.9
Pod undocumented
417 0 my ($fmt,$doc,$blk) = @_;
418 0 my $buf = '';
419 0 $fmt->toString(\$buf)->putDocumentRaw($doc)->flush()->blockStore(\$buf,$blk);
420 0 return $fmt;
421 }
422  
423 ## $fmt_or_undef = $fmt->blockAppend($blk)
424 ## $fmt_or_undef = $fmt->blockAppend($blk,$ofile)
425 ## + append a block $block to a file $ofile (default=$blk->{ofile})
426 ## + $block is a HASH-ref as returned by blockScan()
427 ## + default implementation just dumps $blk->{odata} to $filename;
428 ## modulo @$blk{qw(ohead ofoot)} as appropriate
429 0 ▶sub blockAppend {
Subroutine blockAppend: not called CC=17 SCAR=55.8
Pod undocumented
430 0 my ($fmt,$blk,$ofile) = @_;
431 0 ▶ $ofile = $blk->{ofile} if (!defined($ofile));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $ofile 0 0 0
432  
433 ##-- common variables
434 1 ▶ use bytes;
Subroutine BEGIN: called CC=1 SCAR=0.0
435 0 my $bufr = $blk->{odata};
436 0 ▶ my $id = $blk->{id} || [0,0];
Condition0%0/2
$blk->{'id'} || [0, 0]
l!l
00
MC/DC0%0/1
$blk->{'id'} || [0, 0]
$blk->{'id'}
Truth table0%0/2
A
A= $blk->{'id'}
Aresult
11
00
437 0 ▶ my $ohead = $blk->{ohead} || [0,0];
Condition0%0/2
$blk->{'ohead'} || [0, 0]
l!l
00
MC/DC0%0/1
$blk->{'ohead'} || [0, 0]
$blk->{'ohead'}
Truth table0%0/2
A
A= $blk->{'ohead'}
Aresult
11
00
438 0 ▶ my $ofoot = $blk->{ofoot} || [0,0];
Condition0%0/2
$blk->{'ofoot'} || [0, 0]
l!l
00
MC/DC0%0/1
$blk->{'ofoot'} || [0, 0]
$blk->{'ofoot'}
Truth table0%0/2
A
A= $blk->{'ofoot'}
Aresult
11
00
439  
440 0 my $blkid = "${ofile}:$id->[0]/$id->[1]";
441 0 ▶ my $outfh = IO::File->new(($id->[0]==0 ? '>' : '>>').$ofile)
Branch: 2 branches
BranchTrueFalseTotal
my $outfh = "IO::File"->new(($id->[0] == 0 ? ">" : ">>") . $ofile) or $fmt->logconfess("blockAppend(): open failed for '${ofile}': $!") 0 0 0
$id->[0] == 0 ? : 0 0 0
442 or $fmt->logconfess("blockAppend(): open failed for '$ofile': $!");
443 0 ▶ binmode($outfh, utf8::is_utf8($$bufr) ? ':utf8' : ':raw');
Branch: 1 branch
BranchTrueFalseTotal
utf8::is_utf8($$bufr) ? : 0 0 0
444  
445 0 $fmt->vlog($LL_BLK_DEBUG, "blockAppend($blkid): begin: pos=", $outfh->tell, "; buflen=", bytes::length($$bufr));
446 0 $fmt->vlog($LL_BLK_DEBUG, "blockAppend($blkid): ohead=[$ohead->[0],$ohead->[1]]; ofoot=[$ofoot->[0],$ofoot->[1]]");
447  
448 ##-- dump: header (initial block only)
449 0 ▶ if ($id->[0]==0 && $ohead->[1]>0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($id->[0] == 0 and $ohead->[1] > 0) 0 0 0
Condition0%0/3
$id->[0] == 0 and $ohead->[1] > 0
!ll&&!rl&&r
000
MC/DC0%0/2
$id->[0] == 0 and $ohead->[1] > 0
$id->[0] == 0 $ohead->[1] > 0
Truth table0%0/3
A and B
A= $id->[0] == 0B= $ohead->[1] > 0
ABresult
0X0
100
111
450 0 ▶ $outfh->print(substr($$bufr, $ohead->[0], $ohead->[1]-$ohead->[0]))
Branch: 1 branch
BranchTrueFalseTotal
$outfh->print(substr($$bufr, $ohead->[0], $ohead->[1] - $ohead->[0])) or $fmt->logconfess("blockAppend(): print failed to '${ofile}' for initial-block header: $!") 0 0 0
451 or $fmt->logconfess("blockAppend(): print failed to '$ofile' for initial-block header: $!");
452 0 $fmt->vlog($LL_BLK_DEBUG, "blockAppend($blkid): wrote ", ($ohead->[1]-$ohead->[0]), " header bytes\n");
453 }
454  
455 ##-- dump: body
456 0 ▶ $outfh->print(substr($$bufr, $ohead->[1], ($ofoot->[0]||length($$bufr))-($ohead->[0]+$ohead->[1])))
Branch: 1 branch
BranchTrueFalseTotal
$outfh->print(substr($$bufr, $ohead->[1], ($ofoot->[0] || length $$bufr) - ($ohead->[0] + $ohead->[1]))) or $fmt->logconfess("blockAppend(): print failed to '${ofile}' for block body: $!") 0 0 0
Condition0%0/3
$ofoot->[0] || length $$bufr
l!l&&r!l&&!r
000
MC/DC0%0/2
$ofoot->[0] || length $$bufr
$ofoot->[0] length $$bufr
Truth table0%0/3
A || B
A= $ofoot->[0]B= length $$bufr
ABresult
1X1
011
000
457 or $fmt->logconfess("blockAppend(): print failed to '$ofile' for block body: $!");
458 0 ▶ $fmt->vlog($LL_BLK_DEBUG, "blockAppend($blkid): wrote ", (($ofoot->[0]||length($$bufr))-($ohead->[0]+$ohead->[1])), " data bytes");
Condition0%0/3
$ofoot->[0] || length $$bufr
l!l&&r!l&&!r
000
MC/DC0%0/2
$ofoot->[0] || length $$bufr
$ofoot->[0] length $$bufr
Truth table0%0/3
A || B
A= $ofoot->[0]B= length $$bufr
ABresult
1X1
011
000
459  
460 ##-- dump: footer (final block only)
461 0 ▶ if ($id->[0]==$id->[1] && $ofoot->[1]>0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($id->[0] == $id->[1] and $ofoot->[1] > 0) 0 0 0
Condition0%0/3
$id->[0] == $id->[1] and $ofoot->[1] > 0
!ll&&!rl&&r
000
MC/DC0%0/2
$id->[0] == $id->[1] and $ofoot->[1] > 0
$id->[0] == $id->[1] $ofoot->[1] > 0
Truth table0%0/3
A and B
A= $id->[0] == $id->[1]B= $ofoot->[1] > 0
ABresult
0X0
100
111
462 0 ▶ $outfh->print(substr($$bufr, $ofoot->[0], $ofoot->[1]-$ofoot->[0]))
Branch: 1 branch
BranchTrueFalseTotal
$outfh->print(substr($$bufr, $ofoot->[0], $ofoot->[1] - $ofoot->[0])) or $fmt->logconfess("blockAppend(): print failed to '${ofile}' for final-block footer: $!") 0 0 0
463 or $fmt->logconfess("blockAppend(): print failed to '$ofile' for final-block footer: $!");
464 0 $fmt->vlog($LL_BLK_DEBUG, "blockAppend($blkid): wrote ", ($ofoot->[1]-$ofoot->[0]), " footer bytes");
465 }
466  
467 ##-- cleanup & return
468 0 $fmt->vlog($LL_BLK_DEBUG, "blockAppend($blkid): finished, pos=", $outfh->tell);
469 0 $outfh->close;
470 0 return $fmt;
471 }
472  
473 ##==============================================================================
474 ## Methods: Input
475 ##==============================================================================
476  
477 ##--------------------------------------------------------------
478 ## Methods: Input: Input selection
479  
480 ## $fmt = $fmt->from(fh=>$fh)
481 ## $fmt = $fmt->from(file=>$file)
482 ## $fmt = $fmt->from(string=>$str)
483 ## $fmt = $fmt->from(string=>\$str)
484 ## + open $fmt for input from specified source
485 ## + wraps fromFh(), fromFile(), fromString()
486 0 ▶sub from {
Subroutine from: not called CC=3 SCAR=24.8
Pod undocumented
487 0 my $fmt = shift;
488 0 my $which = shift;
489 0 ▶ return $fmt->fromFh(@_) if ($which eq 'fh');
Branch: 1 branch
BranchTrueFalseTotal
if $which eq "fh" 0 0 0
490 0 ▶ return $fmt->fromFile(@_) if ($which eq 'file');
Branch: 1 branch
BranchTrueFalseTotal
if $which eq "file" 0 0 0
491 0 return $fmt->fromString(@_);
492 }
493  
494 ## $fmt = $fmt->fromString( $string)
495 ## $fmt = $fmt->fromString(\$string)
496 ## + select input from string $string
497 ## + default calls $fmt->fromFh($fmt->{tmpfh}=$new_fh)
498 0 ▶sub fromString {
Subroutine fromString: not called CC=3 SCAR=24.8
Pod documented
499 0 my $fmt = shift;
500 0 $fmt->close;
501 0 my $fh = IO::Handle->new();
502 0 ▶ CORE::open($fh, '<', ref($_[0]) ? $_[0] : \$_[0])
Branch: 2 branches
BranchTrueFalseTotal
open $fh, "<", ref $_[0] ? $_[0] : \$_[0] or $fmt->logconfess("fromString(): open failed for string input: $!") 0 0 0
ref $_[0] ? : 0 0 0
503 or $fmt->logconfess("fromString(): open failed for string input: $!");
504 0 return $fmt->fromFh($fmt->{tmpfh}=$fh);
505 }
506  
507 ## $fmt = $fmt->fromFile($filename)
508 ## + select input from file $filename
509 ## + default calls $fmt->fromFh($fmt->{tmpfh}=$new_fh)
510 0 ▶sub fromFile {
Subroutine fromFile: not called CC=3 SCAR=24.8
Pod documented
511 0 my ($fmt,$file) = @_;
512 0 $fmt->close;
513 0 ▶ my $fh = (ref($file) ? $file : IO::File->new("<$file"))
Branch: 2 branches
BranchTrueFalseTotal
my $fh = ref $file ? $file : "IO::File"->new("<$file") or $fmt->logconfess("fromFile(): open failed for '${file}'") 0 0 0
ref $file ? : 0 0 0
514 or $fmt->logconfess("fromFile(): open failed for '$file'");
515 0 return $fmt->fromFh($fmt->{tmpfh}=$fh);
516 }
517  
518 ## $fmt = $fmt->fromFh($fh)
519 ## + select input from open filenandle $fh
520 ## + default implementation just calls $fmt->close(1) and sets $fmt->{fh}=$fh
521 0 ▶sub fromFh {
Subroutine fromFh: not called CC=2 SCAR=17.9
Pod documented
522 0 my ($fmt,$fh) = @_;
523 0 ▶ $fmt->logconfess("fromFh(): abstract method called for object instance") if ($fmt->can('fromFh') eq \&fromFh); ##-- sanity check
Branch: 1 branch
BranchTrueFalseTotal
if $fmt->can("fromFh") eq \&DTA::CAB::Format::fromFh 0 0 0
524 0 $fmt->close(1); ##-- keep $fmt->{tmpfh} for auto-close
525 0 $fmt->{fh} = $fh; ##-- save this handle for later use
526 #$fmt->setLayers(); ##-- set perlIO layers
527 #$fmt->logconfess("fromFh() not implemented");
528 0 return $fmt;
529 }
530  
531 ## $fmt = $fmt->fromFh_str($fh)
532 ## + alternate fromFh() implementation which slurps contents of $fh and calls $fmt->fromString(\$str)
533 0 ▶sub fromFh_str {
Subroutine fromFh_str: not called CC=1 SCAR=6.9
Pod documented
534 0 my ($fmt,$fh) = @_;
535 0 $fmt->DTA::CAB::Format::fromFh($fh);
536 0 $fmt->setLayers();
537 0 local $/=undef;
538 0 my $str = <$fh>;
539 0 return $fmt->fromString(\$str);
540 }
541  
542 ##--------------------------------------------------------------
543 ## Methods: Input: Generic API
544  
545 ## $doc = $fmt->parseDocument()
546 ## + parse document from currently selected input source
547 0 ▶sub parseDocument {
Subroutine parseDocument: not called CC=1 SCAR=6.9
Pod documented
548 0 my $fmt = shift;
549 0 $fmt->logconfess("parseDocument() not implemented in abstract base class ", __PACKAGE__ );
550 }
551  
552 ## $doc = $fmt->parseString( $str)
553 ## $doc = $fmt->parseString(\$str)
554 ## + wrapper for $fmt->fromString(\$str)->parseDocument()
555 0 ▶sub parseString {
Subroutine parseString: not called CC=2 SCAR=17.9
Pod documented
556 0 ▶ my $doc = $_[0]->fromString(ref($_[1]) ? $_[1] : \$_[1])->parseDocument;
Branch: 1 branch
BranchTrueFalseTotal
ref $_[1] ? : 0 0 0
557 0 $_[0]->close();
558 0 return $doc;
559 }
560  
561 ## $doc = $fmt->parseFile($filename_or_fh)
562 ## + wrapper for $fmt->fromFile($filename_or_fh)->parseDocument()
563 0 ▶sub parseFile {
Subroutine parseFile: not called CC=1 SCAR=6.9
Pod documented
564 0 my $doc = $_[0]->fromFile($_[1])->parseDocument;
565 0 $_[0]->close();
566 0 return $doc;
567 }
568  
569 ## $doc = $fmt->parseFh($fh)
570 ## + wrapper for $fmt->fromFh($filename_or_fh)->parseDocument()
571 0 ▶sub parseFh {
Subroutine parseFh: not called CC=1 SCAR=6.9
Pod documented
572 0 my $doc = $_[0]->fromFh($_[1])->parseDocument;
573 0 $_[0]->close();
574 0 return $doc;
575 }
576  
577 ##--------------------------------------------------------------
578 ## Methods: Input: Utilties
579  
580 ## $doc = $fmt->forceDocument($reference)
581 ## + attempt to tweak $reference into a DTA::CAB::Document
582 ## + a slightly more in-depth version of DTA::CAB::Datum::toDocument()
583 0 ▶sub forceDocument {
Subroutine forceDocument: not called CC=14 SCAR=53.5
Pod documented
584 0 my ($fmt,$any) = @_;
585 0 ▶ if (!ref($any)) {
Branch: 6 branches
BranchTrueFalseTotal
if (not ref $any) { } 0 0 0
elsif (DTA::CAB::Format::isa($any, 'DTA::CAB::Document')) { } 0 0 0
elsif (DTA::CAB::Format::isa($any, 'DTA::CAB::Sentence')) { } 0 0 0
elsif (DTA::CAB::Format::isa($any, 'DTA::CAB::Token')) { } 0 0 0
elsif (ref $any eq 'HASH') { } 0 0 0
elsif (ref $any eq 'ARRAY') { } 0 0 0
586 ##-- string: token-like
587 #return bless({body=>[ bless({tokens=>[bless({text=>$any},'DTA::CAB::Token')]},'DTA::CAB::Sentence') ]},'DTA::CAB::Document');
588 0 $any ={body=>[ {tokens=>[{text=>$any}] }] };
589 }
590 elsif (isa($any,'DTA::CAB::Document')) {
591 ##-- document
592 ; #$any;
593 }
594 elsif (isa($any,'DTA::CAB::Sentence')) {
595 ##-- sentence
596 0 $any = {body=>[$any]};
597 }
598 elsif (isa($any,'DTA::CAB::Token')) {
599 ##-- token
600 #return bless({body=>[ bless({tokens=>[$any]},'DTA::CAB::Sentence') ]},'DTA::CAB::Document');
601 0 $any= {body=>[ {tokens=>[$any]} ]};
602 }
603 elsif (ref($any) eq 'HASH') {
604 ##-- hash
605 0 ▶ if (exists($any->{body})) {
Branch: 3 branches
BranchTrueFalseTotal
if (exists $any->{'body'}) { } 0 0 0
elsif (exists $any->{'tokens'}) { } 0 0 0
elsif (exists $any->{'text'}) { } 0 0 0
606 ##-- hash, document-like
607 #return bless($any,'DTA::CAB::Document');
608 ;
609 }
610 elsif (exists($any->{tokens})) {
611 ##-- hash, sentence-like
612 0 $any = {body=>[$any]};
613 }
614 elsif (exists($any->{text})) {
615 ##-- hash, token-like
616 0 $any = {body=>[ {tokens=>[$any]} ]};
617 }
618 }
619 elsif (ref($any) eq 'ARRAY') {
620 ##-- array
621 0 ▶ if (!ref($any->[0])) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $any->[0]) 0 0 0
622 ##-- array; assumedly of token strings
623 0 $_ = {text=>$_} foreach (grep {!ref($_)} @$any);
624 0 $any = {body=>[ {tokens=>$any} ]};
625 }
626 }
627 else {
628 ##-- something else
629 0 ▶ $fmt->warn("forceDocument(): cannot massage non-document '".(ref($any)||$any)."'");
Condition0%0/3
ref $any || $any
l!l&&r!l&&!r
000
MC/DC0%0/2
ref $any || $any
ref $any $any
Truth table0%0/3
A || B
A= ref $anyB= $any
ABresult
1X1
011
000
630 0 return $any;
631 }
632 0 ▶ $any = bless($any,'DTA::CAB::Document') if (!isa($any,'DTA::CAB::Document'));
Branch: 1 branch
BranchTrueFalseTotal
unless DTA::CAB::Format::isa($any, "DTA::CAB::Document") 0 0 0
633 0 return $any;
634 }
635  
636 ##==============================================================================
637 ## Methods: Output
638 ##==============================================================================
639  
640 ##--------------------------------------------------------------
641 ## Methods: Output: Generic
642  
643 ## $type = $fmt->mimeType()
644 ## + default returns text/plain
645 0 ▶sub contentType { return $_[0]->mimeType(@_[1..$#_]); }
Subroutine contentType: not called CC=1 SCAR=6.9
Pod undocumented
646 0 ▶sub mimeType { return 'text/plain'; }
Subroutine mimeType: not called CC=1 SCAR=6.9
Pod documented
647  
648 ## $ext = $fmt->defaultExtension()
649 ## + returns default filename extension for this format (default='.cab')
650 0 ▶sub defaultExtension { return '.cab'; }
Subroutine defaultExtension: not called CC=1 SCAR=6.9
Pod documented
651  
652 ## $short = $fmt->shortName()
653 ## + returns "official" short name for this format
654 ## + default just returns package suffix
655 0 ▶sub shortName {
Subroutine shortName: not called CC=3 SCAR=24.8
Pod documented
656 0 my $short = shift;
657 0 ▶ $short = ref($short) || $short;
Condition0%0/3
ref $short || $short
l!l&&r!l&&!r
000
MC/DC0%0/2
ref $short || $short
ref $short $short
Truth table0%0/3
A || B
A= ref $shortB= $short
ABresult
1X1
011
000
658 0 ▶ if ($short =~ s/^DTA::CAB::Format:://) {
Branch: 1 branch
BranchTrueFalseTotal
if ($short =~ s/^DTA::CAB::Format:://) { } 0 0 0
659 0 $short =~ s/://g;
660 } else {
661 0 $short =~ s/^.*\:\://;
662 }
663 0 return lc($short);
664 }
665  
666 ## $lvl = $fmt->formatLevel()
667 ## $fmt = $fmt->formatLevel($level)
668 ## + set output formatting level
669 0 ▶sub formatLevel {
Subroutine formatLevel: not called CC=2 SCAR=17.9
Pod documented
670 0 my ($fmt,$level) = @_;
671 0 ▶ return $fmt->{level} if (!defined($level));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $level 0 0 0
672 0 $fmt->{level}=$level;
673 0 return $fmt;
674 }
675  
676 ## $fmt = $fmt->flush()
677 ## + flush any buffered output to selected output source
678 ## + default implementation deletes $fmt->{outbuf} and calls $fmt->{fh}->flush()
679 0 ▶sub flush {
Subroutine flush: not called CC=2 SCAR=17.9
Pod documented
680 0 delete($_[0]{outbuf});
681 0 ▶ $_[0]{fh}->flush() if (defined($_[0]{fh}));
Branch: 1 branch
BranchTrueFalseTotal
if defined $_[0]{"fh"} 0 0 0
682 0 return $_[0];
683 }
684  
685 ##--------------------------------------------------------------
686 ## Methods: Output: output selection
687  
688 ## $fmt = $fmt->to(fh=>$fh)
689 ## $fmt = $fmt->to(file=>$file)
690 ## $fmt = $fmt->to(string=>\$str)
691 ## + open $fmt for output to specified destination
692 ## + wraps toFh(), toFile(), toString()
693 0 ▶sub to {
Subroutine to: not called CC=3 SCAR=24.8
Pod undocumented
694 0 my $fmt = shift;
695 0 my $which = shift;
696 0 ▶ return $fmt->toFh(@_) if ($which eq 'fh');
Branch: 1 branch
BranchTrueFalseTotal
if $which eq "fh" 0 0 0
697 0 ▶ return $fmt->toFile(@_) if ($which eq 'file');
Branch: 1 branch
BranchTrueFalseTotal
if $which eq "file" 0 0 0
698 0 return $fmt->toString(@_);
699 }
700  
701  
702 ## $fmt = $fmt->toString(\$str, $level)
703 ## + select output to $str
704 ## + default implementation just wraps $fmt->toFh($fmt->{tmpfh}=$new_fh, $level)
705 0 ▶sub toString {
Subroutine toString: not called CC=3 SCAR=24.8
Pod documented
706 0 my $fmt = shift;
707 0 $fmt->close;
708 0 my $fh = IO::Handle->new();
709 0 ▶ CORE::open($fh, '>', ref($_[0]) ? $_[0] : \$_[0])
Branch: 2 branches
BranchTrueFalseTotal
open $fh, ">", ref $_[0] ? $_[0] : \$_[0] or $fmt->logconfess("toString(): open failed for string output: $!") 0 0 0
ref $_[0] ? : 0 0 0
710 or $fmt->logconfess("toString(): open failed for string output: $!");
711 0 return $fmt->toFh($fmt->{tmpfh}=$fh, $_[1]);
712 }
713  
714 ## $fmt_or_undef = $fmt->toFile($filename, $formatLevel)
715 ## + select output to named file $filename
716 ## + default implementation just wraps $fmt->toFh($fmt->{tmpfh}=$new_fh, $level)
717 0 ▶sub toFile {
Subroutine toFile: not called CC=3 SCAR=24.8
Pod documented
718 0 my ($fmt,$file,$level) = @_;
719 0 $fmt->close;
720 0 ▶ my $fh = (ref($file) ? $file : IO::File->new(">$file"))
Branch: 2 branches
BranchTrueFalseTotal
my $fh = ref $file ? $file : "IO::File"->new(">$file") or $fmt->logconfess("toFile(): open failed for '${file}'") 0 0 0
ref $file ? : 0 0 0
721 or $fmt->logconfess("toFile(): open failed for '$file'");
722 0 return $fmt->toFh($fmt->{tmpfh}=$fh, $level);
723 }
724  
725 ## $fmt_or_undef = $fmt->toFh($fh,$level)
726 ## + select output to an open filehandle $fh
727 ## + default implementation just calls $fmt->formatLevel($level) and sets $fmt->{fh}=$fh
728 0 ▶sub toFh {
Subroutine toFh: not called CC=2 SCAR=17.9
Pod documented
729 0 my ($fmt,$fh,$level) = @_;
730 #$fmt->logconfess("toFh(): abstract method called for object instance") if ($fmt->can('toFh') eq \&toFh); ##-- sanity check
731 0 ▶ $fmt->formatLevel($level) if (defined($level));
Branch: 1 branch
BranchTrueFalseTotal
if defined $level 0 0 0
732 0 $fmt->{fh}=$fh;
733 #$fmt->setLayers($fh) ##-- set I/O layers
734 #$fh->print($fmt->{outbuf});
735 0 return $fmt;
736 }
737  
738 ## $fmt_or_undef = $fmt->buf2fh(\$inbuf=\$fmt->{outbuf},$fh)
739 ## + low-level utility which dumps $$buf to $fh
740 ## + may call utf8::encode() or utf8::upgrade() on $inbuf
741 0 ▶sub buf2fh {
Subroutine buf2fh: not called CC=6 SCAR=37.4
Pod undocumented
742 0 my ($fmt,$bufr,$fh) = @_;
743 0 ▶ $bufr = \$fmt->{outbuf} if (!defined($bufr));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $bufr 0 0 0
744 0 my $buf_u8 = utf8::is_utf8($$bufr);
745 0 my $fh_u8 = grep {$_ eq 'utf8'} PerlIO::get_layers($fh);
746 0 ▶ if ($buf_u8 && !$fh_u8) {
Branch: 2 branches
BranchTrueFalseTotal
if ($buf_u8 and not $fh_u8) { } 0 0 0
elsif (not $buf_u8 and $fh_u8) { } 0 0 0
Condition0%0/3
$buf_u8 and not $fh_u8
!ll&&!rl&&r
000
MC/DC0%0/2
$buf_u8 and not $fh_u8
$buf_u8 not $fh_u8
Truth table0%0/3
A and not(B)
A= $buf_u8B= not $fh_u8
ABresult
0X0
100
111
747 ##-- utf8 -> bytes: encode buffer
748 0 utf8::encode($$bufr);
749 ▶ } elsif (!$buf_u8 && $fh_u8) {
Condition0%0/3
not $buf_u8 and $fh_u8
!ll&&!rl&&r
000
MC/DC0%0/2
not $buf_u8 and $fh_u8
not $buf_u8 $fh_u8
Truth table0%0/3
not(A) and B
A= not $buf_u8B= $fh_u8
ABresult
0X0
100
111
750 ##-- bytes -> utf8: upgrade buffer
751 0 utf8::upgrade($$bufr);
752 }
753 0 $fh->print($$bufr);
754 0 return $fmt;
755 }
756  
757 ## $fmt_or_undef = $fmt->buf2bytes(\$inbuf=\$fmt->{outbuf},\$outbuf)
758 ## + low-level utility which copies raw bytes of $$inbuf to $$outbuf
759 0 ▶sub buf2bytes {
Subroutine buf2bytes: not called CC=3 SCAR=24.8
Pod undocumented
760 0 my ($fmt,$ibufr,$obufr) = @_;
761 0 ▶ $ibufr = \$fmt->{outbuf} if (!defined($ibufr));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $ibufr 0 0 0
762 0 $$obufr = $$ibufr;
763 0 ▶ utf8::encode($$obufr) if (utf8::is_utf8($$obufr));
Branch: 1 branch
BranchTrueFalseTotal
if utf8::is_utf8($$obufr) 0 0 0
764 0 return $fmt;
765 }
766  
767 ## $fmt_or_undef = $fmt->toFh_buf($fh,$formatLevel)
768 ## + toFh() implementation which dumps $fmt->{outbuf} to $fmt->{fh}=$fh
769 #sub toFh_buf {
770 # my $fmt = shift;
771 # $fmt->DTA::CAB::Format::toFh($fmt,@_); ##-- set $fmt->{level}, $fmt->{fh}
772 # binmode($fmt->{fh}, (utf8::is_utf8($fmt->{outbuf}) ? ':utf8' : ':raw'));
773 # $fmt->{fh}->print($fmt->{outbuf});
774 # return $fmt;
775 #}
776  
777 ##--------------------------------------------------------------
778 ## Methods: Output: Recommended API
779  
780 ## $fmt = $fmt->putToken($tok)
781 ## + default implementations of other methods assume output is concatenated onto $fmt->{outbuf}
782 0 ▶sub putTokenRaw { return $_[0]->putToken($_[1]); }
Subroutine putTokenRaw: not called CC=1 SCAR=6.9
Pod documented
783 0 ▶sub putToken {
Subroutine putToken: not called CC=1 SCAR=6.9
Pod documented
784 0 my $fmt = shift;
785 0 $fmt->logconfess("putToken() not implemented!");
786 0 return undef;
787 }
788  
789 ## $fmt = $fmt->putSentence($sent)
790 ## + default implementation just iterates $fmt->putToken() & appends 1 additional "\n" to $fmt->{outbuf}
791 0 ▶sub putSentenceRaw { return $_[0]->putSentence($_[1]); }
Subroutine putSentenceRaw: not called CC=1 SCAR=6.9
Pod documented
792 0 ▶sub putSentence {
Subroutine putSentence: not called CC=2 SCAR=17.9
Pod documented
793 0 my ($fmt,$sent) = @_;
794 0 $fmt->putToken($_) foreach (@{toSentence($sent)->{tokens}});
795 0 $fmt->{outbuf} .= "\n";
796 0 return $fmt;
797 }
798  
799 ##--------------------------------------------------------------
800 ## Methods: Output: Required API
801  
802 ## $fmt = $fmt->putDocument($doc)
803 ## + default implementation just iterates $fmt->putSentence()
804 ## + should be non-destructive for $doc
805 0 ▶sub putDocument {
Subroutine putDocument: not called CC=2 SCAR=17.9
Pod documented
806 0 my ($fmt,$doc) = @_;
807 0 $fmt->putSentence($_) foreach (@{toDocument($doc)->{body}});
808 0 return $fmt;
809 }
810  
811 ## $fmt = $fmt->putDocumentRaw($doc)
812 ## + may copy plain $doc reference
813 0 ▶sub putDocumentRaw { return $_[0]->putDocument($_[1]); }
Subroutine putDocumentRaw: not called CC=1 SCAR=6.9
Pod documented
814  
815  
816 ## $fmt = $fmt->putData($data)
817 ## + put arbitrary raw data (e.g. for YAML, JSON, XmlPerl)
818 0 ▶sub putData {
Subroutine putData: not called CC=1 SCAR=6.9
Pod undocumented
819 0 $_[0]->logconfess("putData() not implemented!");
820 }
821  
822 1 1; ##-- be happy
823  
824 __END__
« CAB/Format/TEIws.pm ↑ Summary CAB/Format/Raw/Perl.pm »