.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "XML::Structured 3pm"
.TH XML::Structured 3pm "2018-04-21" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::Structured \- simple conversion API from XML to perl structures and back
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use XML::Structured;
\&
\&    $dtd = [
\&        \*(Aqelement\*(Aq =>
\&            \*(Aqattribute1\*(Aq,
\&            \*(Aqattribute2\*(Aq,
\&            [],
\&            \*(Aqelement1\*(Aq,
\&            [ \*(Aqelement2\*(Aq ],
\&            [ \*(Aqelement3\*(Aq =>
\&                ...
\&            ],
\&            [[ \*(Aqelement4\*(Aq =>
\&                ...
\&            ]],
\&    ];
\&
\&    $hashref = XMLin($dtd, $xmlstring);
\&    $hashref = XMLinfile($dtd, $filename_or_glob);
\&    $xmlstring = XMLout($dtd, $hashref);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The XML::Structured module provides a way to convert xml data into
a predefined perl data structure and back to xml. Unlike with modules
like XML::Simple it is an error if the xml data does not match
the provided skeleton (the \*(L"dtd\*(R"). Another advantage is that the
order of the attributes and elements is taken from the dtd when
converting back to xml.
.SS "\fIXMLin()\fP"
.IX Subsection "XMLin()"
The \fIXMLin()\fR function takes the dtd and a string as arguments and
returns a hash reference containing the data.
.SS "\fIXMLinfile()\fP"
.IX Subsection "XMLinfile()"
This function works like \f(CW\*(C`XMLin()\*(C'\fR, but takes a filename or a
file descriptor glob as second argument.
.SS "\fIXMLout()\fP"
.IX Subsection "XMLout()"
\&\f(CW\*(C`XMLout()\*(C'\fR provides the reverse operation to \f(CW\*(C`XMLin()\*(C'\fR, it takes
a dtd and a hash reference as arguments and returns an \s-1XML\s0 string.
.SH "The DTD"
.IX Header "The DTD"
The dtd parameter specifies the structure of the allowed xml data.
It consists of nested perl arrays.
.SS "simple attributes and elements"
.IX Subsection "simple attributes and elements"
The very simple example for a dtd is:
.PP
.Vb 4
\&    $dtd = [ \*(Aquser\*(Aq =>
\&                 \*(Aqlogin\*(Aq,
\&                 \*(Aqpassword\*(Aq,
\&           ];
.Ve
.PP
This dtd will accept/create \s-1XML\s0 like:
.PP
.Vb 1
\&    <user login="foo" password="bar" />
.Ve
.PP
XMLin doesn't care if \*(L"login\*(R" or \*(L"password\*(R" are attributes or
elements, so
.PP
.Vb 4
\&    <user>
\&      <login>foo</login>
\&      <password>bar</password>
\&    </user>
.Ve
.PP
is also valid input (but doesn't get re-created by \f(CW\*(C`XMLout()\*(C'\fR).
.SS "multiple elements of the same name"
.IX Subsection "multiple elements of the same name"
If an element may appear multiple times, it must be declared as
an array in the dtd:
.PP
.Vb 4
\&    $dtd = [ \*(Aquser\*(Aq =>
\&                 \*(Aqlogin\*(Aq,
\&                 [ \*(Aqfavorite_fruits\*(Aq ],
\&           ];
.Ve
.PP
XMLin will create an array reference as value in this case, even if
the xml data contains only one element. Valid \s-1XML\s0 looks like:
.PP
.Vb 4
\&    <user login="foo">
\&      <favorite_fruits>apple</favorite_fruits>
\&      <favorite_fruits>peach</favorite_fruits>
\&    </user>
.Ve
.PP
As attributes may not appear multiple times, XMLout will create
elements for this case. Note also that all attributes must come
before the first element, thus the first array in the dtd ends
the attribute list. As an example, the following dtd
.PP
.Vb 5
\&    $dtd = [ \*(Aquser\*(Aq =>
\&                 \*(Aqlogin\*(Aq,
\&                 [ \*(Aqfavorite_fruits\*(Aq ],
\&                 \*(Aqpassword\*(Aq,
\&           ];
.Ve
.PP
will create xml like:
.PP
.Vb 5
\&    <user login="foo">
\&      <favorite_fruits>apple</favorite_fruits>
\&      <favorite_fruits>peach</favorite_fruits>
\&      <password>bar</password>
\&    </user>
.Ve
.PP
\&\*(L"login\*(R" is translated to an attribute and \*(L"password\*(R" to an element.
.PP
You can use an empty array reference to force the end of the attribute
list, e.g.:
.PP
.Vb 5
\&    $dtd = [ \*(Aquser\*(Aq =>
\&                 [],
\&                 \*(Aqlogin\*(Aq,
\&                 \*(Aqpassword\*(Aq,
\&           ];
.Ve
.PP
will translate to
.PP
.Vb 4
\&    <user>
\&      <login>foo</login>
\&      <password>bar</password>
\&    </user>
.Ve
.PP
instead of
.PP
.Vb 1
\&    <user login="foo" password="bar" />
.Ve
.SS "sub-elements"
.IX Subsection "sub-elements"
sub-elements are elements that also contain attributes or other
elements. They are specified in the dtd as arrays with more than
one element. Here is an example:
.PP
.Vb 7
\&    $dtd = [ \*(Aquser\*(Aq =>
\&                 \*(Aqlogin\*(Aq,
\&                 [ \*(Aqaddress\*(Aq =>
\&                     \*(Aqstreet\*(Aq,
\&                     \*(Aqcity\*(Aq,
\&                 ],
\&           ];
.Ve
.PP
Valid xml for this dtd looks like:
.PP
.Vb 3
\&    <user login="foo">
\&      <address street="broadway 7" city="new york" />
\&    </user>
.Ve
.PP
It is sometimes useful to specify such dtds in multiple steps:
.PP
.Vb 4
\&    $addressdtd = [ \*(Aqaddress\*(Aq =>
\&                         \*(Aqstreet\*(Aq,
\&                         \*(Aqcity\*(Aq,
\&                  ];
\&
\&    $dtd = [ \*(Aquser\*(Aq =>
\&                 \*(Aqlogin\*(Aq,
\&                 $addressdtd,
\&           ];
.Ve
.SS "multiple sub-elements with the same name"
.IX Subsection "multiple sub-elements with the same name"
As with simple elements, one can allow sub-elements to occur multiple
times. \f(CW\*(C`XMLin()\*(C'\fR creates an array of hash references in this case.
The dtd specification uses an array reference to an array for this
case, for example:
.PP
.Vb 8
\&    $dtd = [ \*(Aquser\*(Aq =>
\&                 \*(Aqlogin\*(Aq,
\&                 [[ \*(Aqaddress\*(Aq =>
\&                     \*(Aqstreet\*(Aq,
\&                     \*(Aqcity\*(Aq,
\&                 ]],
\&           ];
\&Or, with the $addressdtd definition used in the previous example:
\&
\&    $dtd = [ \*(Aquser\*(Aq =>
\&                 \*(Aqlogin\*(Aq,
\&                 [ $addressdtd ],
\&           ];
.Ve
.PP
Accepted \s-1XML\s0 is:
.PP
.Vb 4
\&    <user login="foo">
\&      <address street="broadway 7" city="new york" />
\&      <address street="rural road 12" city="tempe" />
\&    </user>
.Ve
.SS "the _content pseudo-element"
.IX Subsection "the _content pseudo-element"
All of the non-whitespace parts between elements get collected
into a single \*(L"_content\*(R" element. As example,
.PP
.Vb 4
\&    <user login="foo">
\&      <address street="broadway 7" city="new york"/>hello
\&      <address street="rural road 12" city="tempe"/>world
\&    </user>
.Ve
.PP
would set the _content element to \f(CW\*(C`hello world\*(C'\fR (the dtd must allow
a _content element, of course). If the dtd is
.PP
.Vb 5
\&    $dtd = [ \*(Aquser\*(Aq =>
\&                 \*(Aqlogin\*(Aq,
\&                 [ $addressdtd ],
\&                 \*(Aq_content\*(Aq,
\&           ];
.Ve
.PP
the xml string created by \fIXMLout()\fR will be:
.PP
.Vb 5
\&    <user login="foo">
\&      <address street="broadway 7" city="new york" />
\&      <address street="rural road 12" city="tempe" />
\&      hello world    
\&    </user>
.Ve
.PP
The exact input cannot be re-created, as the positions and the
fragmentation of the content data is lost.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBXML::Structured\fR requires either XML::Parser or \s-1XML::SAX\s0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2006 Michael Schroeder <mls@suse.de>
.PP
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.