Unix/Linux Go Back    


CentOS 7.0 - man page for xml::libxslt (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


LibXSLT(3)		       User Contributed Perl Documentation		       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.

       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).

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.

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 otherwised.

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.

MAINTAINER
       Petr Pajas , pajas@matfyz.org

BUGS
       Please report bugs via

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

SEE ALSO
       XML::LibXML

perl v5.16.3				    2013-01-23				       LibXSLT(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:22 AM.