.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SimpleObject 3pm"
.TH SimpleObject 3pm "2022-06-28" "perl v5.34.0" "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::SimpleObject \- Perl extension allowing a simple object representation of a parsed XML::Parser tree.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use XML::SimpleObject;
\&
\&  # Construct with the key/value pairs as argument; this will create its 
\&  # own XML::Parser object.
\&  my $xmlobj = new XML::SimpleObject(XML => $XML, ErrorContext => 2);
\&
\&  # ... or construct with the parsed tree as the only argument, having to 
\&  # create the XML::Parser object separately.
\&  my $parser = new XML::Parser (ErrorContext => 2, Style => "Tree");
\&  my $xmlobj = new XML::SimpleObject ($parser\->parse($XML));
\&
\&  my $filesobj = $xmlobj\->child("files")\->child("file");
\&
\&  $filesobj\->name;
\&  $filesobj\->value;
\&  $filesobj\->attribute("type");
\&  
\&  %attributes    = $filesobj\->attributes;
\&  @children      = $filesobj\->children;
\&  @some_children = $filesobj\->children("some");
\&  @chilren_names = $filesobj\->children_names;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a short and simple class allowing simple object access to a parsed XML::Parser tree, with methods for fetching children and attributes in as clean a manner as possible. My apologies for further polluting the \s-1XML::\s0 space; this is a small and quick module, with easy and compact usage. See XML::SimpleObject::LibXML for the same interface for XML::LibXML.
.SH "USAGE"
.IX Header "USAGE"
.ie n .IP "$xmlobj = new XML::SimpleObject($parser\->parse($XML))" 4
.el .IP "\f(CW$xmlobj\fR = new XML::SimpleObject($parser\->parse($XML))" 4
.IX Item "$xmlobj = new XML::SimpleObject($parser->parse($XML))"
\&\f(CW$parser\fR is an XML::Parser object created with Style \*(L"Tree\*(R":
.Sp
.Vb 1
\&    my $parser = new XML::Parser (ErrorContext => 2, Style => "Tree");
.Ve
.Sp
After creating \f(CW$xmlobj\fR, this object can now be used to browse the \s-1XML\s0 tree with the following methods.
.ie n .IP "$xmlobj\->child('\s-1NAME\s0')" 4
.el .IP "\f(CW$xmlobj\fR\->child('\s-1NAME\s0')" 4
.IX Item "$xmlobj->child('NAME')"
This will return a new XML::SimpleObject object using the child element \s-1NAME.\s0
.ie n .IP "$xmlobj\->children('\s-1NAME\s0')" 4
.el .IP "\f(CW$xmlobj\fR\->children('\s-1NAME\s0')" 4
.IX Item "$xmlobj->children('NAME')"
Called with an argument \s-1NAME,\s0 \fBchildren()\fR will return an array of XML::SimpleObject objects of element \s-1NAME.\s0 Thus, if \f(CW$xmlobj\fR represents the top-level \s-1XML\s0 element, 'children' will return an array of all elements directly below the top-level that have the element name \s-1NAME.\s0
.ie n .IP "$xmlobj\->children" 4
.el .IP "\f(CW$xmlobj\fR\->children" 4
.IX Item "$xmlobj->children"
Called without arguments, '\fBchildren()\fR' will return an array of XML::SimpleObject
s for all children elements of \f(CW$xmlobj\fR. These are not in the order they occur in
 the \s-1XML\s0 document.
.ie n .IP "$xmlobj\->children_names" 4
.el .IP "\f(CW$xmlobj\fR\->children_names" 4
.IX Item "$xmlobj->children_names"
This will return an array of all the names of child elements for \f(CW$xmlobj\fR. You can use this to step through all the children of a given element (see \s-1EXAMPLES\s0). Each name will occur only once, even if multiple children exist with that name.
.ie n .IP "$xmlobj\->value" 4
.el .IP "\f(CW$xmlobj\fR\->value" 4
.IX Item "$xmlobj->value"
If the element represented by \f(CW$xmlobj\fR contains any \s-1PCDATA,\s0 this method will return that text data.
.ie n .IP "$xmlobj\->attribute('\s-1NAME\s0')" 4
.el .IP "\f(CW$xmlobj\fR\->attribute('\s-1NAME\s0')" 4
.IX Item "$xmlobj->attribute('NAME')"
This returns the text for an attribute \s-1NAME\s0 of the \s-1XML\s0 element represented by \f(CW$xmlobj\fR.
.ie n .IP "$xmlobj\->attributes" 4
.el .IP "\f(CW$xmlobj\fR\->attributes" 4
.IX Item "$xmlobj->attributes"
This returns a hash of key/value pairs for all elements in element \f(CW$xmlobj\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Given this \s-1XML\s0 document:
.PP
.Vb 10
\&  <files>
\&    <file type="symlink">
\&      <name>/etc/dosemu.conf</name>
\&      <dest>dosemu.conf\-drdos703.eval</dest>
\&    </file>
\&    <file>
\&      <name>/etc/passwd</name>
\&      <bytes>948</bytes>
\&    </file>
\&  </files>
.Ve
.PP
You can then interpret the tree as follows:
.PP
.Vb 2
\&  my $parser = new XML::Parser (ErrorContext => 2, Style => "Tree");
\&  my $xmlobj = new XML::SimpleObject ($parser\->parse($XML));
\&
\&  print "Files: \en";
\&  foreach my $element ($xmlobj\->child("files")\->children("file"))
\&  {
\&    print "  filename: " . $element\->child("name")\->value . "\en";
\&    if ($element\->attribute("type"))
\&    {
\&      print "    type: " . $element\->attribute("type") . "\en";
\&    }
\&    print "    bytes: " . $element\->child("bytes")\->value . "\en";
\&  }
.Ve
.PP
This will output:
.PP
.Vb 6
\&  Files:
\&    filename: /etc/dosemu.conf
\&      type: symlink
\&      bytes: 20
\&    filename: /etc/passwd
\&      bytes: 948
.Ve
.PP
You can use '\fBchildren()\fR' without arguments to step through all children of a given element:
.PP
.Vb 4
\&  my $filesobj = $xmlobj\->child("files")\->child("file");
\&  foreach my $child ($filesobj\->children) {
\&    print "child: ", $child\->name, ": ", $child\->value, "\en";
\&  }
.Ve
.PP
For the tree above, this will output:
.PP
.Vb 3
\&  child: bytes: 20
\&  child: dest: dosemu.conf\-drdos703.eval
\&  child: name: /etc/dosemu.conf
.Ve
.PP
Using '\fBchildren_names()\fR', you can step through all children for a given element:
.PP
.Vb 5
\&  my $filesobj = $xmlobj\->child("files");
\&  foreach my $childname ($filesobj\->children_names) {
\&      print "$childname has children: ";
\&      print join (", ", $filesobj\->child($childname)\->children_names), "\en";
\&  }
.Ve
.PP
This will print:
.PP
.Vb 1
\&    file has children: bytes, dest, name
.Ve
.PP
By always using '\fBchildren()\fR', you can step through each child object, retrieving them with '\fBchild()\fR'.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dan Brian <dbrian@brians.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), XML::Parser.