XML::LibXSLT(3)       User Contributed Perl Documentation      XML::LibXSLT(3)


NAME
       XML::LibXSLT - Interface to the GNOME libxslt library

SYNOPSIS
         use XML::LibXSLT;
         use XML::LibXML;

         my $xslt = XML::LibXSLT->new();

         my $source = XML::LibXML->load_xml(location => 'foo.xml');
         my $style_doc = XML::LibXML->load_xml(location=>'bar.xsl', no_cdata=>1);

         my $stylesheet = $xslt->parse_stylesheet($style_doc);

         my $results = $stylesheet->transform($source);

         print $stylesheet->output_as_bytes($results);

DESCRIPTION
       This module is an interface to the GNOME project's libxslt. This is an
       extremely good XSLT engine, highly compliant and also very fast. I have
       tests showing this to be more than twice as fast as Sablotron.

OPTIONS
       XML::LibXSLT has some global options. Note that these are probably not
       thread or even fork safe - so only set them once per process. Each one
       of these options can be called either as class methods, or as instance
       methods. However either way you call them, it still sets global
       options.

       Each of the option methods returns its previous value, and can be
       called without a parameter to retrieve the current value.

       max_depth
             XML::LibXSLT->max_depth(1000);

           This option sets the maximum recursion depth for a stylesheet. See
           the very end of section 5.4 of the XSLT specification for more
           details on recursion and detecting it. If your stylesheet or XML
           file requires seriously deep recursion, this is the way to set it.
           Default value is 250.

       max_vars
             XML::LibXSLT->max_vars(100_000);

           This option sets the maximum number of variables for a stylesheet.
           If your stylesheet or XML file requires many variables, this is the
           way to increase their limit. Default value is system-specific and
           may vary.

       debug_callback
             XML::LibXSLT->debug_callback($subref);

           Sets a callback to be used for debug messages. If you don't set
           this, debug messages will be ignored.

       register_function
             XML::LibXSLT->register_function($uri, $name, $subref);
             $stylesheet->register_function($uri, $name, $subref);

           Registers an XSLT extension function mapped to the given URI. For
           example:

             XML::LibXSLT->register_function("urn:foo", "bar",
               sub { scalar localtime });

           Will register a "bar" function in the "urn:foo" namespace (which
           you have to define in your XSLT using "xmlns:...") that will return
           the current date and time as a string:

             <xsl:stylesheet version="1.0"
               xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
               xmlns:foo="urn:foo">
             <xsl:template match="/">
               The time is: <xsl:value-of select="foo:bar()"/>
             </xsl:template>
             </xsl:stylesheet>

           Parameters can be in whatever format you like. If you pass in a
           nodelist it will be a XML::LibXML::NodeList object in your perl
           code, but ordinary values (strings, numbers and booleans) will be
           ordinary perl scalars. If you wish them to be
           "XML::LibXML::Literal", "XML::LibXML::Number" and
           "XML::LibXML::Number" values respectively then set the variable
           $XML::LibXSLT::USE_LIBXML_DATA_TYPES to a true value. Return values
           can be a nodelist or a plain value - the code will just do the
           right thing.  But only a single return value is supported (a list
           is not converted to a nodelist).

       register_element
                   $stylesheet->register_element($uri, $name, $subref)

           Registers an XSLT extension element $name mapped to the given URI.
           For example:

             $stylesheet->register_element("urn:foo", "hello", sub {
                     my $name = $_[2]->getAttribute( "name" );
                     return XML::LibXML::Text->new( "Hello, $name!" );
             });

           Will register a "hello" element in the "urn:foo" namespace that
           returns a "Hello, X!" text node. You must define this namespace in
           your XSLT and include its prefix in the
           "extension-element-prefixes" list:

             <xsl:stylesheet version="1.0"
               xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
               xmlns:foo="urn:foo"
                   extension-element-prefixes="foo">
             <xsl:template match="/">
               <foo:hello name="bob"/>
             </xsl:template>
             </xsl:stylesheet>

           The callback is passed the input document node as $_[1] and the
           stylesheet node as $_[2]. $_[0] is reserved for future use.

API
       The following methods are available on the new XML::LibXSLT object:

       parse_stylesheet($stylesheet_doc)
           $stylesheet_doc here is an XML::LibXML::Document object (see
           XML::LibXML) representing an XSLT file. This method will return a
           XML::LibXSLT::Stylesheet object, or undef on failure. If the XSLT
           is invalid, an exception will be thrown, so wrap the call to
           parse_stylesheet in an eval{} block to trap this.

           IMPORTANT: $stylesheet_doc should not contain CDATA sections,
           otherwise libxslt may misbehave. The best way to assure this is to
           load the stylesheet with no_cdata flag, e.g.

             my $stylesheet_doc = XML::LibXML->load_xml(location=>"some.xsl", no_cdata=>1);

       parse_stylesheet_file($filename)
           Exactly the same as the above, but parses the given filename
           directly.

