.\" 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 "LibXML 3pm"
.TH LibXML 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::LibXML \- Perl extension allowing a simple(r) object representation of an XML::LibXML DOM object.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use XML::SimpleObject::LibXML;
\&
\& # Construct with the key/value pairs as argument; this will create its
\& # own XML::LibXML object.
\& my $xmlobj = new XML::SimpleObject(XML => $XML);
\&
\& # ... or construct with the parsed tree as the only argument, having to
\& # create the XML::Parser object separately.
\& my $parser = new XML::LibXML;
\& my $dom = $parser\->parse_file($file); # or $parser\->parse_string($xml);
\& my $xmlobj = new XML::SimpleObject::LibXML ($dom);
\&
\& 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");
\& @children_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::LibXML 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. Some will rightfully question placing another interface over the \s-1DOM\s0 methods provided by XML::LibXML, but my experience is that people appreciate the total simplicity provided by this module, despite its limitations.
.SH "USAGE"
.IX Header "USAGE"
.ie n .IP "$xmlobj = new XML::SimpleObject::LibXML($parser\->parse_string($XML))" 4
.el .IP "\f(CW$xmlobj\fR = new XML::SimpleObject::LibXML($parser\->parse_string($XML))" 4
.IX Item "$xmlobj = new XML::SimpleObject::LibXML($parser->parse_string($XML))"
\&\f(CW$parser\fR is an XML::LibXML object.
.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::LibXML 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::LibXML 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::SimpleObjects::LibXML objects for all children elements of \f(CW$xmlobj\fR. Unlike XML::SimpleObject, XML::SimpleObject::LibXML retains the order of these children.
.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), although multiple elements of the same name will not be identified. Use '\fBchildren()\fR' instead.
.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
\&
\&
\& /etc/dosemu.conf
\& dosemu.conf\-drdos703.eval
\&
\&
\& /etc/passwd
\& 948
\&
\&
.Ve
.PP
You can then interpret the tree as follows:
.PP
.Vb 2
\& my $parser = new XML::LibXML;
\& my $xmlobj = new XML::SimpleObject::LibXML ($parser\->parse_string($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
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), XML::SimpleObject, XML::Parser, XML::LibXML.