---
name: "XML::Grove::Subst"
section: "3pm"
platform: "linux"
package: "libxml-grove-perl"
version: "0.46alpha-14"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/XML::Grove::Subst"
---

# XML::Grove::Subst(3pm)

substitute values into a template

## 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 );
```

## DESCRIPTION

`"XML::Grove::Subst"` implements XML templates.  `"XML::Grove::Subst"` traverses through a source grove replacing all elements with names \``"SUB:XXX"`' or \``"SUB:key"`' with their corresponding values from ARGS (a list) or ARG (a hash), repsectively.

## METHODS

- $grove\_obj-\>subst( *ARGS* ) =item $subster-\>subst( $grove\_obj, *ARGS* )

  Search for \``"SUB:`*XXX*`"`' elements, where *XXX* is an array index, and replace the element with the value from *ARGS*, a list of values. The return value is a new grove with the substitutions applied.

- $grove\_obj-\>subst\_hash( *ARG* ) =item $subster-\>subst\_hash( $grove\_obj, *ARG* )

  Search for \``"SUB:key"`' elements and replace the element with the value from *ARG*, a hash of values.  The hash key is taken from the \``"key"`' attribute of the \``"SUB:key"`' element, for example, \``"<SUB:key key='foo'>"`'.  The return value is a new grove with the substitutions applied.

## EXAMPLE

The following template, in a file \``"template.xml"`', could be used 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 this template you would first parse it and convert it to a grove, and then use \``"subst_hash()"`' every time you needed a new 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 } );
```

## AUTHOR

Ken MacLeod, ken@bitsko.slc.ut.us

## SEE ALSO

[**perl**(1)](/perl/1.md), **XML::Grove**(3)

Extensible Markup Language (XML) \<http://www.w3c.org/XML\>