XSLT transformations from a C++ application

Rather than running XSLT transformations from the command line, you may want to invoke transformations from your own C++ application. If you use Saxon repeatedly to perform multiple transformations, this will always be much faster than running it each time from the command line.

You can perform a transformation using the SaxonC C++ interface as follows:

Create a SaxonProcessor and set any global configuration options on the SaxonProcessor object. If your stylesheet uses any features that require SaxonC-PE or SaxonC-EE, be sure to use the constructor new SaxonProcessor(true).
Call newXslt30Processor() to create an Xslt30Processor, and set any options that are local to a specific compilation (for example, the destination of error messages).

Error messages that occur during the compile phase are handled internally in SaxonC and thrown as the C++ exception SaxonApiException. Throwing exceptions is fine for an application run from a console, but not so good if it's executing on a web server, or behind a graphical interface. In such cases you'll want to catch the exception and handle it accordingly.
Call one of the methods compileFromFile(), compileFromString() or compileFromAssociatedFile() to compile a stylesheet. The result is a pointer to the XsltExecutable object, which can be used as often as you like, in the same thread or in different threads.

The XsltExecutable class was introduced in SaxonC 11.1, and provides new ways of executing stylesheet code that are defined in the XSLT 3.0 specification, though Saxon also allows you to use the same entry points with 1.0 or 2.0 stylesheets. Among the new capabilities are:
- You can invoke a specific stylesheet function, with parameters, rather than invoking a named template or template rule.
- If you start execution with a named template or template rule, you can supply values for the parameters defined on that template, as well as the global stylesheet parameters, using the setParameter() method. The SaxonProcessor has a number of utility methods to create XDM objects, for example makeStringValue() to create an XdmAtomicValue object from a char pointer array, which can be used for the values of parameters.
- Whether you execute a template or a function, you can return the results in raw string as a char pointer array, to file or as an XDM type. For example, a function (or template) might return a sequence of strings, or a single boolean, or a map, or even a function.
  
  It is possible to capture the secondary result documents into an std:map (as the pair URI key and XdmNode) using the setCaptureResultDocuments() method. This overrides the default mechanism of writing the result documents to file. To retrieve the result documents call the method getResultDocuments() after the execution of the stylesheet.
- There is no longer any necessary relationship between the "principal source document" (if it still exists) and the context item for evaluating global variables. The two things are quite independent of each other.
  
  The principal source document can be set on the XsltExecutable using the setInitialMatchSelection() or setInitialMatchSelectionAsFile() methods. The SaxonProcessor provides methods for parsing XML documents from file and from a string literal (e.g parseXmlFromFile()); while the DocumentBuilder class is more feature rich, for instance it can be used to parse and validate XML documents by setting a SchemaValidator.
  
  It is sometimes a requirement to supply the context item to be used when evaluating global variables and parameters; which can be done using the setGlobalContextItem() or setGlobalContextFromFile() methods.
For more details about the configuration options available, and how to set these properties and parameters, see Configuration in the SaxonC documentation.
To run a transformation, there are several methods available on the XsltExecutable to execute the compiled stylesheet. For example, to evaluate a stylesheet using apply-templates invocation there are three methods available: applyTemplatesReturningString(), applyTemplatesReturningValue() and applyTemplatesReturningFile(). As the names suggest these methods return the output of the transformation as a serialized string (as a char pointer array), or a pointer to an XdmValue object or file on disk, respectively. Similarly there are other methods available to initiate call-template invocation or function call invocation.

Alternatively, it is also possible to run one shot transformations using the methods transformFileToFile(), transformFileToString() and transformFileToValue() directly on the Xslt30Processor without going through an explicit compilation process. But note that these methods have limited features and are not designed for XSLT 3.0. For XSLT 3.0 it is advisable to use one of the compile methods above to create a XsltExecutable.