XML::XSLT - A perl module for processing XSLT

Content-Type: text/xml Content-Length: 17259

# NAME

XML::XSLT - A perl module for processing XSLT

# SYNOPSIS

    use XML::XSLT;

    my $xslt = XML::XSLT->new ($xsl, warnings => 1);

    $xslt->transform ($xmlfile);

    print $xslt->toString;

    $xslt->dispose();

# DESCRIPTION

This module implements the W3C's XSLT specification. The goal is full implementation of this spec, but we have not yet achieved that. However, it already works well. See XML::XSLT Commands for the current status of each command.

XML::XSLT makes use of XML::DOM and LWP::Simple, while XML::DOM uses XML::Parser. Therefore XML::Parser, XML::DOM and LWP::Simple have to be installed properly for XML::XSLT to run.

# Specifying Sources

The stylesheets and the documents may be passed as filenames, file handles regular strings, string references or DOM-trees. Functions that require sources (e.g. new), will accept either a named parameter or simply the argument.

Either of the following are allowed:

    my $xslt = XML::XSLT->new($xsl);
    my $xslt = XML::XSLT->new(Source => $xsl);

In documentation, the named parameter `Source' is always shown, but it is never required.

## METHODS

- new(Source => $xml [, %args])

  Returns a new XSLT parser object. Valid flags are:

- DOMparser_args

  Hashref of arguments to pass to the XML::DOM::Parser object's parse method.

- variables

  Hashref of variables and their values for the stylesheet.

- base

  Base of URL for file inclusion.

- debug

  Turn on debugging messages.

- warnings

  Turn on warning messages.

- indent

  Starting amount of indention for debug messages. Defaults to 0.

- indent_incr

  Amount to indent each level of debug message. Defaults to 1.

- open_xml(Source => $xml [, %args])

  Gives the XSLT object new XML to process. Returns an XML::DOM object corresponding to the XML.

- base

  The base URL to use for opening documents.

- parser_args

  Arguments to pase to the parser.

- open_xsl(Source => $xml, [, %args])

  Gives the XSLT object a new stylesheet to use in processing XML. Returns an XML::DOM object corresponding to the stylesheet. Any arguments present are passed to the XML::DOM::Parser.

- base

  The base URL to use for opening documents.

- parser_args

  Arguments to pase to the parser.

- process(%variables)

  Processes the previously loaded XML through the stylesheet using the variables set in the argument.

- transform(Source => $xml [, %args])

  Processes the given XML through the stylesheet. Returns an XML::DOM object corresponding to the transformed XML. Any arguments present are passed to the XML::DOM::Parser.

- serve(Source => $xml [, %args])

  Processes the given XML through the stylesheet. Returns a string containg the result. Example:

      use XML::XSLT qw(serve);

      $xslt = XML::XSLT->new($xsl);
      print $xslt->serve $xml;

- http_headers

  If true, then prepends the appropriate HTTP headers (e.g. Content-Type, Content-Length);

  Defaults to true.

- xml_declaration

  If true, then the result contains the appropriate <?xml?> header.

  Defaults to true.

- xml_version

  The version of the XML.

  Defaults to 1.0.

- doctype

  The type of DOCTYPE this document is. Defaults to SYSTEM.

- toString

  Returns the result of transforming the XML with the stylesheet as a string.

- to_dom

  Returns the result of transforming the XML with the stylesheet as an XML::DOM object.

- media_type

  Returns the media type (aka mime type) of the object.

- dispose

  Executes the dispose method on each XML::DOM object.

# XML::XSLT Commands

- xsl:apply-imports no

  Not supported yet.

- xsl:apply-templates limited

  Attribute 'select' is supported to the same extent as xsl:value-of supports path selections.

  Not supported yet: - attribute 'mode' - xsl:sort and xsl:with-param in content

- xsl:attribute partially

  Adds an attribute named to the value of the attribute 'name' and as value the stringified content-template.

  Not supported yet: - attribute 'namespace'

- xsl:attribute-set yes

  Partially

- xsl:call-template yes

  Takes attribute 'name' which selects xsl:template's by name.

  Weak support: - xsl:with-param (select attrib not supported)

  Not supported yet: - xsl:sort

- xsl:choose yes

  Tests sequentially all xsl:whens until one succeeds or until an xsl:otherwise is found. Limited test support, see xsl:when

- xsl:comment yes

  Supported.

- xsl:copy partially
- xsl:copy-of limited

  Attribute 'select' functions as well as with xsl:value-of

- xsl:decimal-format no

  Not supported yet.

- xsl:element yes
- xsl:fallback no

  Not supported yet.

- xsl:for-each limited

  Attribute 'select' functions as well as with xsl:value-of

  Not supported yet: - xsl:sort in content

- xsl:if limited

  Identical to xsl:when, but outside xsl:choose context.

- xsl:import no

  Not supported yet.

- xsl:include yes

  Takes attribute href, which can be relative-local, absolute-local as well as an URL (preceded by identifier http:).

- xsl:key no

  Not supported yet.

- xsl:message no

  Not supported yet.

- xsl:namespace-alias no

  Not supported yet.

- xsl:number no

  Not supported yet.

- xsl:otherwise yes

  Supported.

- xsl:output limited

  Only the initial xsl:output element is used. The "text" output method is not supported, but shouldn't be difficult to implement. Only the "doctype-public", "doctype-system", "omit-xml-declaration", "method", and "encoding" attributes have any support.

- xsl:param experimental

  Synonym for xsl:variable (currently). See xsl:variable for support.

- xsl:preserve-space no

  Not supported yet. Whitespace is always preserved.

- xsl:processing-instruction yes

  Supported.

- xsl:sort no

  Not supported yet.

- xsl:strip-space no

  Not supported yet. No whitespace is stripped.

- xsl:stylesheet limited

  Minor namespace support: other namespace than 'xsl:' for xsl-commands is allowed if xmlns-attribute is present. xmlns URL is verified. Other attributes are ignored.

- xsl:template limited

  Attribute 'name' and 'match' are supported to minor extend. ('name' must match exactly and 'match' must match with full path or no path)

  Not supported yet: - attributes 'priority' and 'mode'

- xsl:text yes

  Supported.

- xsl:transform limited

  Synonym for xsl:stylesheet

- xsl:value-of limited

  Inserts attribute or element values. Limited support:

  <xsl:value-of select="."/>

  <xsl:value-of select="/root-elem"/>

  <xsl:value-of select="elem"/>

  <xsl:value-of select="//elem"/>

  <xsl:value-of select="elem[n]"/>

  <xsl:value-of select="//elem[n]"/>

  <xsl:value-of select="@attr"/>

  <xsl:value-of select="text()"/>

  <xsl:value-of select="processing-instruction()"/>

  <xsl:value-of select="comment()"/>

  and combinations of these.

  Not supported yet: - attribute 'disable-output-escaping'

- xsl:variable experimental

  Very limited. It should be possible to define a variable and use it with &lt;xsl:value select="$varname" /&gt; within the same template.

- xsl:when limited

  Only inside xsl:choose. Limited test support:

  <xsl:when test="@attr='value'">

  <xsl:when test="elem='value'">

  <xsl:when test="path/[@attr='value']">

  <xsl:when test="path/[elem='value']">

  <xsl:when test="path">

  path is supported to the same extend as with xsl:value-of

- xsl:with-param experimental

  It is currently not functioning. (or is it?)

# SUPPORT

General information, bug reporting tools, the latest version, mailing lists, etc. can be found at the XML::XSLT homepage:

    http://xmlxslt.sourceforge.net/

# DEPRECATIONS

Methods and interfaces from previous versions that are not documented in this version are deprecated. Each of these deprecations can still be used but will produce a warning when the deprecation is first used. You can use the old interfaces without warnings by passing new() the flag use_deprecated . Example:

    $parser = XML::XSLT->new($xsl, "FILE",
                             use_deprecated => 1);

The deprecated methods will disappear by the time a 1.0 release is made.

The deprecated methods are :

- output_string

  use toString instead

- result_string

  use toString instead

- output

  use toString instead

- result

  use toString instead

- result_mime_type

  use media_type instead

- output_mime_type

  use media_type instead

- result_tree

  use to_dom instead

- output_tree

  use to_dom instead

- transform_document

  use transform instead

- process_project

  use process instead

- open_project

  use Source argument to new() and transform instead.

- print_output

  use serve() instead.

# BUGS

Yes.

# HISTORY

Geert Josten and Egon Willighagen developed and maintained XML::XSLT up to version 0.22. At that point, Mark Hershberger started moving the project to Sourceforge and began working on it with Bron Gondwana.

# LICENCE

Copyright (c) 1999 Geert Josten & Egon Willighagen. All Rights Reserverd. This module is free software, and may be distributed under the same terms and conditions as Perl.

# AUTHORS

Geert Josten <gjosten@sci.kun.nl>

Egon Willighagen <egonw@sci.kun.nl>

Mark A. Hershberger <mah@everybody.org>

Bron Gondwana <perlcode@brong.net>

Jonathan Stowe <jns@gellyfish.com>

# SEE ALSO

XML::DOM , LWP::Simple , XML::Parser