#include <XsltExecutable.h>

Public Member Functions
void	setcwd (const char *cwd)
	set the current working directory (cwd). This method also applies to the

void	setBaseOutputURI (const char *baseURI)
	Set the base output URI.

void	setGlobalContextItem (XdmItem *value)

void	setGlobalContextFromFile (const char *filename)

XsltExecutable *	clone ()
	Create a clone object of this XsltExecutable object.

void	setInitialMode (const char *modeName)
	Set the initial mode for the transformation.

void	setInitialMatchSelection (XdmValue *selection)

void	setInitialMatchSelectionAsFile (const char *filename)

void	setOutputFile (const char *outfile)

void	setResultAsRawValue (bool option)

void	setParameter (const char name, XdmValue value)

std::map< std::string, XdmValue * > &	getResultDocuments ()

XdmValue *	getParameter (const char *name, bool withParam=true)

bool	removeParameter (const char *name)

bool	removeProperty (const char *name)

void	setProperty (const char name, const char value)

void	setInitialTemplateParameters (std::map< std::string, XdmValue * > parameters, bool tunnel)

const char *	getProperty (const char *name)

std::map< std::string, XdmValue * > &	getParameters ()
	Get all parameters as a std::map.

std::map< std::string, std::string > &	getProperties ()
	Get all properties as a std::map.

void	clearParameters (bool deleteValues=false)
	Clear parameter values set.

void	clearProperties ()
	Clear property values set.

XdmValue **	createXdmValueArray (int len)

char **	createCharArray (int len)

void	deleteXdmValueArray (XdmValue **arr, int len)
	Utility method for Python API - internal use only.

void	setSaveXslMessage (bool show, const char *filename=nullptr)

void	setCaptureResultDocuments (bool flag, bool rawResults=false)

void	exportStylesheet (const char *filename)
	Produce a representation of the compiled stylesheet.

void	transformFileToFile (const char sourcefile, const char outputfile)
	Perform a one shot transformation.

const char *	transformFileToString (const char *sourcefile)
	Perform a one shot transformation.

XdmValue *	transformFileToValue (const char *sourcefile)

void	applyTemplatesReturningFile (const char *outfile)

const char *	applyTemplatesReturningString ()

XdmValue *	applyTemplatesReturningValue ()

void	callTemplateReturningFile (const char templateName, const char outfile)

const char *	callTemplateReturningString (const char *templateName=nullptr)

XdmValue *	callTemplateReturningValue (const char *templateName=nullptr)

void	callFunctionReturningFile (const char functionName, XdmValue arguments, int argument_length, const char outfile)
	Call a public user-defined function in the already compiled stylesheet.

const char *	callFunctionReturningString (const char functionName, XdmValue *arguments, int argument_length)
	Call a public user-defined function in the compiled stylesheet.

XdmValue *	callFunctionReturningValue (const char functionName, XdmValue *arguments, int argument_length)
	Call a public user-defined function in the already compiled stylesheet.

const char *	transformToString (XdmNode *source=nullptr)
	Execute transformation to string. Properties supplied in advance.

XdmValue *	transformToValue (XdmNode *source=nullptr)
	Execute transformation to Xdm Value. Properties supplied in advance.

void	transformToFile (XdmNode *source=nullptr)
	Execute transformation to file. Properties supplied in advance.

XdmValue *	getXslMessages ()

void	clearXslMessages ()

bool	exceptionOccurred ()

SaxonApiException *	getException ()
	Check for exception thrown and return the SaxonApiException object.

const char *	getErrorMessage ()
	Get the first error message if there are any errors.

void	exceptionClear ()
	Clear any exception thrown.

Friends
class	Xslt30Processor

Detailed Description

An XsltExecutable represents the compiled form of a stylesheet.

An XsltExecutable is created by using one of the compile methods on the Xslt30Processor class.

Member Function Documentation

◆ applyTemplatesReturningFile()

void XsltExecutable::applyTemplatesReturningFile ( const char * outfile )

Invoke the stylesheet by applying templates to a supplied input sequence, Saving the results to file. The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile. The result is stored in the supplied output file.

Parameters

outfile - The file name where results will be stored

Exceptions

SaxonApiException

◆ applyTemplatesReturningString()

const char * XsltExecutable::applyTemplatesReturningString ( )

Invoke the compiled stylesheet by applying templates to a supplied input sequence, Saving the results as serialized string. The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.

Exceptions

SaxonApiException

◆ applyTemplatesReturningValue()

