XML::LibXSLT man page on OpenServer

Man page or keyword search:  
man Server   5388 pages
apropos Keyword Search (all sections)
Output format
OpenServer logo
[printable version]

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 $parser = XML::LibXML->new();
	 my $xslt = XML::LibXSLT->new();

	 my $source = $parser->parse_file('foo.xml');
	 my $style_doc = $parser->parse_file('bar.xsl');

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

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

	 print $stylesheet->output_string($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);

	   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::Lit-
	   eral", "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).

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

       parse_stylesheet($doc)
	   $doc here is an XML::LibXML::Document object (see XML::LibXML) rep-
	   resenting 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.

       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 call-
       backs, 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 => "value);

	   Transforms the passed in XML::LibXML::Document object, and returns
	   a new XML::LibXML::Document. Extra hash entries are used as parame-
	   ters.

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

       output_string(result)
	   Returns a scalar that is the XSLT rendering of the
	   XML::LibXML::Document object using the desired output format (spec-
	   ified in the xsl:output tag in the stylesheet). Note that you can
	   also call $result->toString, but that will *always* output the doc-
	   ument in XML format which may not be what you asked for in the
	   xsl:output tag.

	   Important note: The string returned by this function appears to
	   Perl as characters if the output encoding was specified as UTF-8
	   and as bytes if no output encoding was specified or if the output
	   encoding was different from UTF-8. See also "out-
	   put_as_bytes(result)" and "output_as_chars(result)".

       output_as_bytes(result)
	   Like "output_string(result)", but always return the output as a
	   byte string encoded in the output encoding specified in the
	   stylesheet.

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

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

       media_type()
	   Returns the output media_type of the results. Defaults to
	   "text/html".

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 cer-
       tain actions that a stylesheet may attempt during a transformation. It
       may be desirable to restrict some of these actions (for example, writ-
       ing 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 call-
	   back 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 prefer-
       ences 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 informa-
	   tion 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 regis-
       tered 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 distribu-
       tion, 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 Bench-
       mark.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.15, it
	   will return 10115.

       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.15".

       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.15, it will return 10115.

AUTHOR
       Matt Sergeant, matt@sergeant.org

       Security callbacks implementation contributed by Shane Corgatelli.

       Copyright 2001-2006, AxKit.com Ltd. All rights reserved.

SEE ALSO
       XML::LibXML

perl v5.8.8			  2006-11-17			    LibXSLT(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OpenServer

List of man pages available for OpenServer

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net