| 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__ |