XdmValue * XsltExecutable::applyTemplatesReturningValue ( )

Invoke the compiled stylesheet by applying templates to a supplied input sequence, Saving the results as an XdmValue. The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.

Exceptions

SaxonApiException

◆ callFunctionReturningFile()

void XsltExecutable::callFunctionReturningFile	(	const char *	functionName,
		XdmValue **	arguments,
		int	argument_length,
		const char *	outfile )

Call a public user-defined function in the already compiled stylesheet.

Here we wrap the result in an XML document, and sending this document to a specified file

Parameters

functionName	- The name of the function to be called
arguments	- Pointer array of XdmValue object - he values of the arguments to be supplied to the function. These will be converted if necessary to the type as defined in the function signature, using the function conversion rules.
argument_length	- the Coutn of arguments objects in the array
outfile	- The file name where results will be stored

Exceptions

SaxonApiException

◆ callFunctionReturningString()

const char * XsltExecutable::callFunctionReturningString	(	const char *	functionName,
		XdmValue **	arguments,
		int	argument_length )

Call a public user-defined function in the compiled stylesheet.

Here we wrap the result in an XML document, and serialized this document to string value

Parameters

functionName	- The name of the function to be called
arguments	- Pointer array of XdmValue object - he values of the arguments to be supplied to the function. These will be converted if necessary to the type as defined in the function signature, using the function conversion rules.
argument_length	- the Count of arguments objects in the array

Exceptions

SaxonApiException

◆ callFunctionReturningValue()

XdmValue * XsltExecutable::callFunctionReturningValue	(	const char *	functionName,
		XdmValue **	arguments,
		int	argument_length )

Call a public user-defined function in the already compiled stylesheet.

Here we wrap the result in an XML document, and return the document as an XdmValue

Parameters

functionName	- The name of the function to be called
arguments	- Pointer array of XdmValue object - he values of the arguments to be supplied to the function. These will be converted if necessary to the type as defined in the function signature, using the function conversion rules.
argument_length	- the Count of arguments objects in the array

Exceptions

SaxonApiException

◆ callTemplateReturningFile()

void XsltExecutable::callTemplateReturningFile	(	const char *	templateName,
		const char *	outfile )

Invoke a transformation by calling a named template and save result to file. The results of calling the template are wrapped in a document node, which is then sent to the specified file destination. If setInitialTemplateParameters(std::Map, boolean) has been called, then the parameters supplied are made available to the called template (no error occurs if parameters are supplied that are not used).

Parameters

templateName	- The name of the initial template. This must match the name of a public named template in the stylesheet. If the value is nullptr, the clark name for xsl:initial-template is used.
outfile	- The file name where results will be stored.

Exceptions

SaxonApiException

◆ callTemplateReturningString()

const char * XsltExecutable::callTemplateReturningString ( const char * templateName = nullptr )

Invoke a transformation by calling a named template and return result as a string. The results of calling the template are wrapped in a document node, which is then serialized as a string. If setInitialTemplateParameters(std::Map, boolean) has been called, then the parameters supplied are made available to the called template (no error occurs if parameters are supplied that are not used).

Parameters

templateName - the name of the initial template. This must match the name of a public named template in the stylesheet. If the value is nullptr, the clark name for xsl:initial-template is used.

Exceptions

SaxonApiException

◆ callTemplateReturningValue()

XdmValue * XsltExecutable::callTemplateReturningValue ( const char * templateName = nullptr )

Invoke a transformation by calling a named template and return result as an XdmValue. The results of calling the template are wrapped in a document node, which is then returned as an XdmValue. If setInitialTemplateParameters(std::Map, boolean) has been called, then the parameters supplied are made available to the called template (no error occurs if parameters are supplied that are not used).

Parameters

templateName - the name of the initial template. This must match the name of a public named template in the stylesheet. If the value is nullptr, the clark name for xsl:initial-template is used.

Exceptions

SaxonApiException

◆ clearParameters()

void XsltExecutable::clearParameters ( bool deleteValues = false )

Clear parameter values set.

Default behaviour (false) is to leave XdmValues in memory. Individual pointers to XdmValue objects have to be deleted in the calling program.

Parameters

deleteValues - if true then XdmValues are deleted

◆ clearXslMessages()

void XsltExecutable::clearXslMessages ( )

Clear xsl:message data that are held in the Processor. If the save to file has been enabled then clearXslMessages does not take affect

◆ clone()

XsltExecutable * XsltExecutable::clone ( )

Create a clone object of this XsltExecutable object.

