NAME

XML::ApplyXSLT - convert XML data with XSLT stylesheet files

SYNOPSIS

  use XML::ApplyXSLT;
  $xapply = XML::ApplyXSLT->new;

  # parse an XML document by various means
  $doc = $xapply->parse( $xml_filename ) || die $xapply->errorstring;
  $doc = $xapply->parse( \$xml_string );
  $doc = $xapply->parse( \*FILEHANDLE );

  # set global defaults, such as path, style, and class to lookup
  # stylesheets from the filesystem
  $xapply->config({ 
    class => 'test',
    style => 'default'
  });

  # load rules
  $xapply->rules( $rules_filehandle );

  # determine information about a given document (via rules)
  ( $filedata, $defaults, $params ) = $xapply->study( $doc, $xml_filename );

  # extra code here to mess with defaults, check parameters, etc.

  # transform the previously parsed XML document via stylesheet found
  # via path, class, and style lookups
  ( $docref, $details ) = $xapply->transform( $doc, 
    default => $defaults, param => $params);
  print $$docref;

DESCRIPTION

This module converts XML documents with XSLT files. As different stylesheets could be applied to a particular XML format depending on the context, methods are provided to determine what class and style the XML data belongs to by DOCTYPE, the root element name, or Processing Instructions. The class and style information is used to construct a path to a stylesheet file residing somewhere on the filesystem, which is loaded and used to convert the XML data. The class and style information can also be set manually, if only a single stylesheet will be used.

Stylesheets are parsed and stored in memory to avoid reparsing the same stylesheet for multiple XML documents.

The XML::LibXML and XML::LibXSLT modules provide XML and XSLT parsing.

As this is a new module, the methods may change as more is learned about the needs of command line, CGI, or mod_perl based interfaces.

METHODS

Looking at the code in t/1.t probably best bet for usage at this point.

new

config

Accepts hash to alter 'default' used to hold path, class, and style (or anything else) information, or returns said default hash by reference.

config_libxml

Passes configuration methods by hash to XML::LibXML object.

config_libxslt

Passes configuration methods by hash to XML::LibXSLT object.

errorstring

Last error message from module.

debugstring

May contain XML::LibXML or XML::LibXSLT error data, which could include unsafe characters or sensitive file data due to parse failures.

parse

Parses XML document by filename, string, or filehandle. Returns XML::LibXML object.

filedata

Returns information about a filename. See also docdata. Called by study.

docdata

Parses XML document information, such as the root name and DOCTYPE identification strings. See also filedata. Called by study.

rules

Accepts filehandle to load rules from. These rules are used by study.

apply_rules

Internal routine used by style to apply rules to document data.

study

Runs filedata and docdata information past rules to figure out how to classify the XML document in question.

expand

Expands %{keyword} style statements in passed data against a hash of lookup values. Used by get_style to expand the path default to find the location of the stylesheet to use.

transform

Transforms XML::LibXML document with XML:::LibXSLT after looking up the stylesheet to use via get_style based of off 'default' data.

query_xpath

Internal routine, used by docdata.

get_style

Internal, for stylesheet lookup.

RULES

Rules are used to classify and set defaults and parameter values for XML documents, based on the XML document info. A rule is a single line, and may be extended by placing a backslash at the end of the line. Lines beginning with an octothorpe (#) will be ignored, as will blank lines. An example set of rules follow.

  # set a default for everything
  defaults: path=/var/www/htdocs/xsl/%{class}/%{style}.xsl \
    style=default

  # when in specific subdirectory, alter path default
  dirname sub "site/example.org/htdocs" \
    path=/var/www/site/example.org/htdocs/xsl/%{class}/%{style}.xsl

  # handle different document types
  rootname eq "eolas" stop \
    defaults: class=eolas \
    params: request.preferred_style=%{style}

  rootname eq "changelog" stop class=cvs2cl \
    params: request.preferred_style=%{style}

  doctype eq "-//OASIS//DTD DocBook XML V4.2//EN" stop class=docbook42

BUGS

Reporting Bugs

Newer versions of this module may be available from CPAN.

If the bug is in the latest version, send a report to the author. Patches that fix problems or add new features are welcome.

Known Issues

No known issues, though see source for TODO and other comments.

SEE ALSO

AxKit, for more complex XML mangling needs.

The supporting modules XML::LibXML and XML::LibXSLT.

http://www.w3.org/TR/REC-xml

http://www.w3.org/TR/xslt

AUTHOR

Jeremy Mates, <jmates@sial.org>

COPYRIGHT AND LICENSE

The author disclaims all copyrights and releases this module into the public domain.