SaxonC  11.3
Saxon Processor library for C/C++, PHP and Python
Public Member Functions | Friends | List of all members
XsltExecutable Class Reference

#include <XsltExecutable.h>

Public Member Functions

void setcwd (const char *cwd)
 set the current working directory (cwd). This method also applies to the More...
 
void setBaseOutputURI (const char *baseURI)
 Set the base output URI. More...
 
void setGlobalContextItem (XdmItem *value)
 Set the source document from an XdmNode for the transformation. More...
 
void setGlobalContextFromFile (const char *filename)
 
XsltExecutableclone ()
 Create a clone object of this XsltExecutable object. More...
 
void setInitialMode (const char *modeName)
 Set the initial mode for the transformation. More...
 
void setInitialMatchSelection (XdmValue *selection)
 The initial value to which templates are to be applied (equivalent to the select attribute of xsl:apply-templates) More...
 
void setInitialMatchSelectionAsFile (const char *filename)
 The initial filename to which templates are to be applied (equivalent to the select attribute of xsl:apply-templates). More...
 
void setOutputFile (const char *outfile)
 
void setResultAsRawValue (bool option)
 
void setParameter (const char *name, XdmValue *value)
 
std::map< std::string, XdmValue * > & getResultDocuments ()
 
XdmValuegetParameter (const char *name)
 
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. More...
 
std::map< std::string, std::string > & getProperties ()
 Get all properties as a std::map. More...
 
void clearParameters (bool deleteValues=false)
 Clear parameter values set. More...
 
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. More...
 
void setSaveXslMessage (bool show, const char *filename=nullptr)
 This method gives users the option to switch on or off the xsl:message feature. More...
 
void setCaptureResultDocuments (bool flag, bool rawResults=false)
 Enable the capture of the result-document output into an std:map. This overrides the default mechanism. More...
 
void exportStylesheet (const char *filename)
 Produce a representation of the compiled stylesheet. More...
 
void transformFileToFile (const char *sourcefile, const char *outputfile)
 Perform a one shot transformation. More...
 
const char * transformFileToString (const char *sourcefile)
 Perform a one shot transformation. More...
 
XdmValuetransformFileToValue (const char *sourcefile)
 
void applyTemplatesReturningFile (const char *outfile)
 Invoke the stylesheet by applying templates to a supplied input sequence, Saving the results to file. More...
 
const char * applyTemplatesReturningString ()
 Invoke the compiled stylesheet by applying templates to a supplied input sequence, Saving the results as serialized string. More...
 
XdmValueapplyTemplatesReturningValue ()
 Invoke the compiled stylesheet by applying templates to a supplied input sequence, Saving the results as an XdmValue. More...
 
void callTemplateReturningFile (const char *templateName, const char *outfile)
 Invoke a transformation by calling a named template and save result to file. More...
 
const char * callTemplateReturningString (const char *templateName=nullptr)
 Invoke a transformation by calling a named template and return result as a string. More...
 
XdmValuecallTemplateReturningValue (const char *templateName=nullptr)
 Invoke a transformation by calling a named template and return result as a XdmValue. More...
 
void callFunctionReturningFile (const char *functionName, XdmValue **arguments, int argument_length, const char *outfile)
 Call a public user-defined function in the already compiled stylesheet. More...
 
const char * callFunctionReturningString (const char *functionName, XdmValue **arguments, int argument_length)
 Call a public user-defined function in the compiled stylesheet. More...
 
XdmValuecallFunctionReturningValue (const char *functionName, XdmValue **arguments, int argument_length)
 Call a public user-defined function in the already compiled stylesheet. More...
 
const char * transformToString (XdmNode *source=nullptr)
 Execute transformation to string. Properties supplied in advance. More...
 
XdmValuetransformToValue (XdmNode *source=nullptr)
 Execute transformation to Xdm Value. Properties supplied in advance. More...
 
void transformToFile (XdmNode *source=nullptr)
 Execute transformation to file. Properties supplied in advance. More...
 
bool exceptionOccurred ()
 
SaxonApiExceptiongetException ()
 Check for exception thrown and return the SaxonApiException object. More...
 
const char * getErrorMessage ()
 Get the error message if there are any error. More...
 
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

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

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

◆ 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,

◆ 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 Coutn of arguments objects in the array

◆ 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

◆ 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,

◆ 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.
outputfile- The file name where results will be stored,

◆ callTemplateReturningValue()

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

Invoke a transformation by calling a named template and return result as a 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.

◆ clearParameters()

void XsltExecutable::clearParameters ( bool  deleteValues = false)

Clear parameter values set.

Default behaviour (false) is to leave XdmValues in memory true then XdmValues are deleted

Parameters
deleteValues.Individual pointers to XdmValue objects have to be deleted in the calling program

◆ 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 
)
inline

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.

◆ getErrorMessage()

const char * XsltExecutable::getErrorMessage ( )

Get the error message if there are any error.

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)

Get a parameter value by name

Parameters
name- Specified parameter name to get
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)

◆ removeParameter()

bool XsltExecutable::removeParameter ( const char *  name)

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

Parameters
namethe 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
namethe name of the property to be removed
Returns
bool - outcome of the romoval

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

Set the source from file for the transformation.

◆ setGlobalContextItem()

void XsltExecutable::setGlobalContextItem ( XdmItem value)

Set the source document from an XdmNode for the transformation.

Parameters
value- The source to the stylesheet as a pointer to the XdmNode 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 internall

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
modeNamethe 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
parametersthe parameters to be used for the initial template
tunneltrue 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
namethe name of the stylesheet parameter, as a string. For namespaced parameter use the JAXP solution i.e. "{uri}name"
valuethe 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
nameof the property
valueof 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
optiontrue 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

◆ 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

◆ 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

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

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

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

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