Debian Codegraph @

README

raw
1 NAME
2
3 XML-Struct - Represent XML as data structure preserving element order
4
5 SYNOPSIS
6
7 use XML::Struct qw(readXML writeXML simpleXML);
8
9 my $xml = readXML( "input.xml" );
10 # [ root => { xmlns => 'http://example.org/' }, [ '!', [ x => {}, [42] ] ] ]
11
12 my $doc = writeXML( $xml );
13 # <?xml version="1.0" encoding="UTF-8"?>
14 # <root xmlns="http://example.org/">!<x>42</x></root>
15
16 my $simple = simpleXML( $xml, root => 'record' );
17 # { record => { xmlns => 'http://example.org/', x => 42 } }
18
19 DESCRIPTION
20
21 XML::Struct implements a mapping between XML and Perl data structures.
22 By default, the mapping preserves element order, so it also suits for
23 "document-oriented" XML. In short, an XML element is represented as
24 array reference with three parts:
25
26 [ $name => \%attributes, \@children ]
27
28 This data structure corresponds to the abstract data model of MicroXML
29 <http://www.w3.org/community/microxml/>, a simplified subset of XML.
30
31 If your XML documents don't contain relevant attributes, you can also
32 choose to map to this format:
33
34 [ $name => \@children ] # element without attributes
35 [ $name ] # empty tag without attributes
36
37 Both parsing (with XML::Struct::Reader or function readXML) and
38 serializing (with XML::Struct::Writer or function writeXML) are fully
39 based on XML::LibXML, so performance is better than XML::Simple and
40 similar to XML::LibXML::Simple.
41
42 MODULES
43
44 XML::Struct::Reader
45
46 Parse XML as stream into XML data structures.
47
48 XML::Struct::Writer
49
50 Write XML data structures to XML streams for serializing, SAX
51 processing, or creating a DOM object.
52
53 XML::Struct::Writer::Stream
54
55 Simplified SAX handler for XML serialization.
56
57 XML::Struct::Simple
58
59 Transform XML data structure into simple form.
60
61 FUNCTIONS
62
63 The following functions are exported on request:
64
65 readXML( $source [, %options ] )
66
67 Read an XML document with XML::Struct::Reader. The type of source
68 (string, filename, URL, IO Handle...) is detected automatically. See
69 XML::Struct::Reader for options. Options not known to
70 XML::Struct::Reader are passed to XML::LibXML::Reader.
71
72 writeXML( $xml [, %options ] )
73
74 Write an XML document/element with XML::Struct::Writer. See
75 XML::Struct::Writer for options.
76
77 simpleXML( $element [, %options ] )
78
79 Transform an XML document/element into simple key-value format as known
80 from XML::Simple. See XML::Struct::Simple for options.
81
82 removeXMLAttr( $element )
83
84 Transform XML structure with attributes to XML structure without
85 attributes. The function does not modify the passed element but creates
86 a modified copy.
87
88 this function is deprecated and will be removed in a future release!
89
90 EXAMPLE
91
92 To give an example, with XML::Struct::Reader, this XML document:
93
94 <root>
95 <foo>text</foo>
96 <bar key="value">
97 text
98 <doz/>
99 </bar>
100 </root>
101
102 is transformed to this structure:
103
104 [
105 "root", { }, [
106 [ "foo", { }, "text" ],
107 [ "bar", { key => "value" }, [
108 "text",
109 [ "doz", { }, [ ] ]
110 ]
111 ]
112 ]
113
114 This module also supports a simple key-value (aka "data-oriented")
115 format, as used by XML::Simple. With option simple (or function
116 simpleXML) the document given above would be transformed to this
117 structure:
118
119 {
120 foo => "text",
121 bar => {
122 key => "value",
123 doz => {}
124 }
125 }
126
127 SEE ALSO
128
129 This module was first created to be used in Catmandu::XML and turned
130 out to also become a replacement for XML::Simple. See the former for
131 more XML processing.
132
133 XML::Twig is another popular and powerfull module for stream-based
134 processing of XML documents.
135
136 See XML::Smart, XML::Hash::LX, XML::Parser::Style::ETree, XML::Fast,
137 and XML::Structured for different representations of XML data as data
138 structures (feel free to implement converters from/to XML::Struct).
139 XML::GenericJSON seems to be an outdated and incomplete attempt to
140 capture more parts of XML Infoset in another data structure.
141
142 See JSONx for a kind of reverse direction (JSON in XML).
143
144 COPYRIGHT AND LICENSE
145
146 This software is copyright (c) 2014 by Jakob Voß.
147
148 This is free software; you can redistribute it and/or modify it under
149 the same terms as the Perl 5 programming language system itself.
150