/ 
XML-Xalan-0.41
/ XML::Xalan::Transformer

NAME

XML::Xalan::Transformer - Perl interface to XalanTransformer class

SYNOPSIS

use XML::Xalan;

my $tr = new XML::Xalan::Transformer;

# compile a stylesheet file:
my $compiled = $tr->compile_stylesheet_file("foo.xsl");

# compile a stylesheet string:
my $compiled = $tr->compile_stylesheet_string(<<"XSLT");
<?xml version="1.0"?> 
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:template match="doc">
    <out><xsl:value-of select="."/></out>
  </xsl:template>
</xsl:stylesheet>
XSLT

# parse an XML file:
my $parsed = $tr->parse_file("foo.xml");

# parse an XML string:
my $parsed = $tr->parse_string(<<"XML");
<?xml version="1.0"?>
<doc>Hello</doc>
XML

# perform a transformation and store the result into a destination file:
my $res = $tr->transform_to_file($src_file, $xsl_file, $dest_file);
my $res = $tr->transform_to_file($parsed, $xsl_file, $dest_file);
my $res = $tr->transform_to_file($parsed, $compiled, $dest_file);

# perform a transformation and return the result:
my $res = $tr->transform_to_data($src_file, $xsl_file);
my $res = $tr->transform_to_data($parsed, $xsl_file);
my $res = $tr->transform_to_data($parsed, $compiled);

# error checking
die $tr->errstr unless defined $res;

DESCRIPTION

Interface to the XalanTransformer class.

METHODS

new()

Constructor, with no argument. Returns an XML::Xalan::Transformer object.

my $tr = new XML::Xalan::Transformer;
$tr->compile_stylesheet_file($xsl_file)

Compiles a stylesheet file and returns an XML::Xalan::CompiledStylesheet object.

my $compiled = $tr->compile_stylesheet("foo.xsl");
$tr->compile_stylesheet_string($xsl_string)

Compiles a stylesheet string and returns an XML::Xalan::CompiledStylesheet object.

my $compiled = $tr->compile_stylesheet_string(<<"XSLT");
<?xml version="1.0"?> 
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:template match="doc">
    <out><xsl:value-of select="."/></out>
  </xsl:template>
</xsl:stylesheet>
XSLT
$tr->parse_file($xml_file)

Parses an XML file and returns an XML::Xalan::ParsedSource object.

my $parsed = $tr->parse_file("foo.xml");
$tr->parse_string($xml_string)

Parses an XML string and returns an XML::Xalan::ParsedSource object.

my $parsed = $tr->parse_string(<<"XML");
<?xml version="1.0"?>
<doc>Hello</doc>
XML
$tr->transform_to_file($source, $xsl, $dest)

Transforms a source into a specified file. Returns undef on failure. $source could be an XML::Xalan::ParsedSource object or an XML file. $xsl could be an XML::Xalan::CompiledStylesheet object or an XSL file.

$tr->transform_to_file("foo.xml", "foo.xsl", "bar.xml");

To process an XML source with xml-stylesheet processing instruction, pass undef as the second argument.

$tr->transform_to_data($source, $xsl)

Transforms a source and returns the result. $source could be an XML::Xalan::ParsedSource object or an XML file. $xsl could be an XML::Xalan::CompiledStylesheet object or an XSL file.

Example:

my $result = $tr->transform_to_data("foo.xml", "foo.xsl");

To process an XML source with xml-stylesheet processing instruction, pass undef as the second argument.

$tr->transform_to_handler($source, $xsl, *FH, $handler)

Transforms a source and pass the result to a callback handler. $xsl could be an XML::Xalan::CompiledStylesheet object or an XSL file.

If $xsl is an XML::Xalan::CompiledStylesheet object, then $source must be an XML::Xalan::ParsedSource object.

Example:

$out_handler = sub {
    my ($ctx, $mesg);
    print $ctx $mesg;
};
$tr->transform_to_handler(
    $xmlfile, $xslfile, 
    *STDERR, $out_handler);

To process an XML source with xml-stylesheet processing instruction, pass undef as the second argument.

$tr->destroy_stylesheet($compiled_stylesheet)

Removes $compiled_stylesheet from memory.

$tr->destroy_parsed_source($parsed_source)

Removes $parsed_source from memory.

$tr->set_stylesheet_param($key, $val)

Set an XSLT parameter, $key is the param name and val is the assigned value. Returns nothing.

$tr->set_stylesheet_param("id", 777);
$tr->set_stylesheet_param("user", "'johndoe'");
my $res = $tr->transform_to_file($source, $xsl, $dest);
$tr->install_external_function($namespace, $function_name, $function, \%opt)

Install a user defined function as an extension. Returns: nothing. This opens interesting possibilities since now you have a Perl-powered XSLT transformer! :-)

Example:

