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. Uses the output_as_bytes method to produce the output document.
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.

AUTHOR

Jeremy Mates, <jmates@sial.org>

COPYRIGHT AND LICENSE

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

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