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