my $namespace = "http://ExternalFunction.xalan-c++.xml.apache.org";
my $func_name = "square-root";
my $func = sub {
   my @args = @_;
   if (@args != 1) {
       warn "square-root accepts exactly one arg!";
       return undef;
   } 
   return POSIX::sqrt($args[0]);
};

$tr->install_external_function($namespace, $func_name, $func);
my $res = $tr->transform_to_file($source, $xsl, $dest);

The function to install must return a scalar. In case of fatal error, don't die(), but you should return undef.

Another example is a function to remove html tags:

use HTML::Parse;
use HTML::FormatText;

...

$tr->install_external_function($namespace, 'plain-text', 
    sub {
        my $html_text = shift;
        return HTML::FormatText->new->format(parse_html($html_text));
    });

my $parsed = $tr->parse_string(<<"XML");
<?xml version="1.0"?>
<doc>
 <value><![CDATA[<B>Something bold</B><p>and a new paragraph..</p>]]></value>
</doc>
XML

my $compiled = $tr->compile_stylesheet_string(<<'XSLT');
<?xml version="1.0"?> 
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
               xmlns:external="http://ExternalFunction.xalan-c++.xml.apache.org"
       exclude-result-prefixes="external">
<xsl:output method="text"/>
 <xsl:template match="doc">
 <xsl:choose>
   <xsl:when test="function-available('external:plain-text')">
     <xsl:value-of select="external:plain-text(value)"/>
   </xsl:when>
   <xsl:otherwise>
     Function external:plain-text() is not available!
   </xsl:otherwise>
 </xsl:choose>
 </xsl:template>
</xsl:stylesheet>  
XSLT

die $tr->errstr unless $compiled;
my $res = $tr->transform_to_data($parsed, $compiled) or die $tr->errstr;

%attr is an optional hashref attribute. Currently supported attribute is Context, which is default to FALSE. When this is set, then a context node is always passed to the callback function as the first argument. A context node is an XML::Xalan::DOM::Node object.

$tr->uninstall_external_function($namespace, $function_name)

Uninstall a user defined function. Returns: nothing. For example, to uninstall the square-root example above:

my $namespace = "http://ExternalFunction.xalan-c++.xml.apache.org";
my $func_name = "square-root";

$tr->uninstall_external_function($namespace, $func_name);
$tr->create_document_builder()

Returns an XML::Xalan::DocumentBuilder object. This object allows an XML::Xalan::Transformer object to transform input sources parsed by any Perl SAX2 conformant parsers.

See the XML::Xalan::DocumentBuilder pod documentation for usage info.

$tr->destroy_document_builder($document_builder)

Destroy an XML::Xalan::DocumentBuilder object.

$tr->errstr()

Returns current error string.

A NOTE ON OBJECTS CLEANING UP

XML::Xalan::Transformer is an interface to XalanTransformer class, a C++ class which internally keeps a list of compiled stylesheet objects and another list of parsed source objects. Upon an XalanTransformer object destruction, those lists are iterated and each element of them is deleted. Deleting an element which is no longer exist causes a segfault, thereby I do not provide destructors for XML::Xalan::CompiledStylesheet and XML::Xalan::ParsedSource, since these will conflict with one from XML::Xalan::Transformer.

As a consequence, if you write a code which runs an XML::Xalan::Transformer object for a long time and using either compiled stylesheet or parsed source, be careful to call the appropriate destroy_stylesheet() or destroy_parsed_source() to remove it from the internal list (thus, from the memory) once it's no longer used. Otherwise, the memory used will be accumulated regardless of the objects are already out of scope, and the wasted allocated memory will be freed only when the XML::Xalan::Transformer object runs out of scope.

For example:

my $tr = new XML::Xalan::Transformer;
my $compiled = $tr->compile_stylesheet_file($stylesheet);
my $res = $tr->transform_to_file($source, $compiled, $dest);

# $compiled will be used for another stylesheet, then 
# it's necessary to destroy it explicitly first:
$tr->destroy_stylesheet($compiled);

# now it's safe to use for another stylesheet
$compiled = $tr->compile_stylesheet_file($another_stylesheet);

Also, there's no destructor for XML::Xalan::ContentHandler where the instance gets removed as the XML::Xalan::DocumentBuilder that created it is destroyed.

TODO

  • set_stylesheet_param() should accept a hash ref instead, so several parameters can be passed at once.

  • Validation option on parsing.

    At this moment, if you need validation capability, you can use XML::Xalan::DocumentBuilder to make use any validating XML parser which supports Perl SAX2, such as XML::LibXML.

AUTHOR

Edwin Pratomo, edpratomo@cpan.org

SEE ALSO

XML::Xalan::DocumentBuilder(3), XML::Xalan::ParsedSource(3), XML::Xalan::DOM(3).