CAB/Format/XmlCommon.pm untested

filter: Statementstmt 0.0% 0 / 125 Branchbran 0.0% 0 / 46 Conditioncond 0.0% 0 / 56 MC/DCmcdc 0.0% 0 / 33 Subroutinesub 0.0% 0 / 28 Podpod 0.0% 0 / 21 totaltotal 0.0% 0 / 309 CC 24 SCAR 29.5
CC
24
Cov
0%
defaultXmlNode
72.0
flush
30.0
toFile
20.0
CRAP 19.1
1 ## -*- Mode: CPerl -*-
2 ##
3 ## File: DTA::CAB::Format::Common.pm
4 ## Author: Bryan Jurish <moocow@cpan.org>
5 ## Description: Datum parser|formatter: XML (common)
6  
7 package DTA::CAB::Format::XmlCommon;
8 use DTA::CAB::Format;
9 use DTA::CAB::Datum ':all';
10 use DTA::CAB::Utils ':libxml';
11 use XML::LibXML;
12 use IO::File;
13 use Carp;
14 use strict;
15  
16 ##==============================================================================
17 ## Globals
18 ##==============================================================================
19  
20 our @ISA = qw(DTA::CAB::Format);
21  
22 ##==============================================================================
23 ## Constructors etc.
24 ##==============================================================================
25  
26 ## $fmt = CLASS_OR_OBJ->new(%args)
27 ## + object structure: assumed HASH
28 ## (
29 ## ##-- input
30 ## xdoc => $xdoc, ##-- XML::LibXML::Document
31 ## xprs => $xprs, ##-- XML::LibXML parser
32 ## xprsopts => \%opts, ##-- XML::LibXML parser options
33 ##
34 ## ##-- output
35 ## #utf8 => $bool, ##-- always true
36 ## level => $level, ##-- output formatting level (default=0)
37 ## output => [$how,$arg] ##-- either ['fh',$fh], ['file',$filename], or ['str',\$buf]
38 ##
39 ## ##-- common
40 ## )
41 sub new {
42 my $that = shift;
43 my $fmt = bless({
44 ##-- input
45 xprs => undef, ##-- see xmlparser() method, below
46 xdoc => undef,
47 #xmlparser_opts => {},
48  
49 ##-- output
50 utf8 => 1,
51 level => 0,
52 output => undef,
53  
54 ##-- common
55  
56 ##-- user args
57 @_
58 }, ref($that)||$that);
59 return $fmt;
60 }
61  
62 ## $xmlparser = $fmt->xmlparser(%xmlparser_opts)
63 ## + returns cached $fmt->{xprs} if available
64 ## + otherwise caches & returns DTA::CAB::Utils::libxml_parser()
65 sub xmlparser {
66 return $_[0]{xprs} if (ref($_[0]) && defined($_[0]{xprs}));
67 return $_[0]{xprs} = DTA::CAB::Utils::libxml_parser( %{$_[0]{xprsopts}//{}}, @_[1..$#_] );
68 }
69  
70 ##==============================================================================
71 ## Methods: Persistence
72 ##==============================================================================
73  
74 ## @keys = $class_or_obj->noSaveKeys()
75 ## + returns list of keys not to be saved
76 sub noSaveKeys {
77 return ($_[0]->SUPER::noSaveKeys, qw(xdoc xprs));
78 }
79  
80 ##=============================================================================
81 ## Methods: I/O: generic
82 ##==============================================================================
83  
84 ## $fmt = $fmt->close($savetmp=0)
85 ## + override calls $fmt->flush() and deletes @$fmt{qw(xdoc output)}
86 sub close {
87 $_[0]->flush();# if (!$_[0]{flushing});
88 delete @{$_[0]}{qw(xdoc output)};
89 return $_[0]->SUPER::close(@_[1..$#_]);
90 }
91  
92 ## @layers = $fmt->iolayers()
93 ## + returns PerlIO layers to use for I/O handles
94 ## + override returns ':raw'
95 sub iolayers {
96 return qw(:raw);
97 }
98  
99 ## $fmt = $fmt->flush()
100 ## + flush any buffered output to selected output channel
101 ## + override dumps buffered $fmt->{xdoc} to output sink in ($outputHow,$outputArg)=@{$fmt->{out}} and deletes $fmt->{xdoc}
102 sub flush {
103 my $fmt = shift;
104 if (defined(my $xdoc=$fmt->{xdoc}) && defined(my $out=$fmt->{output})) {
105 if ($out->[0] eq 'string') {
106 ${$out->[1]} = $xdoc->toString($fmt->{level} || 0)
107 or $fmt->logconfess(ref($xdoc)."::toString() failed: $!");
108 }
109 if ($out->[0] eq 'file') {
110 $xdoc->toFile($out->[1], $fmt->{level} || 0)
111 or $fmt->logconfess(ref($xdoc)."::toFile() failed for $out->[1]: $!");
112 }
113 elsif ($out->[0] eq 'fh') {
114 $xdoc->toFH($out->[1], $fmt->{level} || 0)
115 or $fmt->logconfess(ref($xdoc)."::toFH() failed for $out->[1]: $!");
116 }
117 }
118 delete $fmt->{xdoc};
119 return $fmt;
120 }
121  
122 ##=============================================================================
123 ## Methods: Input
124 ##==============================================================================
125  
126 ##--------------------------------------------------------------
127 ## Methods: Input: Input selection
128  
129 ## $fmt = $fmt->fromString(\$string)
130 ## + input from string: override buffers XML document in $fmt->{xdoc}
131 sub fromString {
132 my $fmt = shift;
133 $fmt->{xdoc} = $fmt->xmlparser->parse_string(ref($_[0]) ? ${$_[0]} : $_[0])
134 or $fmt->logconfess("XML::LibXML::parse_string() failed: $!");
135 return $fmt;
136 }
137  
138 ## $fmt = $fmt->fromFile($filename)
139 ## + input from named file: override buffers XML document in $fmt->{xdoc}
140 sub fromFile {
141 my ($fmt,$file) = @_;
142 return $fmt->fromFh($file) if (ref($file));
143 $fmt->{xdoc} = $fmt->xmlparser->parse_file($file)
144 or $fmt->logconfess("XML::LibXML::parse_file() failed for '$file': $!");
145 return $fmt;
146 }
147  
148 ## $fmt = $fmt->fromFh($handle)
149 ## + input from filehandle: override buffers XML document in $fmt->{xdoc}
150 sub fromFh {
151 my ($fmt,$fh) = @_;
152 $fmt->{xdoc} = $fmt->xmlparser->parse_fh($fh)
153 or $fmt->logconfess("XML::LibXML::parse_fh() failed for handle '$fh': $!");
154 return $fmt;
155 }
156  
157 ##--------------------------------------------------------------
158 ## Methods: Input: Generic API
159  
160 ## $doc = $fmt->parseDocument()
161 ## + parse document from currently selected input source
162 ## + to be overridden by child classes
163 sub parseDocument {
164 my $fmt = shift;
165 $fmt->logconfess("parseDocument() not implemented in abstract base class ", __PACKAGE__);
166 }
167  
168  
169 ##==============================================================================
170 ## Methods: Output
171 ##==============================================================================
172  
173 ##--------------------------------------------------------------
174 ## Methods: Output: Generic
175  
176 ## $type = $fmt->mimeType()
177 ## + override returns text/xml
178 sub mimeType { return 'text/xml'; }
179  
180 ## $ext = $fmt->defaultExtension()
181 ## + returns default filename extension for this format
182 sub defaultExtension { return '.xml'; }
183  
184 ##--------------------------------------------------------------
185 ## Methods: Output: output selection
186  
187 ## $fmt = $fmt->toString(\$str)
188 ## $fmt = $fmt->toString(\$str, $formatLevel)
189 ## + select output to string
190 ## + override sets $fmt->{output}=['string',\$str]
191 sub toString {
192 my $fmt = shift;
193 $fmt->close;
194 $fmt->{output} = ['string', ref($_[0]) ? $_[0] : \$_[0]];
195 $fmt->formatlevel($_[1]) if (defined($_[1]));
196 #$fmt->xmlDocument(); ##-- prepare document
197 return $fmt;
198 }
199  
200 ## $fmt_or_undef = $fmt->toFile($filename, $formatLevel)
201 ## + select output to file
202 ## + override sets $fmt->{output}=['file',\$filename]
203 sub toFile {
204 my $fmt = shift;
205 return $fmt->toFh(@_) if (ref($_[0]));
206 return $fmt->toFh(\*STDOUT) if ($_[0] eq '-');
207 $fmt->close;
208 $fmt->{output} = ['file', $_[0]];
209 $fmt->formatlevel($_[1]) if (defined($_[1]));
210 #$fmt->xmlDocument(); ##-- prepare document
211 return $fmt;
212 }
213  
214 ## $fmt_or_undef = $fmt->toFh($handle, $formatLevel)
215 ## + flush buffered output document to $filename_or_handle
216 ## + override sets $fmt->{output}=['fh',$handle]
217 sub toFh {
218 my $fmt = shift;
219 $fmt->close;
220 $fmt->{output} = ['fh', $_[0]];
221 binmode($_[0],':raw'); ##-- set raw mode for XML output
222 $fmt->formatlevel($_[1]) if (defined($_[1]));
223 #$fmt->xmlDocument(); ##-- prepare document
224 return $fmt;
225 }
226  
227  
228 ##--------------------------------------------------------------
229 ## Methods: Output: local
230  
231 ## $xmldoc = $fmt->xmlDocument()
232 ## + create or return output buffer $fmt->{xdoc}
233 sub xmlDocument {
234 return $_[0]{xdoc} if (defined($_[0]{xdoc}));
235 return $_[0]{xdoc} = XML::LibXML::Document->new("1.0","UTF-8");
236 }
237  
238 ## $rootnode = $fmt->xmlRootNode()
239 ## $rootnode = $fmt->xmlRootNode($nodname)
240 ## + returns root node
241 ## + $nodname defaults to 'doc'
242 sub xmlRootNode {
243 my ($fmt,$name) = @_;
244 my $xdoc = $fmt->xmlDocument;
245 my $root = $xdoc->documentElement;
246 if (!defined($root)) {
247 $xdoc->setDocumentElement($root = XML::LibXML::Element->new(defined($name) ? $name : 'doc'));
248 }
249 return $root;
250 }
251  
252 ##--------------------------------------------------------------
253 ## Methods: Output: Generic API
254  
255 sub putToken { $_[0]->logconfess("putToken(): not implemented in abstract base class ", __PACKAGE__); }
256 sub putSentence { $_[0]->logconfess("putSentence(): not implemented in abstract base class ", __PACKAGE__); }
257 sub putDocument { $_[0]->logconfess("putDocument(): not implemented in abstract base class ", __PACKAGE__); }
258  
259  
260 ##--------------------------------------------------------------
261 ## Methods: Output: XML Nodes: Generic
262  
263 ## $nod = $fmt->defaultXmlNode($value,\%opts)
264 ## + default XML node generator
265 ## + \%opts:
266 ## hashElt => $elt, ##-- output hash element (default='HASH')
267 ## listElt => $elt, ##-- ouput list element (default='ARRAY')
268 ## atomElt => $elt, ##-- ouput atom element (default='VALUE')
269 our $HASH_ELT = 'HASH';
270 our $LIST_ELT = 'ARRAY';
271 our $ATOM_ELT = 'VALUE';
272 sub defaultXmlNode {
273 my ($fmt,$val,$opts) = @_;
274 my $hashElt = $opts->{hashElt}||$fmt->{hashElt}||$HASH_ELT;
275 my $listElt = $opts->{listElt}||$fmt->{listElt}||$LIST_ELT;
276 my $atomElt = $opts->{atomElt}||$fmt->{atomElt}||$ATOM_ELT;
277 my ($vnod);
278 if (UNIVERSAL::can($val,'xmlNode') && UNIVERSAL::can($val,'xmlNode') ne \&defaultXmlNode) {
279 ##-- xml-aware object (avoiding circularities): $val->xmlNode()
280 return $val->xmlNode(@_[2..$#_]);
281 }
282 elsif (!ref($val)) {
283 ##-- non-reference: <ATOM>$val</ATOM> or <VALUE undef="1"/>
284 $vnod = XML::LibXML::Element->new($atomElt);
285 if (defined($val)) {
286 $vnod->appendText($val);
287 } else {
288 $vnod->setAttribute("undef","1");
289 }
290 }
291 elsif (UNIVERSAL::isa($val,'HASH')) {
292 ##-- HASH ref: <HASH ref="$ref"> ... <ENTRY key="$eltKey">defaultXmlNode($eltVal)</ENTRY> ... </HASH>
293 $vnod = XML::LibXML::Element->new($hashElt);
294 $vnod->setAttribute("ref",ref($val)) if (ref($val) ne 'HASH');
295 foreach (keys(%$val)) {
296 my $enod = $fmt->defaultXmlNode($val->{$_},$opts);
297 $enod->setAttribute("key",$_);
298 $vnod->addChild($enod);
299 }
300 }
301 elsif (UNIVERSAL::isa($val,'ARRAY')) {
302 ##-- ARRAY ref: <ARRAY ref="$ref"> ... xmlNode($eltVal) ... </ARRAY>
303 $vnod = XML::LibXML::Element->new($listElt);
304 $vnod->setAttribute("ref",ref($val)) if (ref($val) ne 'ARRAY');
305 foreach (@$val) {
306 $vnod->addChild($fmt->defaultXmlNode($_));
307 }
308 }
309 # elsif (UNIVERSAL::isa($val,'SCALAR')) {
310 # ##-- SCALAR ref: <SCALAR ref="$ref"> xmlNode($$val) </SCALAR>
311 # $vnod = XML::LibXML::Element->new("SCALAR");
312 # $vnod->setAttribute("ref",ref($val)); #if (ref($val) ne 'SCALAR');
313 # $vnod->addChild($fmt->defaultXmlNode($$val));
314 # }
315 else {
316 ##-- other reference (CODE,etc.): <VALUE ref="$ref" unknown="1">"$val"</VALUE>
317 $fmt->logcarp("defaultXmlNode(): default node generator clause called for value '$val'");
318 $vnod = XML::LibXML::Element->new($atomElt);
319 $vnod->setAttribute("ref",ref($val));
320 $vnod->setAttribute("unknown","1");
321 $vnod->appendText("$val");
322 }
323 return $vnod;
324 }
325  
326  
327  
328 1; ##-- be happy
329  
330 __END__