Input Callbacks
       To define XML::LibXSLT or XML::LibXSLT::Stylesheet specific input
       callbacks, reuse the XML::LibXML input callback API as described in
       XML::LibXML::InputCallback(3).

       input_callbacks($icb)
           Enable the callbacks in $icb only for this XML::LibXSLT object.
           $icb should be a "XML::LibXML::InputCallback" object. This will
           call "init_callbacks" and "cleanup_callbacks" automatically during
           parsing or transformation.

Security Callbacks
       To create security preferences for the transformation see
       XML::LibXSLT::Security. Once the security preferences have been defined
       you can apply them to an XML::LibXSLT or XML::LibXSLT::Stylesheet
       instance using the security_callbacks() method.

XML::LibXSLT::Stylesheet
       The main API is on the stylesheet, though it is fairly minimal.

       One of the main advantages of XML::LibXSLT is that you have a generic
       stylesheet object which you call the transform() method passing in a
       document to transform. This allows you to have multiple transformations
       happen with one stylesheet without requiring a reparse.

       transform(doc, %params)
             my $results = $stylesheet->transform($doc, foo => "'bar'");
             print $stylesheet->output_as_bytes($results);

           Transforms the passed in XML::LibXML::Document object, and returns
           a new XML::LibXML::Document. Extra hash entries are used as
           parameters.  Be sure to keep in mind the caveat with regard to
           quotes explained in the section on "Parameters" below.

       transform_file(filename, %params)
             my $results = $stylesheet->transform_file($filename, bar => "'baz'");

           Note the string parameter caveat, detailed in the section on
           "Parameters" below.

       output_as_bytes(result)
           Returns a scalar that is the XSLT rendering of the
           XML::LibXML::Document object using the desired output format
           (specified in the xsl:output tag in the stylesheet). Note that you
           can also call $result->toString, but that will *always* output the
           document in XML format which may not be what you asked for in the
           xsl:output tag. The scalar is a byte string encoded in the output
           encoding specified in the stylesheet.

       output_as_chars(result)
           Like output_as_bytes(result), but always return the output as
           (UTF-8 encoded) string of characters.

       output_string(result)
           DEPRECATED: This method is something between
           output_as_bytes(result) and output_as_bytes(result): The scalar
           returned by this function appears to Perl as characters (UTF8 flag
           is on) if the output encoding specified in the XSLT stylesheet was
           UTF-8 and as bytes if no output encoding was specified or if the
           output encoding was other than UTF-8. Since the behavior of this
           function depends on the particular stylesheet, it is deprecated in
           favor of output_as_bytes(result) and output_as_chars(result).

       output_fh(result, fh)
           Outputs the result to the filehandle given in $fh.

       output_file(result, filename)
           Outputs the result to the file named in $filename.

       output_encoding()
           Returns the output encoding of the results. Defaults to "UTF-8".

       output_method()
           Returns the value of the "method" attribute from "xsl:output"
           (usually "xml", "html" or "text"). If this attribute is
           unspecified, the default value is initially "xml". If the transform
           method is used to produce an HTML document, as per the XSLT spec
           <http://www.w3.org/TR/xslt#output>, the default value will change
           to "html". To override this behavior completely, supply an
           "xsl:output" element in the stylesheet source document.

       media_type()
           Returns the value of the "media-type" attribute from "xsl:output".
           If this attribute is unspecified, the default media type is
           initially "text/xml". This default changes to "text/html" under the
           same conditions as output_method.

       input_callbacks($icb)
           Enable the callbacks in $icb only for this stylesheet. $icb should
           be a "XML::LibXML::InputCallback" object. This will call
           "init_callbacks" and "cleanup_callbacks" automatically during
           transformation.

       transform_into_chars(doc, %params)
           Combines transform() and output_as_chars().

           (Added in version 2.0000 .)

Parameters
       LibXSLT expects parameters in XPath format. That is, if you wish to
       pass a string to the XSLT engine, you actually have to pass it as a
       quoted string:

         $stylesheet->transform($doc, param => "'string'");

       Note the quotes within quotes there!

       Obviously this isn't much fun, so you can make it easy on yourself:

         $stylesheet->transform($doc, XML::LibXSLT::xpath_to_string(
               param => "string"
               ));

       The utility function does the right thing with respect to strings in
       XPath, including when you have quotes already embedded within your
       string.

