Debian Codegraph @

README

raw
1 NAME
2
3 Catmandu::XSD - Modules for handling XML data with XSD compilation
4
5 SYNOPSIS
6
7 ## Converting XML to YAML/JSON/CSV/etc
8
9 # Compile an XSD schema file and parse one shiporder.xml file
10 catmandu convert XSD --root '{}shiporder'
11 --schemas demo/order/*.xsd
12 to YAML < shiporder.xml
13
14 # Same as above but parse more than one file into an array of records
15 catmandu convert XSD --root '{}shiporder'
16 --schemas demo/order/*.xsd
17 --files 'data/*.xml'
18 to YAML
19
20 # Same as above but all array of records are in a XML container file
21 catmandu convert XSD --root '{}shiporder'
22 --schemas demo/order/*.xsd
23 --xpath '/Container/List//Record/Payload/*'
24 to YAML < data/container.xml
25
26 ## Convert an YAML/JSON/CSV into XML validated against an XSD schemas
27
28 # Convert one shiporder YAML to XML
29 catmandu convert YAML to XSD --root '{}shiporder'
30 --schemas demo/order/*.xsd < shiporder.YAML
31
32 # Same as above but store multiple shiporders in the YAML into a separate file
33 catmandu convert YAML to XSD --root '{}shiporder'
34 --schemas demo/order/*.xsd
35 --split 1
36 < shiporder.YAML
37
38 # Same as above but use template toolkit to pack the XML into an container
39 # (The xml record is stored in the 'xml' key which can be retrieved in the
40 # template by [% xml %])
41 catmandu convert YAML to XSD --root '{}shiporder'
42 --schemas demo/order/*.xsd
43 --template_before t/xml_header.tt
44 --template t/xml_record.tt
45 --template t/xml_footer.tt
46 < shiporder.YAML
47
48 ## Example documents
49
50 # Show an example how a valid XML document needs to be structured for an
51 # XSD scheme.
52 catmandu convert XSD --root {}shiporder
53 --schemas "t/demo/order/*xsd"
54 --example 1 to YAML
55
56 DESCRIPTION
57
58 Catmandu::XSD contains modules for handling XML data within the
59 Catmandu framework. Parsing and serializing is based on XML::Compile.
60
61 There are two modules available for handling XML data in the Catmandu
62 framework: Catmandu::XML and Catmandu::XSD. The former one can be used
63 when no XML schema is available for the data. It provides a simple
64 interface to read in XML data and transform it to other formats.
65 Because Catmandu::XML doesn't depend on an XSD schema, it can't know
66 which fields in the input XML files are sequences or single value
67 elements. Each record is parsed on its own. A record with content:
68
69 <foo>
70 <bar>test</bar>
71 </foo>
72
73 will be parsed into a YAML output like:
74
75 catmandu XML to YAML < test.xml
76 --
77 bar: test
78
79 A record with content:
80
81 <foo>
82 <bar>test</bar>
83 <bar>test</bar>
84 </foo>
85
86 will be parsed into a YAL output like:
87
88 catmandu XML to YAML < test2.xml
89 --
90 bar:
91 - test
92 - test
93
94 In the first case 'bar' will contain a string, in the second case an
95 array. This might no be what you want in some programming projects.
96 E.g. when you need the 'bar' field to be always an array of values,
97 then you an XSD schema file is required containing the exact structure
98 of the XML document:
99
100 test.xsd:
101 <?xml version="1.0" encoding="UTF-8" ?>
102 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
103 <xs:element name="foo">
104 <xs:complexType>
105 <xs:sequence>
106 <xs:element name="bar" type="xs:string" maxOccurs="unbounded"/>
107 </xs:sequence>
108 </xs:complexType>
109 </xs:element>
110 </xs:schema>
111
112 And now the test.xml and test2.xml can be parsed with help of
113 Catmandu::XSD:
114
115 catmandu XSD --root '{}foo' --schemas test.xsd to YAML < test.xml
116 --
117 bar:
118 - test
119
120 catmandu XSD --root '{}foo' --schemas test.xsd to YAML < test2.xml
121 --
122 bar:
123 - test
124 - test
125
126 WILDCARDS
127
128 Some XSD Schema allow for any or anyAttribute specifications in the
129 schema. The Catmandu::XSD modules can't guess in these cases what the
130 schema implementation is. These nodes will be parsed as
131 XML::LibXML::Nodes in the resulting documents. Catmandu output formats
132 such as Catmandu::Exporter::JSON can't handle these XML::LibXML::Node
133 nodes. You have to implement yourself a Catmandu::Fix to translate
134 these values in to plain string, array or hash elements.
135
136 But in general a round trip should be problematic:
137
138 catmandu XSD --root ... --schema wildcard.xsd to XSD --root ... --schema wildcard.xsd < data.xml
139
140 MIXED ELEMENTS
141
142 ComplexType and ComplexContent in the XSD schema can be declared with
143 the <mixed="true"> attribute. This means that in the XML documents
144 simple text and XML elements can be mixed as in:
145
146 Hello, I'm <name>John</name> how can I <bold>help</bold> you?
147
148 In these cases it is not know if the elements are required as an hash
149 or should be ignored. By defaults Catmandu::XSD will parse these
150 elements as XML::LibXML::Nodes documents. This behavious can be changed
151 by setting the 'mixed' flag:
152
153 # All mixed elements will be XML::LibXML::Node-s
154 catmandu XSD --root ... --schema mixed.xsd < data.xml
155
156 # The mixed elements will be ignored, only the text will survive
157 #
158 # Hello, I'm <name>John</name> how can I <bold>help</bold> you?
159 #
160 # => Hello, I'm John how can I help you?
161 catmandu XSD --root ... --schema mixed.xsd --mixed TEXTUAL < data.xml
162
163 # The mixed text will be ignored, only the elements will survive
164 #
165 # Hello, I'm <name>John</name> how can I <bold>help</bold> you?
166 #
167 # => { name => 'John' , bold => 'help' }
168 catmandu XSD --root ... --schema mixed.xsd --mixed STRUCTURAL < data.xml
169
170 # The mixed elements will be a plain XML fragment string
171 #
172 # Hello, I'm <name>John</name> how can I <bold>help</bold> you?
173 #
174 # => $r = 'Hello, I'm <name>John</name> how can I <bold>help</bold> you?'
175 catmandu XSD --root ... --schema mixed.xsd --mixed XML_STRING < data.xml
176
177 MODULES
178
179 Catmandu::Importer::XSD
180
181 Parse and validate XML data using an XSD file for structural data.
182
183 Catmandu::Exporter::XSD
184
185 Serialize and validate XML data using an XSD file for structural
186 data.
187
188 Catmandu::Fix::xpath_map
189
190 Map XML from XSD-any elements into data fields using XPath
191 expressions.
192
193 BUGS, QUESTIONS, HELP
194
195 Use the github issue tracker for any bug reports or questions on this
196 module: https://github.com/LibreCat/Catmandu-XSD/issues
197
198 DISCLAIMER
199
200 This module is based on XML::Compile and the Catmandu framework.
201
202 XML::Compile is the workhorse that forms the core of this module to
203 compile XSD file into parser and serializers.
204
205 Catmandu is used to transform parsed XML into any format you like.
206 Catmandu contains a simple DSL languages called Catmandu::Fix to create
207 small scripts to manipulate data. The Catmandu toolkit is used by many
208 university libraries to process metadata collections.
209
210 For more information on Catmandu visit: http://librecat.org/Catmandu/
211 or follow the blog posts at: https://librecatproject.wordpress.com/
212
213 AUTHOR
214
215 Patrick Hochstenbach , patrick.hochstenbach at ugent.be
216
217 LICENSE AND COPYRIGHT
218
219 This program is free software; you can redistribute it and/or modify it
220 under the terms of either: the GNU General Public License as published
221 by the Free Software Foundation; or the Artistic License.
222
223 See http://dev.perl.org/licenses/ for more information.
224
225 SEE ALSO
226
227 XML::Compile , Catmandu , Template , Catmandu::XML
228