Provided by: libxml-grove-perl_0.46alpha-14_all bug

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), XML::Grove(3)

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