Returns: XsltExecutable - new copy of this object

◆ createCharArray()

char ** XsltExecutable::createCharArray ( int len )

inline

Utility method for working with SaxonC on Python

◆ createXdmValueArray()

XdmValue ** XsltExecutable::createXdmValueArray ( int len )

inline

Utility method for working with SaxonC on Python

◆ deleteXdmValueArray()

void XsltExecutable::deleteXdmValueArray	(	XdmValue **	arr,
		int	len )

Utility method for Python API - internal use only.

This method deletes a XdmValue pointer array

Parameters

arr	- XdmValue pointer array
len	- length of the array

◆ exceptionOccurred()

bool XsltExecutable::exceptionOccurred ( )

Checks for pending exceptions without creating a local reference to the exception object

Returns: bool - true when there is a pending exception; otherwise return false

◆ exportStylesheet()

void XsltExecutable::exportStylesheet ( const char * filename )

Produce a representation of the compiled stylesheet.

The representation of the compiled stylesheet is in an XML form, suitable for distribution and reloading. If the configuration under which the export takes place is suitably licensed, then license information will be included in the export file allowing execution of the stylesheet without any additional license.

The detailed form of the output representation is not documented.

Parameters

filename - the destination for the XML document containing the diagnostic representation of the compiled stylesheet. The stream will be closed when writing has finished.

Exceptions

SaxonApiException

◆ getErrorMessage()

const char * XsltExecutable::getErrorMessage ( )

Get the first error message if there are any errors.

A transformation may have a number of errors reported against it.

Returns: char* - The message of the exception

◆ getException()

SaxonApiException * XsltExecutable::getException ( )

Check for exception thrown and return the SaxonApiException object.

Returns: SaxonApiException. Returns the exception message if thrown otherwise return nullptr

◆ getParameter()

XdmValue * XsltExecutable::getParameter	(	const char *	name,
		bool	withParam = true )

Get a parameter value by name

Parameters

name	- Specified parameter name to get
withParam	Internal use only

Returns: XdmValue

◆ getParameters()

std::map< std::string, XdmValue * > & XsltExecutable::getParameters ( )

Get all parameters as a std::map.

Please note that the key name has been prefixed with 'param:', for example 'param:name'

Returns: std:map with key as string name mapped to XdmValue.

◆ getProperties()

std::map< std::string, std::string > & XsltExecutable::getProperties ( )

Get all properties as a std::map.

Returns: std:map with key as string name mapped to string values.

◆ getProperty()

const char * XsltExecutable::getProperty ( const char * name )

Get a property value by name

Parameters

name	- Specified paramater name to get

Returns: string - Get string of the property as char pointer array

◆ getResultDocuments()

std::map< std::string, XdmValue * > & XsltExecutable::getResultDocuments ( )

Return the result-documents resulting from the execution of the stylesheet. Null is returned if the user has not enabled this feature via the method setCaptureResultDocuments()

Returns: std::map - the map is indexed by the absolute URI of the result document, and the corresponding value is an XdmNode containing the result document (as an in-memory tree, without serialization)

Exceptions

SaxonApiException if we fail to get result-documents

◆ getXslMessages()

XdmValue * XsltExecutable::getXslMessages ( )

Get the messages written using the xsl:message instruction. Returns null if the user has not enabled capturing of xsl:messages via setSaveXslMessage()

Returns: XdmValue - the sequence of xsl:messages as an XdmValue

◆ removeParameter()

bool XsltExecutable::removeParameter ( const char * name )

Remove a parameter (name, value) pair from a stylesheet

Parameters

name	the name of the stylesheet parameter

Returns: bool - outcome of the removal

◆ removeProperty()

bool XsltExecutable::removeProperty ( const char * name )

Remove a property (name, value) pair from the executable

Parameters

name	the name of the property to be removed

Returns: bool - outcome of the removal

◆ setBaseOutputURI()

void XsltExecutable::setBaseOutputURI ( const char * baseURI )

Set the base output URI.

The base output URI is used for resolving relative URIs in the href attribute of the xsl:result-document instruction; it is accessible to XSLT stylesheet code using the XPath current-output-uri() function

Parameters

baseURI - the base output URI

◆ setCaptureResultDocuments()

void XsltExecutable::setCaptureResultDocuments	(	bool	flag,
		bool	rawResults = false )

Enable the capture of the result-document output into an std:map. This overrides the default mechanism. If this option is enabled, then any document created using xsl:result-document is saved (as an XdmNode) in an std::map object where it is accessible using the URI as a key. After the execution of the transformation a call on the getResultDocuments() method is required to get access to the result-documents in the map.

