SaxonC 12.7.0
Saxon Processor library for C/C++, PHP and Python
Loading...
Searching...
No Matches
Public Member Functions | Friends | List of all members
XsltExecutable Class Reference

An XsltExecutable represents the compiled form of a stylesheet. More...

#include <XsltExecutable.h>

Public Member Functions

void setcwd (const char *cwd)
 Set the current working directory (cwd).
 
const char * getcwd ()
 Get the current working directory (cwd).
 
void setBaseOutputURI (const char *baseURI)
 Set the base output URI.
 
void setGlobalContextItem (XdmItem *value)
 Supply the context item to be used when evaluating global variables and parameters.
 
void setGlobalContextFromFile (const char *filename)
 Supply the context item to be used when evaluating global variables and parameters.
 
XsltExecutableclone ()
 Create a clone of this XsltExecutable object.
 
void setInitialMode (const char *modeName)
 Set the initial mode for the transformation.
 
void setInitialMatchSelection (XdmValue *selection)
 Set the initial match selection for the transformation to be a specified XDM value.
 
void setInitialMatchSelectionAsFile (const char *filename)
 Set the initial match selection for the transformation to be a specified file.
 
void setOutputFile (const char *outfile)
 Set the output file where the transformation result is sent.
 
void setResultAsRawValue (bool option)
 Specify how transformation results are returned.
 
void setParameter (const char *name, XdmValue *value)
 Set the value of a stylesheet parameter.
 
std::map< std::string, XdmValue * > & getResultDocuments ()
 Obtain the secondary result documents resulting from the execution of the stylesheet, as a map.
 
XdmValuegetParameter (const char *name, bool withParam=true)
 Get the value of a stylesheet parameter.
 
bool removeParameter (const char *name)
 Remove a parameter (name, value) pair set for a stylesheet parameter.
 
bool removeProperty (const char *name)
 Remove a configuration property (name, value) pair specific to the processor in use.
 
void setProperty (const char *name, const char *value)
 Set a configuration property specific to the processor in use.
 
void setInitialTemplateParameters (std::map< std::string, XdmValue * > parameters, bool tunnel)
 Set parameters to be passed to the initial template.
 
const char * getProperty (const char *name)
 Get the value of a configuration property.
 
std::map< std::string, XdmValue * > & getParameters ()
 Get all parameters as a std::map.
 
std::map< std::string, std::string > & getProperties ()
 Get all configuration properties specified on the processor as a std::map.
 
void clearParameters (bool deleteValues=false)
 Clear stylesheet parameter values set.
 
void clearProperties ()
 Clear configuration property values set.
 
char ** createCharArray (int len)
 Utility method for working with SaxonC on Python - internal use only.
 
void deleteXdmValueArray (XdmValue **arr, int len)
 Utility method for Python API - internal use only.
 
void setSaveXslMessage (bool show, const char *filename=nullptr)
 This method gives users the option to switch on or off the xsl:message feature.
 
void setCaptureResultDocuments (bool flag, bool rawResults=false)
 Enable the capture of secondary result documents into a std:map, this overrides the default mechanism.
 
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, and save the result to file.
 
const char * transformFileToString (const char *sourcefile)
 Perform a one shot transformation, returning the result as a string.
 
XdmValuetransformFileToValue (const char *sourcefile)
 Perform a one shot transformation, returning the result as an XdmValue.
 
void applyTemplatesReturningFile (const char *outfile)
 Invoke a transformation by applying templates to a supplied input sequence, and save the result to file.
 
const char * applyTemplatesReturningString ()
 Invoke a transformation by applying templates to a supplied input sequence, returning the result as a string.
 
XdmValueapplyTemplatesReturningValue ()
 Invoke a transformation by applying templates to a supplied input sequence, returning the result as an XdmValue.
 
void callTemplateReturningFile (const char *templateName, const char *outfile)
 Invoke a transformation by calling a named template, and save the result to file.
 
const char * callTemplateReturningString (const char *templateName=nullptr)
 Invoke a transformation by calling a named template and return the result as a string.
 
XdmValuecallTemplateReturningValue (const char *templateName=nullptr)
 Invoke a transformation by calling a named template and return the result as an XdmValue.
 
void callFunctionReturningFile (const char *functionName, XdmValue **arguments, int argument_length, const char *outfile)
 Call a public user-defined function in the stylesheet, and save the result to file.
 
const char * callFunctionReturningString (const char *functionName, XdmValue **arguments, int argument_length)
 Call a public user-defined function in the stylesheet and return the result as a string.
 
