LibXML(3pm)

💖 LibXML(3pm) 💖

okay bestie, gather round, because this is XML::SimpleObject::LibXML and it's about to make your whole XML life so much easier. it's a Perl extension that gives you a simple(r) object representation of an XML::LibXML DOM object, and it's from the User Contributed Perl Documentation corner of the manual universe. 🦋

---

✨ NAME ✨

XML::SimpleObject::LibXML — a Perl extension letting you have a simple(r) object representation of an XML::LibXML DOM object. that's it, that's the whole vibe. 🎀

---

🌸 SYNOPSIS 🌸

here's the whole thing in action, no edits, no cap:

  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;

so yes, you either hand it key/value pairs and it builds its own XML::LibXML object for you, or you hand it a parsed tree as the only argument and you're responsible for making the XML::Parser object yourself. pick your fighter. 💅

---

🫶 DESCRIPTION 🫶

bestie. it's a short and simple class. that's the whole personality. it lets you do simple object access to a parsed XML::LibXML tree, with methods for fetching children and attributes in as clean a manner as possible. 👑

the author literally apologizes for further polluting the XML:: namespace — it's a small and quick module, with easy and compact usage. and yeah, some people will rightfully question why anyone would place another interface over the DOM methods that XML::LibXML already provides. valid. but the experience was that people genuinely appreciate the total simplicity this module provides, despite its limitations. and honestly? they ate with that. 🔥

---

💅 USAGE 💅

  $xmlobj = new XML::SimpleObject::LibXML($parser->parse_string($XML))

$parser is an XML::LibXML object.

once $xmlobj exists, you can use it to browse the XML tree with the methods below. let's go one by one, i got you:

• $xmlobj->child('NAME') — this returns a new XML::SimpleObject::LibXML object using the child element NAME. baby object, fresh out the box. 🧚
• $xmlobj->children('NAME') — call it with an argument NAME and children() hands you back an array of XML::SimpleObject::LibXML objects of element NAME. so if $xmlobj represents the top-level XML element, 'children' returns an array of all elements directly below the top-level that have the element name NAME. only the direct ones, bestie, we're not digging deeper for you.
• $xmlobj->children — called with no arguments, 'children()' returns an array of XML::SimpleObjects::LibXML objects for all children elements of $xmlobj. and here's the slay: unlike XML::SimpleObject, XML::SimpleObject::LibXML retains the order of these children. ✨
• $xmlobj->children_names — returns an array of all the names of child elements for $xmlobj. you can use this to step through all the children of a given element (peep the EXAMPLES section), but heads up: multiple elements of the same name will not be identified. so if you've got dupes, use 'children()' instead. not me warning you in advance. 💀
• $xmlobj->value — if the element represented by $xmlobj contains any PCDATA, this method returns that text data. just the text, nothing else.
• $xmlobj->attribute('NAME') — returns the text for an attribute NAME of the XML element represented by $xmlobj.
• $xmlobj->attributes — returns a hash of key/value pairs for all elements in element $xmlobj. yes, a whole hash. enjoy. 🍓

---

🌈 EXAMPLES 🌈

okay so picture this XML document:

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

you can then interpret the tree like this:

  my $parser = new XML::LibXML;
  my $xmlobj = new XML::SimpleObject::LibXML ($parser->parse_string($XML));

  print "Files: \n";
  foreach my $element ($xmlobj->child("files")->children("file"))
  {
    print "  filename: " . $element->child("name")->value . "\n";
    if ($element->attribute("type"))
    {
      print "    type: " . $element->attribute("type") . "\n";
    }
    print "    bytes: " . $element->child("bytes")->value . "\n";
  }

and this will output:

  Files:
    filename: /etc/dosemu.conf
      type: symlink
      bytes: 20
    filename: /etc/passwd
      bytes: 948

---

you can also use 'children()' without arguments to step through all the children of a given element:

  my $filesobj = $xmlobj->child("files")->child("file");
  foreach my $child ($filesobj->children) {
    print "child: ", $child->name, ": ", $child->value, "\n";
  }

for the tree above, this will output:

  child: bytes: 20
  child: dest: dosemu.conf-drdos703.eval
  child: name: /etc/dosemu.conf

---

and using 'children_names()', you can step through all children for a given element:

  my $filesobj = $xmlobj->child("files");
  foreach my $childname ($filesobj->children_names) {
      print "$childname has children: ";
      print join (", ", $filesobj->child($childname)->children_names), "\n";
  }

this will print:

    file has children: bytes, dest, name

---

and the big brain move: by always using 'children()', you can step through each child object and retrieve them with 'child()'. that's the loop, that's the lifestyle. 🔁

---

👑 AUTHOR 👑

Dan Brian <dan@brians.org> — legend behavior, honestly.

---

🦋 SEE ALSO 🦋

perl(1), XML::SimpleObject, XML::Parser, XML::LibXML.

---

bestie reminder: this page is perl v5.34.0, dated 2022-06-28. go forth and parse, you gorgeous creature 💖✨🌸