Parameters

flag	- true causes secondary result documents from the transformation to be saved in a map; false disables this option.
rawResults	- true enables the handling of raw destination for resultsDocuments. If not supplied this can also be set on the setResultAsRawValue method. The setResultAsRawValue method has higher priority to this flag

◆ setcwd()

void XsltExecutable::setcwd ( const char * cwd )

set the current working directory (cwd). This method also applies to the

The cwd is used to set the base URI is part of the static context, and is used to resolve any relative URIs appearing within XSLT.

Parameters

cwd	- Current working directory

◆ setGlobalContextFromFile()

void XsltExecutable::setGlobalContextFromFile ( const char * filename )

Supply the context item to be used when evaluating global variables and parameters. Set the source from file for the transformation.

Parameters

filename - the item to be used as the context item within the initializers of global variables and parameters.

◆ setGlobalContextItem()

void XsltExecutable::setGlobalContextItem ( XdmItem * value )

Supply the context item to be used when evaluating global variables and parameters. Set the source document from an XdmNode for the transformation.

Parameters

value - the item to be used as the context item within the initializers of global variables and parameters. Given as a pointer to the XdmItem object.

◆ setInitialMatchSelection()

void XsltExecutable::setInitialMatchSelection ( XdmValue * selection )

The initial value to which templates are to be applied (equivalent to the select attribute of xsl:apply-templates)

Parameters

selection - The value to which the templates are to be applied

◆ setInitialMatchSelectionAsFile()

void XsltExecutable::setInitialMatchSelectionAsFile ( const char * filename )

The initial filename to which templates are to be applied (equivalent to the select attribute of xsl:apply-templates). The file is parsed internally

Parameters

filename - The file name to which the templates are to be applied

◆ setInitialMode()

void XsltExecutable::setInitialMode ( const char * modeName )

Set the initial mode for the transformation.

Parameters

modeName the EQName of the initial mode. Two special values are recognized, in the reserved XSLT namespace: xsl:unnamed to indicate the mode with no name, and xsl:default to indicate the mode defined in the stylesheet header as the default mode. The value null also indicates the default mode (which defaults to the unnamed mode, but can be set differently in an XSLT 3.0 stylesheet).

◆ setInitialTemplateParameters()

void XsltExecutable::setInitialTemplateParameters	(	std::map< std::string, XdmValue * >	parameters,
		bool	tunnel )

Set parameters to be passed to the initial template. These are used whether the transformation is invoked by applying templates to an initial source item, or by invoking a named template. The parameters in question are the xsl:param elements appearing as children of the xsl:template element.

The parameters are supplied in the form of a map; the key is a QName given as a string which must match the name of the parameter; the associated value is an XdmValue containing the value to be used for the parameter. If the initial template defines any required parameters, the map must include a corresponding value. If the initial template defines any parameters that are not present in the map, the default value is used. If the map contains any parameters that are not defined in the initial template, these values are silently ignored.

The supplied values are converted to the required type using the function conversion rules. If conversion is not possible, a run-time error occurs (not now, but later, when the transformation is actually run).

The XsltTransformer retains a reference to the supplied map, so parameters can be added or changed until the point where the transformation is run.

The XSLT 3.0 specification makes provision for supplying parameters to the initial template, as well as global stylesheet parameters. Although there is no similar provision in the XSLT 1.0 or 2.0 specifications, this method works for all stylesheets, regardless whether XSLT 3.0 is enabled or not.

Parameters

parameters	the parameters to be used for the initial template
tunnel	true if these values are to be used for setting tunnel parameters; false if they are to be used for non-tunnel parameters

◆ setOutputFile()

void XsltExecutable::setOutputFile ( const char * outfile )

Set the output file of where the transformation result is sent

◆ setParameter()

void XsltExecutable::setParameter	(	const char *	name,
		XdmValue *	value )

Set the value of a stylesheet parameter

Parameters

name	the name of the stylesheet parameter, as a string. For namespaced parameter use the JAXP solution i.e. "{uri}name"
value	the value of the stylesheet parameter, or nullptr to clear a previously set value

◆ setProperty()

void XsltExecutable::setProperty	(	const char *	name,
		const char *	value )

Set a property specific to the processor in use. XsltProcessor: set serialization properties (names start with '!' i.e. name "!method" -> "xml") 'o':outfile name, 'it': initial template, 'im': initial mode, 's': source as file name 'm': switch on message listener for xsl:message instructions