XdmValuecallFunctionReturningValue (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 a transformation, returning the result as a string, with properties supplied in advance.
 
XdmValuetransformToValue (XdmNode *source=nullptr)
 Execute a transformation, returning the result as an XdmValue, with properties supplied in advance.
 
void transformToFile (XdmNode *source=nullptr)
 Execute a transformation, and save the result to file, with properties supplied in advance.
 
XdmValuegetXslMessages ()
 Get the messages written using the xsl:message instruction.
 
void clearXslMessages ()
 Clear xsl:message data held in the processor.
 
bool exceptionOccurred ()
 Deprecated.
 
SaxonApiExceptiongetException ()
 Deprecated.
 
const char * getErrorMessage ()
 Deprecated.
 
void exceptionClear ()
 Deprecated.
 
SaxonProcessorgetSaxonProcessor ()
 Get the SaxonProcessor which created this XsltExecutable.
 

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 a transformation by applying templates to a supplied input sequence, and save the result to file.

The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile. The result is stored in the specified output file.

Parameters
outfile- the name of the file where results will be stored The caller is responsible for memory deallocation using operator delete.
Exceptions
SaxonApiException

◆ applyTemplatesReturningString()

const char * XsltExecutable::applyTemplatesReturningString ( )

Invoke a transformation by applying templates to a supplied input sequence, returning the result as a string.

The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.

Returns
The result of the transformation serialized to a string. A zero length string is returned if the executed transformation is an empty sequence. The caller is responsible for memory deallocation using operator delete.
Exceptions
SaxonApiException

◆ applyTemplatesReturningValue()

XdmValue * XsltExecutable::applyTemplatesReturningValue ( )

Invoke a transformation by applying templates to a supplied input sequence, returning the result as an XdmValue.

The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.

Returns
The result of the transformation as an XdmValue. The caller is responsible for memory deallocation using delete.
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 stylesheet, and save the result to file.

The results of calling the function are wrapped in a document node, which is then sent to the specified file destination.

Parameters
functionName- the name of the function to be called
arguments- pointer array of XdmValue objects - the 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 number of argument objects in the array
outfile- the name of the file 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 stylesheet and return the result as a string.

The results of calling the function are wrapped in a document node, which is then serialized as a string.

Parameters
functionName- the name of the function to be called
arguments- pointer array of XdmValue objects - the 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. The caller is responsible for memory deallocation using operator delete.
argument_length- the number of argument objects in the array
Returns
The result of calling the function serialized to a string. A zero length string is returned if the result is an empty sequence.
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.

The results of calling the function are wrapped in a document node, which is then returned as an XdmValue.

Parameters
functionName- the name of the function to be called
arguments- pointer array of XdmValue objects - the 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 number of argument objects in the array
Returns
The result of calling the function as an XdmValue (i.e. the raw result, without wrapping in a document node and without serialization). The caller is responsible for memory deallocation using delete.
Exceptions
SaxonApiException

◆ callTemplateReturningFile()

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

Invoke a transformation by calling a named template, and save the 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 name of the file 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 the 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.
Returns
The result of the transformation serialized to a string. A zero length string is returned if the transformation result is an empty sequence. The caller is responsible for memory deallocation using operator delete.
Exceptions
SaxonApiException

◆ callTemplateReturningValue()

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

Invoke a transformation by calling a named template and return the 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.
Returns
The result of the transformation as an XdmValue (i.e. the raw result, without wrapping in a document node or serialization). The caller is responsible for memory deallocation using operator delete.
Exceptions
SaxonApiException

◆ clearParameters()

void XsltExecutable::clearParameters ( bool deleteValues = false)

Clear stylesheet 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 held in the processor.

If it has been specified that messages are saved to file, then calling clearXslMessages has no effect.

◆ clone()

XsltExecutable * XsltExecutable::clone ( )

Create a clone of this XsltExecutable object.

Returns
A new copy of this XsltExecutable object

◆ 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

◆ exceptionClear()

void XsltExecutable::exceptionClear ( )

Deprecated.

Clear any thrown exceptions.

Deprecated
From 12.1 this method is no longer used, since exceptions are now thrown.

◆ exceptionOccurred()

bool XsltExecutable::exceptionOccurred ( )

Deprecated.

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

Returns
True when there is a pending exception; otherwise false
Deprecated
From 12.1 this method is no longer used, since exceptions are now thrown.

◆ 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

◆ getcwd()

const char * XsltExecutable::getcwd ( )

Get the current working directory (cwd).

Memory deallocation is handled internally. 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.

Returns
Current working directory

◆ getErrorMessage()

const char * XsltExecutable::getErrorMessage ( )

Deprecated.

Get the first error message if there are any errors. A transformation may have a number of errors reported against it.

Returns
The message of the exception
Deprecated
From 12.1 this method is no longer used, since exceptions are now thrown.

◆ getException()

SaxonApiException * XsltExecutable::getException ( )

Deprecated.

Get the SaxonApiException object created when we have an error.

Returns
The SaxonApiException object if there is an exception thrown, or nullptr otherwise
Deprecated
From 12.1 this method is no longer used, since exceptions are now thrown.

◆ getParameter()

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

Get the value of a stylesheet parameter.

Parameters
name- the name of the stylesheet parameter
withParam- internal use only
Returns
The value of the parameter as an 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 configuration properties specified on the processor as a std::map.

Returns
Map of (string, string) pairs

◆ getProperty()

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

Get the value of a configuration property.

Parameters
name- the name of the property
Returns
The value of the property as a char pointer array. Memory deallocation is handled internally.

◆ getResultDocuments()

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

Obtain the secondary result documents resulting from the execution of the stylesheet, as a map.

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
SaxonApiExceptionif 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
The sequence of xsl:messages as an XdmValue. The caller is responsible for memory deallocation using operator delete.

◆ removeParameter()

bool XsltExecutable::removeParameter ( const char * name)

Remove a parameter (name, value) pair set for a stylesheet parameter.

Parameters
name- the name of the stylesheet parameter
Returns
Outcome of the removal

◆ removeProperty()

bool XsltExecutable::removeProperty ( const char * name)

Remove a configuration property (name, value) pair specific to the processor in use.

Parameters
name- the name of the property to be removed
Returns
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 secondary result documents into a 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 a 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 secondary 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 results documents. 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 static base URI for XSLT stylesheets when supplied as lexical string. 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 context item for the transformation as a source document.

Parameters
filename- the name of the source document 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 context item for the transformation as an XdmItem.

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

◆ setInitialMatchSelection()

void XsltExecutable::setInitialMatchSelection ( XdmValue * selection)

Set the initial match selection for the transformation to be a specified XDM value.

This is equivalent to the select attribute of xsl:apply-templates

Parameters
selection- the XDM value to which template rules are to be applied

◆ setInitialMatchSelectionAsFile()

void XsltExecutable::setInitialMatchSelectionAsFile ( const char * filename)

Set the initial match selection for the transformation to be a specified file.

This is equivalent to the select attribute of xsl:apply-templates. The file is parsed internally.

Parameters
filename- the file name for the source document to which template rules 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 where the transformation result is sent.

Parameters
outfile- the name of the file where results will be stored

◆ 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 a namespaced name use clark notation i.e. "{uri}local"
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 configuration property specific to the processor in use.

XsltExecutable: 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- the name of the property
value- the value of the property

◆ setResultAsRawValue()

void XsltExecutable::setResultAsRawValue ( bool option)

Specify how transformation results are returned.

Set true to return the result of callTemplate, applyTemplates and transform methods as a raw XdmValue, otherwise return a result document as an XdmNode object.

Parameters
option- true to 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, and save the result to file.

The result is stored in the specified output file.

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, returning the result as a string.

Parameters
sourcefile- the file name of the source document
Returns
The result of the transformation serialized to a string. A zero length string is returned if the transformation result is an empty sequence. The caller is responsible for memory deallocation using operator delete.
Exceptions
SaxonApiException

◆ transformFileToValue()

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

Perform a one shot transformation, returning the result as an XdmValue.

Parameters
sourcefile- the file name of the source document
Returns
The result of the transformation as an XdmValue. The caller is responsible for memory deallocation using delete.
Exceptions
SaxonApiException

◆ transformToFile()

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

Execute a transformation, and save the result to file, with properties supplied in advance.

Perform the transformation as configured for this XsltExecutable. The result is stored in the output file as 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 a transformation, returning the result as a string, with properties supplied in advance.

Perform the transformation as configured for this XsltExecutable.

Parameters
source- source document supplied as an XdmNode object. nullptr accepted if source document has been set already.
Returns
The result of the transformation serialized to a string. A zero length string is returned if the transformation result is an empty sequence. The caller is responsible for memory deallocation using operator delete.
Exceptions
SaxonApiException

◆ transformToValue()

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

Execute a transformation, returning the result as an XdmValue, with properties supplied in advance.

Perform the transformation as configured for this XsltExecutable.

Parameters
source- source document supplied as an XdmNode object. nullptr accepted if source document has been set already.
Returns
The result of the transformation as an XdmValue. The caller is responsible for memory deallocation using operator delete.
Exceptions
SaxonApiException

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