XML::LibXSLT::Security
       Provides an interface to the libxslt security framework by allowing
       callbacks to be defined that can restrict access to various resources
       (files or URLs) during a transformation.

       The libxslt security framework allows callbacks to be defined for
       certain actions that a stylesheet may attempt during a transformation.
       It may be desirable to restrict some of these actions (for example,
       writing a new file using exsl:document). The actions that may be
       restricted are:

       read_file
           Called when the stylesheet attempts to open a local file (ie: when
           using the document() function).

       write_file
           Called when an attempt is made to write a local file (ie: when
           using the exsl:document element).

       create_dir
           Called when a directory needs to be created in order to write a
           file.

           NOTE: By default, create_dir is not allowed. To enable it a
           callback must be registered.

       read_net
           Called when the stylesheet attempts to read from the network.

       write_net
           Called when the stylesheet attempts to write to the network.

   Using XML::LibXSLT::Security
       The interface for this module is similar to XML::LibXML::InputCallback.
       After creating a new instance you may register callbacks for each of
       the security options listed above. Then you apply the security
       preferences to the XML::LibXSLT or XML::LibXSLT::Stylesheet object
       using security_callbacks().

         my $security = XML::LibXSLT::Security->new();
         $security->register_callback( read_file  => $read_cb );
         $security->register_callback( write_file => $write_cb );
         $security->register_callback( create_dir => $create_cb );
         $security->register_callback( read_net   => $read_net_cb );
         $security->register_callback( write_net  => $write_net_cb );

         $xslt->security_callbacks( $security );
          -OR-
         $stylesheet->security_callbacks( $security );

       The registered callback functions are called when access to a resource
       is requested. If the access should be allowed the callback should
       return 1, if not it should return 0. The callback functions should
       accept the following arguments:

       $tctxt
           This is the transform context (XML::LibXSLT::TransformContext). You
           can use this to get the current XML::LibXSLT::Stylesheet object by
           calling stylesheet().

             my $stylesheet = $tctxt->stylesheet();

           The stylesheet object can then be used to share contextual
           information between different calls to the security callbacks.

       $value
           This is the name of the resource (file or URI) that has been
           requested.

       If a particular option (except for "create_dir") doesn't have a
       registered callback, then the stylesheet will have full access for that
       action.

   Interface
       new()
           Creates a new XML::LibXSLT::Security object.

       register_callback( $option, $callback )
           Registers a callback function for the given security option (listed
           above).

       unregister_callback( $option )
           Removes the callback for the given option. This has the effect of
           allowing all access for the given option (except for "create_dir").

BENCHMARK
       Included in the distribution is a simple benchmark script, which has
       two drivers - one for LibXSLT and one for Sablotron. The benchmark
       requires the testcases files from the XSLTMark distribution which you
       can find at http://www.datapower.com/XSLTMark/

       Put the testcases directory in the directory created by this
       distribution, and then run:

         perl benchmark.pl -h

       to get a list of options.

       The benchmark requires XML::XPath at the moment, but I hope to factor
       that out of the equation fairly soon. It also requires Time::HiRes,
       which I could be persuaded to factor out, replacing it with
       Benchmark.pm, but I haven't done so yet.

       I would love to get drivers for XML::XSLT and XML::Transformiix, if you
       would like to contribute them. Also if you get this running on Win32,
       I'd love to get a driver for MSXSLT via OLE, to see what we can do
       against those Redmond boys!

LIBRARY VERSIONS
       For debugging purposes, XML::LibXSLT provides version information about
       the libxslt C library (but do not confuse it with the version number of
       XML::LibXSLT module itself, i.e. with $XML::LibXSLT::VERSION).
       XML::LibXSLT issues a warning if the runtime version of the library is
       less then the compile-time version.

       XML::LibXSLT::LIBXSLT_VERSION()
           Returns version number of libxslt library which was used to compile
           XML::LibXSLT as an integer. For example, for libxslt-1.1.18, it
           will return 10118.

       XML::LibXSLT::LIBXSLT_DOTTED_VERSION()
           Returns version number of libxslt library which was used to compile
           XML::LibXSLT as a string, e.g. "1.1.18".

       XML::LibXSLT::LIBXSLT_RUNTIME_VERSION()
           Returns version number of libxslt library to which XML::LibXSLT is
           linked at runtime (either dynamically or statically). For example,
           for example, for libxslt.so.1.1.18, it will return 10118.

       XML::LibXSLT::HAVE_EXLT()
           Returns 1 if the module was compiled with libexslt, 0 otherwise.

LICENSE
       This is free software, you may use it and distribute it under the same
       terms as Perl itself.

       Copyright 2001-2009, AxKit.com Ltd.

AUTHOR
       Matt Sergeant, matt@sergeant.org

       Security callbacks implementation contributed by Shane Corgatelli.

       Petr Pajas , pajas@matfyz.org

MAINTAINER
       Shlomi Fish, <https://www.shlomifish.org/me/contact-me/> .

BUGS
       Please report bugs via

         http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXSLT

SEE ALSO
       XML::LibXML , XML::LibXSLT::Quick .

perl v5.40.0                      2024-09-01                   XML::LibXSLT(3)