Parameters

name	of the property
value	of the property

◆ setResultAsRawValue()

void XsltExecutable::setResultAsRawValue ( bool option )

Set true if the return type of callTemplate, applyTemplates and transform methods is to return XdmValue, otherwise return XdmNode object with root Document node

Parameters

option true if return raw result, i.e. XdmValue, otherwise return XdmNode

◆ setSaveXslMessage()

void XsltExecutable::setSaveXslMessage	(	bool	show,
		const char *	filename = nullptr )

This method gives users the option to switch on or off the xsl:message feature. It is also possible to send the xsl:message outputs to file given by file name.

Parameters

show	- boolean to indicate if xsl:message should be outputted. Default is on.
filename	- If the filename argument is present then the xsl:message output is appended to the given filename with location cwd+filename

◆ transformFileToFile()

void XsltExecutable::transformFileToFile	(	const char *	sourcefile,
		const char *	outputfile )

Perform a one shot transformation.

The result is stored in the supplied outputfile.

Parameters

sourcefile	- The file name of the source document
outputfile	- The file name where results will be stored

Exceptions

SaxonApiException

◆ transformFileToString()

const char * XsltExecutable::transformFileToString ( const char * sourcefile )

Perform a one shot transformation.

The result is returned as a string

Parameters

sourcefile - The file name of the source document

Returns: char array - result of the transformation

Exceptions

SaxonApiException

◆ transformFileToValue()

XdmValue * XsltExecutable::transformFileToValue ( const char * sourcefile )

Perform a one shot transformation. The result is returned as an XdmValue

Parameters

sourcefile - The file name of the source document

Returns: XdmValue - result of the transformation

Exceptions

SaxonApiException

◆ transformToFile()

void XsltExecutable::transformToFile ( XdmNode * source = nullptr )

Execute transformation to file. Properties supplied in advance.

Perform the transformation based upon a compiled stylesheet and source document. Assume the output file has been set in advance

Parameters

source - source document supplied as an XdmNode object. nullptr accepted if source document has been set already.

Exceptions

SaxonApiException

◆ transformToString()

const char * XsltExecutable::transformToString ( XdmNode * source = nullptr )

Execute transformation to string. Properties supplied in advance.

Perform the transformation based upon what has been cached.

Parameters

source - source document supplied as an XdmNode object. nullptr accepted if source document has been set already.

Returns: char*. Pointer to Array of chars. Result returned as a string.

Exceptions

SaxonApiException

◆ transformToValue()

XdmValue * XsltExecutable::transformToValue ( XdmNode * source = nullptr )

Execute transformation to Xdm Value. Properties supplied in advance.

Perform the transformation based upon cached stylesheet and any source document.

Parameters

source - source document supplied as an XdmNode object. nullptr accepted if source document has been set already.

Returns: as an XdmValue.

Exceptions

SaxonApiException

The documentation for this class was generated from the following files:

Saxon.C.API/XsltExecutable.h
Saxon.C.API/XsltExecutable.cpp

Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ applyTemplatesReturningFile()

◆ applyTemplatesReturningString()

◆ applyTemplatesReturningValue()

◆ callFunctionReturningFile()

◆ callFunctionReturningString()

◆ callFunctionReturningValue()

◆ callTemplateReturningFile()

◆ callTemplateReturningString()

◆ callTemplateReturningValue()

◆ clearParameters()

◆ clearXslMessages()

◆ clone()

◆ createCharArray()

◆ createXdmValueArray()

◆ deleteXdmValueArray()

◆ exceptionOccurred()

◆ exportStylesheet()

◆ getErrorMessage()

◆ getException()

◆ getParameter()

◆ getParameters()

◆ getProperties()

◆ getProperty()

◆ getResultDocuments()

◆ getXslMessages()

◆ removeParameter()

◆ removeProperty()

◆ setBaseOutputURI()

◆ setCaptureResultDocuments()

◆ setcwd()

◆ setGlobalContextFromFile()

◆ setGlobalContextItem()

◆ setInitialMatchSelection()

◆ setInitialMatchSelectionAsFile()

◆ setInitialMode()

◆ setInitialTemplateParameters()

◆ setOutputFile()

◆ setParameter()

◆ setProperty()

◆ setResultAsRawValue()

◆ setSaveXslMessage()

◆ transformFileToFile()

◆ transformFileToString()

◆ transformFileToValue()

◆ transformToFile()

◆ transformToString()

◆ transformToValue()