![]() |
SaxonC 12.7.0
Saxon Processor library for C/C++, PHP and Python
|
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. | |
XsltExecutable * | clone () |
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. | |
XdmValue * | getParameter (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. | |
XdmValue * | transformFileToValue (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. | |
XdmValue * | applyTemplatesReturningValue () |
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. | |
XdmValue * | callTemplateReturningValue (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. | |
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 a transformation, returning the result as a string, with properties supplied in advance. | |
XdmValue * | transformToValue (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. | |
XdmValue * | getXslMessages () |
Get the messages written using the xsl:message instruction. | |
void | clearXslMessages () |
Clear xsl:message data held in the processor. | |
bool | exceptionOccurred () |
Deprecated. | |
SaxonApiException * | getException () |
Deprecated. | |
const char * | getErrorMessage () |
Deprecated. | |
void | exceptionClear () |
Deprecated. | |
SaxonProcessor * | getSaxonProcessor () |
Get the SaxonProcessor which created this XsltExecutable. | |
Friends | |
class | Xslt30Processor |
An XsltExecutable
represents the compiled form of a stylesheet.
An XsltExecutable is created by using one of the compile
methods on the Xslt30Processor class.
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.
outfile | - the name of the file where results will be stored The caller is responsible for memory deallocation using operator delete . |
SaxonApiException |
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.
operator delete
. SaxonApiException |
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.
delete
. SaxonApiException |
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.
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 |
SaxonApiException |
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.
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 |
SaxonApiException |
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.
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 |
delete
. SaxonApiException |
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).
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. |
SaxonApiException |
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).
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. |
operator delete
. SaxonApiException |
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).
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. |
operator delete
. SaxonApiException |
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.
deleteValues | - if true then XdmValues are deleted |
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.
XsltExecutable * XsltExecutable::clone | ( | ) |
Create a clone of this XsltExecutable object.
void XsltExecutable::deleteXdmValueArray | ( | XdmValue ** | arr, |
int | len ) |
void XsltExecutable::exceptionClear | ( | ) |
Deprecated.
Clear any thrown exceptions.
bool XsltExecutable::exceptionOccurred | ( | ) |
Deprecated.
Checks for pending exceptions without creating a local reference to the exception object
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.
filename | - the destination for the XML document containing the diagnostic representation of the compiled stylesheet. The stream will be closed when writing has finished. |
SaxonApiException |
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.
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.
SaxonApiException * XsltExecutable::getException | ( | ) |
Deprecated.
Get the SaxonApiException object created when we have an error.
XdmValue * XsltExecutable::getParameter | ( | const char * | name, |
bool | withParam = true ) |
Get the value of a stylesheet parameter.
name | - the name of the stylesheet parameter |
withParam | - internal use only |
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'
std::map< std::string, std::string > & XsltExecutable::getProperties | ( | ) |
Get all configuration properties specified on the processor as a std::map.
const char * XsltExecutable::getProperty | ( | const char * | name | ) |
Get the value of a configuration property.
name | - the name of the property |
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().
SaxonApiException | if we fail to get result-documents |
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()
operator delete
. bool XsltExecutable::removeParameter | ( | const char * | name | ) |
Remove a parameter (name, value) pair set for a stylesheet parameter.
name | - the name of the stylesheet parameter |
bool XsltExecutable::removeProperty | ( | const char * | name | ) |
Remove a configuration property (name, value) pair specific to the processor in use.
name | - the name of the property to be removed |
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.
baseURI | - the base output URI |
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.
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 |
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.
cwd | - current working directory |
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.
filename | - the name of the source document to be used as the context item within the initializers of global variables and parameters. |
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.
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. |
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
selection | - the XDM value to which template rules are to be applied |
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.
filename | - the file name for the source document to which template rules are to be applied |
void XsltExecutable::setInitialMode | ( | const char * | modeName | ) |
Set the initial mode for the transformation.
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). |
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 | - 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 |
void XsltExecutable::setOutputFile | ( | const char * | outfile | ) |
Set the output file where the transformation result is sent.
outfile | - the name of the file where results will be stored |
void XsltExecutable::setParameter | ( | const char * | name, |
XdmValue * | value ) |
Set the value of a stylesheet parameter.
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 |
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.
name | - the name of the property |
value | - the value of the property |
void XsltExecutable::setResultAsRawValue | ( | bool | option | ) |
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.
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 |
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.
sourcefile | - the file name of the source document |
outputfile | - the file name where results will be stored |
SaxonApiException |
const char * XsltExecutable::transformFileToString | ( | const char * | sourcefile | ) |
Perform a one shot transformation, returning the result as a string.
sourcefile | - the file name of the source document |
operator delete
. SaxonApiException |
XdmValue * XsltExecutable::transformFileToValue | ( | const char * | sourcefile | ) |
Perform a one shot transformation, returning the result as an XdmValue.
sourcefile | - the file name of the source document |
delete
. SaxonApiException |
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.
source | - source document supplied as an XdmNode object. nullptr accepted if source document has been set already. |
SaxonApiException |
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.
source | - source document supplied as an XdmNode object. nullptr accepted if source document has been set already. |
operator delete
. SaxonApiException |
Execute a transformation, returning the result as an XdmValue, with properties supplied in advance.
Perform the transformation as configured for this XsltExecutable.
source | - source document supplied as an XdmNode object. nullptr accepted if source document has been set already. |
operator delete
. SaxonApiException |