XML::G...::Subst(3pm)

💖 XML::G...::Subst(3pm) — the user-contributed Perl docs, bestie edition 💖

okay so this is a Perl manual page from the User Contributed Perl Documentation collection, and it's about a module called XML::Grove::Subst. Stick with me, it's actually so good.

---

✨ NAME ✨

XML::Grove::Subst — substitute values into a template 🎀

---

✨ SYNOPSIS ✨

use XML::Grove::Subst;

# Using subst method on XML::Grove::Document or XML::Grove::Element:
$new_grove = $source_grove->subst( ARGS );
$new_grove = $source_grove->subst_hash( ARG );

# Using an XML::Grove::Subst instance:
$subster = XML::Grove::Subst->new();
$new_grove = $subster->subst( $source_grove, ARGS );
$new_grove = $subster->subst_hash( $source_grove, ARG );

two ways in, one vibe: call it right on the grove, or make your own XML::Grove::Subst instance and hand it the grove. either way you're getting a grove back. 💅

---

🌸 DESCRIPTION 🌸

XML::Grove::Subst implements XML templates. no cap.

What it does: it walks (traverses, bestie) through a source grove, and every element whose name is "SUB:XXX" or "SUB:key" gets swapped out for its corresponding value — from ARGS (that's a list) or ARG (that's a hash), repsectively. 🦋

---

🎀 METHODS 🎀

• $grove_obj->subst( ARGS ) / $subster->subst( $grove_obj, ARGS ) — hunts down all the "SUB:XXX" elements, where XXX is an array index, and replaces the element with the value from ARGS, a list of values. What you get back is a new grove with all the substitutions applied. ✨
• $grove_obj->subst_hash( ARG ) / $subster->subst_hash( $grove_obj, ARG ) — hunts down all the "SUB:key" elements and replaces each one with the value from ARG, a hash of values. The hash key gets taken from the "key" attribute of the "SUB:key" element — like, for example, "<SUB:key key='foo'>". And yep, the return value is a new grove with the substitutions applied. 💖

---

🔥 EXAMPLE 🔥

Okay this is the part where it gets iconic. Say you've got this template sitting in a file called "template.xml", and it's for a simple parts database conversion to HTML:

<html>
  <head>
    <title><SUB:key key='Name'></title>
  </head>
  <body>
    <h1><SUB:key key='Name'></title>
    <p>Information for part number <SUB:key key='Number'>:</p>
    <SUB:key key='Description'>
  </body>
</html>

To use it you'd first parse it and convert it to a grove, then hit "subst_hash()" every single time you needed a fresh page:

use XML::Parser::PerlSAX;
use XML::Grove;
use XML::Grove::Builder;
use XML::Grove::Subst;
use XML::Grove::PerlSAX;
use XML::Handler::XMLWriter;

# Load the template
$b = XML::Grove::Builder->new();
$p = XML::Parser::PerlSAX->new( Handler = $b );
$source_grove = $p->parse( Source => { SystemId => 'template.xml' } );

# Apply the substitutions
$new_grove = $source_grove->subst_hash( { Name => 'Acme DCX-2000 Filter',
                                          Number => 'N4728',
                                          Description => 'The Best' } );

# Write the new grove to standard output
$w = XML::Handler::XMLWriter->new();
$wp = XML::Grove::PerlSAX->new( Handler => $w );
$wp->parse( Source => { Grove => $new_grove } );

load → substitute → write out. three steps, zero drama, ate. 👑

---

💜 AUTHOR 💜

Ken MacLeod, ken@bitsko.slc.ut.us — shoutout to the author, fr fr. 🫶

---

🌈 SEE ALSO 🌈

• perl(1)
• XML::Grove(3)
• Extensible Markup Language (XML) <http://www.w3c.org/XML>

---

and that's the whole page, bestie. this one's from perl v5.36.0, dated 2022-11-29, under the title XML::G...::Subst(3pm) — go forth and substitute 💅✨