NAME

XML::XPathScript::Template - XML::XPathScript transformation template

VERSION

version 2.00

SYNOPSIS

    <%
        $t->set( 'important' => { 'pre' => '<blink>', 
                                  'post' => '</blink>',
                                  'prechild' => '<u>',
                                  'postchild' => '</u>',
                                  } );

        # urgent and annoying share the 'pre' and 'post'
        # of important
        $t->copy( 'important' => [ qw/ urgent annoying / ], 
                    [ qw/ pre post / ],        );

        # redHot is a synonym of important
        $t->alias( 'important' => 'redHot' );

     %>
     <%= apply_templates() %>

DESCRIPTION

A stylesheet's template defines the transformations and actions that are performed on the tags of a document as they are processed.

The template of a stylesheet can be accessed via variables $t, $template and $XML::XPathScript::trans.

METHODS

new

    $template = XML::XPathScript::Template->new

Creates and returns a new, empty template.

set

    $template->set( $tag, \%attributes )
    $template->set( \@tags , \%attributes )

Updates the $tag or @tags in the template with the given %attributes.

Thank to the magic of overloading, using the $template as a code reference acts as a shortcut to set.

Example:

    $template->set( 'foo' => { pre => '<a>', post => '</a>' } );
    # or, if you prefer,
    $template->( 'foo' => { pre => '<a>', post => '</a>' } );

copy

    $template->copy( $original_tag, $copy_tag );
    $template->copy( $original_tag, $copy_tag, \@attributes );
    $template->copy( $original_tag, \@copy_tags );
    $template->copy( $original_tag, \@copy_tags, \@attributes );

Copies all attributes (or a subset of them if @attributes is given) of $original_tag to $copy_tag.

Note that subsequent modifications of the original tag will not affect the copies. To bind several tags to the same behavior, see alias.

Example:

    # copy the attributes 'pre' and 'post' of important 
    # to 'urgent' and 'redHot'
    $template->copy( 'important' => [ qw/ urgent redHot / ], 
                        [ qw/ pre post / ] );

import_template

    $template->import_template( $other_template )

Imports another template into the current one.

alias

    $template->alias( $original_tag => $alias_tag )
    $template->alias( $original_tag => \@alias_tags )

Makes the target tags aliases to the original tag. Further modifications that will be done on any of these tags will be reflected on all others.

Example:

    $template->alias( 'foo' => 'bar' );
                            
    # also modifies 'foo'
    $template->set( 'bar' => { pre => '<u>' } );  

is_alias

    @aliases = $template->is_alias( $tag )

Returns all tags that are aliases to $tag.

unalias

    $template->unalias( $tag )

Unmerge $tag of its aliases, if it has any. Further modifications to $tag will not affect the erstwhile aliases, and vice versa.

Example:

    $template->alias( 'foo' => [ qw/ bar baz / ] );
    $template->set( 'foo' => { pre => '<a>' } );    # affects foo, bar and baz
    $template->unalias( 'bar' );
    $template->set( 'bar' => { pre => '<c>' } );    # affects only bar
    $template->set( 'baz' => { pre => '<b>' } );    # affects foo and baz

clear

    $template->clear()
    $template->clear( \@tags )

Delete all tags, or those given by @tags, from the template.

Example:

    $template->clear([ 'foo', 'bar' ]);

dump

    $template->dump()
    $template->dump( @tags )

Returns a pretty-printed dump of the templates. If @tags are specified, only return their templates.

Example:

    <%= $template->dump( 'foo' ) %>
    
    # will yield something like
    #
    # $template = {
    #    foo => {
    #        post => '</bar>',
    #        pre  => '<bar>',
    #    }
    # };

namespace

    my $subtemplate = $template->namespace( $uri );

Returns the sub-template associated to the namespace defined by $uri.

Example:

    $template->set( 'foo' => { 'pre' => 'within default namespace' } );
    my $subtemplate = $template->namespace( 'http://www.www3c.org/blah/' );
    $subtemplate->set( 'foo' => { 'pre' => "within 'blah' namespace" } );

resolve

    $tag = $template->resolve( $namespace, $tagname );
    $tag = $template->resolve( $tagname );

Returns the tag object within $template that matches $namespace and $tagname best. The returned match is the first one met in the following list:

• $namespace:$tagname

• $namespace:*

• $tagname

• *

• undef

Example:

    $template->set( foo => { pre => 'a' } );
    $template->set( '*' => { pre => 'b' } );
    $template->namespace( 'http://blah' )->set( foo => { pre => 'c' } );
    $template->namespace( 'http://blah' )->set( '*' => { pre => 'd' } );

    $template->resolve( 'foo' )->get( 'pre' );  # returns 'a'
    $template->resolve( 'baz' )->get( 'pre' );  # returns 'b'
    $template->resolve( 'http://meeh', 'foo' )->get( 'pre' );  # returns 'a'
    $template->resolve( 'http://blah', 'foo' )->get( 'pre' );  # returns 'c'
    $template->resolve( 'http://blah', 'baz' )->get( 'pre' );  # returns 'd'

BACKWARD COMPATIBILITY

Prior to version 1.0 of XML::XPathScript, the template of a stylesheet was not an object but a simple hash reference. Modifications to the template were done by manipulating the hash directly.

    <%
        # pre-1.0 way of manipulating the template
        $t->{important}{pre}  = '<blink>';
        $t->{important}{post} = '</blink>';
    
        for my $tag ( qw/ urgent redHot / ) {
            for my $attr ( qw/ pre post / ) {
                $t->{$tag}{$attr} = $t->{important}{$attr};
            }
        }

        $t->{ alert } = $t->{ important };
    %>

Don't tell anyone, but as an XML::XPathScript::Template is a blessed hash reference this way of doing things will still work. However, direct manipulation of the template's hash is deprecated. Instead, it is recommended to use the object's access methods.

    <%
        # correct way to manipulate the template
        $t->set( important => { pre => '<blink>', 
                                post => '</blink>',
                                showtag => 1
                                } );

        $t->copy( important => [ qw/ urgent redHot / ], [ qw/ pre post / ] );

        $t->alias( important => alert );
    %>

AUTHORS

• Yanick Champoux <yanick@cpan.org>

• Dominique Quatravaux <domq@cpan.org>

• Matt Sergeant <matt@sergeant.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019, 2018, 2008, 2007 by Matt Sergeant.

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

cpanm XML::XPathScript

perl -MCPAN -e shell
install XML::XPathScript