Templa...in::XML(3pm)

✨ NAME ✨

Template::Plugin::XML — the XML plugin for the Template Toolkit, bestie 🦋

(it's a 3pm page, part of the User Contributed Perl Documentation, and you're literally reading it right now)

---

🌸 SYNOPSIS 🌸

okay so here's the whole vibe, three ways to do it:

[% USE XML;
   dom    = XML.dom('foo.xml');
   xpath  = XML.xpath('bar.xml');
   simple = XML.simple('baz.xml');
   rss    = XML.simple('news.rdf');
%]

[% USE XML(file='foo.xml');
   dom    = XML.dom
   xpath  = XML.xpath
   # ...etc...
%]

[% USE XML(dir='/path/to/xml');
   file  = XML.file('foo.xml' );
   dom   = file.dom
   xpath = file.xpath
   # ...etc...
%]

---

👑 DESCRIPTION 👑

so the Template-XML distribution is giving ✨a whole collection of Template Toolkit plugin modules✨ for working with XML. very "toolbox but make it cute".

Template::Plugin::XML is the front-end module to all the other XML plugin modules — like the main character that introduces you to everybody at the party 🎀. Through it you can access XML files, and directories full of XML files, via the Template::Plugin::XML::File and Template::Plugin::XML::Directory modules (which subclass from Template::Plugin::File and Template::Plugin::Directory respectively, iykyk). Then from there you can:

• build a Document Object Model (DOM) out of an XML file (Template::Plugin::XML::DOM)
• poke at it with XPath queries (Template::Plugin::XML::XPath)
• turn it into a Perl data structure (Template::Plugin::XML::Simple)
• or parse it as an RSS (RDF Site Summary) file

ngl the lore here is kind of iconic: the basic XML plugins were shipped as part of the Template Toolkit all the way until version 2.15, released in May 2006. At that point they got extracted into this separate Template-XML distribution, and an alpha version of this Template::Plugin::XML front-end module got added. so yeah, glow-up era 💅

heads up bestie: Template::Plugin::XML is still in development and not guaranteed to work correctly yet. fr fr. That said, all the other XML plugins are more-or-less exactly as they were in TT version 2.14 and should work as normal. so like, the rest of the squad is fine, it's just this one that's still in its experimental era 😭

For general info on the Template Toolkit, go read the docs for the Template module or <http://template-toolkit.org>. For info on using plugins, see Template::Plugins and "USE" in Template::Manual::Directives. For more on XML itself, see <http://xml.com/>. 🌈

---

🧚 METHODS 🧚

The XML plugin module hands you a bunch of methods that create various other XML plugin objects. obsessed, honestly.

💜 file(name)

Creates a Template::Plugin::XML::File object. It's a subclass of Template::Plugin::File.

💜 dir(path)

Creates a Template::Plugin::XML::Directory object. It's a subclass of Template::Plugin::Directory.

💜 dom()

Generates a Document Object Module from an XML file. You can call this against a directory, a file, or an XML plugin object — as long as the source XML filename is defined somewhere along the line, you're golden ✨

[% dom = XML.dom(filename) %]

[% file = XML.file(filename);
   dom  = file.dom
%]

[% dir = XML.dir(dirname);
   dom = dir.dom(filename)
%]

💜 xpath()

Performs XPath queries on the file. Just like the dom() method, xpath() can be called against a file, a directory, or an XML plugin object.

[% xpath = XML.xpath(filename) %]

[% file  = XML.file(filename);
   xpath = file.xpath
%]

[% dir   = XML.dir(dirname);
   xpath = dir.xpath(filename)
%]

💜 simple()

TODO: as per dom() and xpath() but for XML::Simple

💜 rss()

TODO: as per dom(), xpath() and simple() but for XML::RSS

---

🎀 XML PLUGINS 🎀

These are the XML plugins provided in this distribution — the whole friend group, one by one 💖

🦋 Template::Plugin::XML

Front-end module to the XML plugin collection.

🦋 Template::Plugin::XML::File

This plugin module represents individual XML files. It's a subclass of the Template::Plugin::File module, and it provides the extra dom(), xpath(), simple() and other methods that matter for XML files.

🦋 Template::Plugin::XML::Directory

This plugin module represents directories of XML files. It's a subclass of the Template::Plugin::Directory module and it provides the same extra XML-related methods as Template::Plugin::XML::File.

🦋 Template::Plugin::XML::DOM

Plugin interface giving you access to the XML::DOM module.

[% USE XD = XML.Dom %]
[% dom = XD.parse_file('example.xml') %]
[% pages = dom.getElementsByTagName('page') %]

🦋 Template::Plugin::XML::RSS

Plugin interface giving you access to the XML::RSS module.

[% USE news = XML.RSS('news.rdf') -%]
[% FOREACH item IN news.items -%]
   * [% item.title %]
[% END %]

🦋 Template::Plugin::XML::Simple

Plugin interface giving you access to the XML::Simple module.

[%  USE xml = XML.Simple('example.xml') %]

🦋 Template::Plugin::XML::XPath

Plugin interface giving you access to the XML::XPath module.

[% USE xpath = XML.XPath('example.xml');
   bar = xpath.find('/foo/bar');
%]

---

⭐ AUTHORS ⭐

Credit where credit is due, periodt 👑

• Andy Wardley wrote the Template Toolkit plugin modules, with assistance from Simon Matthews in the case of the XML::DOM plugin.
• Matt Sergeant wrote the XML::XPath module.
• Enno Derksen and Clark Cooper wrote the XML::DOM module.
• Jonathan Eisenzopf wrote the XML::RSS module.
• Grant McLean wrote the XML::Simple module.
• Clark Cooper and Larry Wall wrote the XML::Parser module.
• James Clark wrote the expat library.

---

💖 COPYRIGHT 💖

Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

🔥 SEE ALSO 🔥

Template, Template::Plugins, Template::Plugin::XML::DOM, Template::Plugin::XML::RSS, Template::Plugin::XML::Simple, Template::Plugin::XML::XPath

---

and that's the whole page bestie 🫶 this one's perl v5.34.0, dated 2022-07-04, and it's filed under Templa...in::XML(3pm). go forth and parse some XML, you absolute legend 👑✨