Project

Profile

Help

How to connect?
Download (51.3 KB) Statistics
| Branch: | Revision:

he / src / main / c / Saxon.C.API / readme.txt @ 02e2c377

1
[Back to web page](http://www.saxonica.com/saxon-c/index.xml)
2

    
3
# Table of Contents
4
1. [Installation](#Installation)
5
2. [Getting started with C/C++](#getting-started)
6
3. [PHP API & Examples](#php-api)
7
4. [Python API & Examples](#python-api)
8
5. [Technical](#tech)
9
6. [Limitations](#limitations)
10

    
11
Saxon/C 1.2.1 is the latest release of Saxon-HE/PE/EE on the C/C++, PHP and Python programming platforms. The APIs support the specifications XSLT 3.0, XQuery 3.1, Schema Validation 1.0/1.1 and XPath 3.1.
12

    
13
Saxon/C is built from the Saxon 9.9.1.5 Java product using Excelsior JET Enterprise 15.3 edition (MP1).
14

    
15
Platforms supported: Linux 64-bit, Mac OS and Windows 64-bit. 
16

    
17
Saxon/C is released in three separate editions, as on the Java platform: Enterprise Edition (Saxon-EE/C), Professional Edition (Saxon-PE/C), and Home Edition (Saxon-HE/C)
18

    
19
<div id='installation'/>
20
## Installation: ##
21

    
22
#### Linux: Saxon-HE/C, Saxon-PE/C and Saxon-EE/C: ####
23
To install any of the Saxon/C releases, unzip the file libsaxon-EDITION-setup-v#.#.#.zip and execute the command './libsaxon-EDITION-setup-v#.#.#'
24
First step is to select the destination of where the product files will be installed.
25
The product files are unpacked in the directory 'Saxon-EDITIONC'
26

    
27
Link the dynamic saxon library so it can be found. For example:
28

    
29
	ln -s /usr/lib/Saxonica/Saxon-EDITIONC#.#.#/libsaxonEDITION.so /usr/lib/libsaxonEDITION.so
30

    
31
You need to setup the environment for the jet jvm. The jvm is in the directory JET-home=Saxonica/Saxon-EDITION1.2.1/rt
32
The directory JET_home/lib/amd64 must be listed in the LD_LIBRARY_PATH environment variable. For instance, if you
33
are using bash or Bourne shell, use the following commands:
34

    
35
    export LD_LIBRARY_PATH=/usr/lib/rt/lib/amd64:$LD_LIBRARY_PATH
36

    
37
We assume that the 'rt' directory is in the location /usr/lib.
38

    
39
Link the jetvm library so it can be found. For example:
40

    
41
	ln -s /usr/lib/Saxonica/Saxon-EDITIONC#.#.#/rt /usr/lib/rt
42

    
43
The Saxon-EDITION API assumes the library is installed as follows: '/usr/lib/libsaxonhec.so', '/usr/lib/libsaxonpec.so' or '/usr/lib/libsaxoneec.so'
44

    
45

    
46
Example of running the C++ test files (i.e. testXPath.cpp, testXQuery.cpp, testXSLT.cpp, testXSLT30.cpp and testValidator.cpp):
47
 
48
    cd samples/cppTests/
49
 
50
    ./build64-linux.sh
51
 
52
    ./testXPath
53
    ./testXSLT
54
    ./testXSLT30
55
    ./testXQuery
56
    ./testValidator (Saxon-EE/C only)
57

    
58
 #### Mac OS: Saxon-HE/C, Saxon-PE/C and Saxon-EE/C: ####
59
To install any of the Saxon/C releases on the Mac OS system, unzip the self-contained file libsaxon-EDITION-mac-setup-v#.#.#.zip
60
 
61
The first step is to copy the library libsaxonEDITION.dylib and the rt directories to a your install location. 
62
The C/C++ interface by default assumes the library files and directories are installed in the directory '/usr/local/lib'. 
63
The location of the Saxon/C library can be set using the SAXONC_HOME environment variable. 
64
The privileges of the folders and files may need adjusting after copying everything if you encounter permission issues.
65

    
66
    cd libsaxon-HEC-mac-setup-v1.2.1/    
67
    sudo cp libsaxonhec.dylib /usr/local/lib/.    
68
    sudo cp -r rt /usr/local/lib/.
69
 
70
The DYLD_LIBRARY_PATH environment variable must be set as follows:
71

    
72
    export JET_HOME=/usr/local/lib/rt
73
    export DYLD_LIBRARY_PATH=$JET_HOME/lib/jetvm:$DYLD_LIBRARY_PATH
74
    
75
    
76
Example of running the C++ test file:
77
 
78
    cd samples/cppTests/
79
 
80
    ./build64-mac.sh
81
 
82
    ./testXPath
83

    
84
#### PHP extension: ####
85
 
86
A built php extension module is included in the Saxon/C distrubtion, see the directory 'php-library-module'.
87
 See the file saxon.so (Available for Linux and Mac OS). This was built using the php 7.2 version.
88
 For PHP5 please copy files in the PHP5-Build directory into the Saxon.C.API directory.
89
 
90
To build the php extension follow the steps below:
91

    
92
Run the commands (from the root directory of the Saxon/C installation):
93

    
94
    cd Saxon.C.API
95
    phpize
96
    ./configure --enable-saxon
97
    make
98
    sudo make install
99

    
100
Create a module conf file:
101

    
102
nano /etc/php7/mods-available/saxon.ini
103
and add contents:
104

    
105
	; configuration for php Saxon HE/PE/EE module
106
	    extension=saxon.so
107
	save the file.
108

    
109
Enable the module for PHP:
110

    
111
	php7enmod saxon
112
	
113
Similar for PHP5
114

    
115
Alternatively, you can update the php.ini file (if using ubuntu it is usually in the location '/etc/php7/apache2/') to contain the php extension: insert the following in the Dynamic Extensions section: extension=saxon.so
116

    
117
* sudo service apache2 restart
118

    
119
Check that the extension has installed properly:
120

    
121
* php -d"extension=saxon.so" -m
122
* Also Create a php page and call the function 'phpinfo()'. Look for the Saxon/C entry.
123

    
124
See example PHP scripts in the 'samples/php' directory. Specifically the files (xpathExamples.php, xqueryExamples.php, xsltExamples.php, xslt30Examples.php and validatorExamples.php). 
125

    
126

    
127
### Python ###
128
The Saxon/C Python extension API has been developed using [Cython](https://cython.org/) for Python3.
129
Cython is required to build the extension library.
130

    
131
To install python and cython on MacOS I recommend using brew or MacPorts. 
132

    
133
The Saxon/C Python extension is in the directory Saxon.C.API/python-saxon
134

    
135
The Python extension on the Linux and MacOS platforms can be built using the following command:
136

    
137
`python3 saxon-setup.py build_ext -if`
138

    
139
Please see the [Python API documentation](http://www.saxonica.com/????/saxonc.html)
140

    
141
<div id='getting-started'/>
142

    
143
## Getting started with C/C++: ##
144

    
145
To get started please browse the Saxon/C API starting with the class [SaxonProcessor](classSaxonProcessor.html) class which acts as a factory class for generating the processors.
146

    
147
## C/C++ ##
148

    
149

    
150

    
151
### c: ###
152

    
153
For c programming see the test harnesses for XSLT, XQuery, Schema Validation and XPath in C code along with the build and run script in the directory 'cTests'.
154

    
155
The following files are required to build Saxon/C on C++:  SaxonCGlue.c, SaxonXProcessor.c, SaxonCXPath.c
156

    
157
To compile the sample test code in C execute the 'build.sh' file the directory 'cTests'. This file builds executables for the test cases testing XSLT, XPath, XQuery and schema Validator. The command is similar to the following:
158

    
159
> gcc -m32 -I$jdkdir/include -I$jdkdir/include/linux -I /System/Library/Frameworks/JavaVM.framework/Headers ../SaxonCGlue.c ../SaxonCProcessor.c ../SaxonCXPath.c  testXSLT.c -o testXSLT -ldl -lc $1
160

    
161
Saxon/C can be run from the commandline in a similar way to its Java counterpart (same options are available). See the file Transform.c, Query.c and Validate.c (which is available in Saxon-EE/C) in the directory 'command'. The build.sh script can be executed to build the commandline programs.
162

    
163

    
164
### C++: ###
165
For C++ programming see sample code for XSLT, XQuery, Schema Validation and XPath in C++ code along with the build and run script in the directory 'cppTests'.
166

    
167
The following files are required to build Saxon/C on C++:  SaxonCGlue.c, SaxonCXPath.c, XdmValue.cpp, XdmItem.cpp, XdmNode.cpp, XdmAtomicValue.cpp, SaxonProcessor.cpp, XsltProcessor.cpp, Xslt30Processor.cpp and XQueryProcessor.cpp, XPathProcessor.cpp, SchemaValidator.cpp
168

    
169
To compile the sample test code in C++ execute the 'build.sh' file the directory 'cppTests'. This file builds executables for the test cases testing XSLT, XPath, XQuery and schema Validator. The command is similar to the following: 
170

    
171
> g++ -m32  ../bin/SaxonCGlue.o ../bin/SaxonCXPath.o ../bin/SaxonProcessor.o ../bin/XQueryProcessor.o ../bin/XsltProcessor.o, ../bin/Xslt30Processor.o ../bin/XPathProcessor.o ../bin/XdmValue.o ../bin/XdmItem.o ../bin/XdmNode.o ../bin/XdmAtomicValue.o ../bin/SchemaValidator.o testXSLT.cpp -o testXSLT -ldl -lc $1 $2
172

    
173

    
174

    
175

    
176
### Configuration of Processors - (setParameter & setProperty methods) ###
177

    
178
There are many parameters and options that can be set to control the way in which Saxon behaves. At a global level when the SaxonProcessor is created, the configuration features can be set with the method 'setConfigurationProperty(const char * name, const char * value)'. For a comprehensive guide on the configuration see the [Saxon documentation](http://saxonica.com/documentation/index.html#!configuration/config-features). There are some feature that don't work or are under tested. For eample, 'bytecode generation' we know does not work.
179

    
180
The example below shows how we can set the configuration features on the processor before we create any of the processors (.e.g. XsltProcessor, XQueryProcess, etc):
181

    
182
> processor->setConfigurationProperty("xsdversion", "1.1"); 
183
or
184
> processor->setConfigurationProperty("http://saxon.sf.net/feature/multipleSchemaImports", "on");
185

    
186
The processors for XSLT, XQuery, XPath and Schema Validator can be configured using the methods setParameter and setProperty. Depending on the specific processor the exact purpose of these methods may differs. In the following sections we will go through the options available.
187

    
188

    
189
We now give a quick guide for running Saxon/C in C++
190

    
191
### XSLT ###
192

    
193
#### setParameter(string $name, XdmValue $value) Method ####
194

    
195
| Name | Example | Comment |
196
| :---- | :---- | :---- |
197
| 'node'=xdmValue | setParameter("node",xdmNodeObj) | Sets the source document for transformation. We also accept the parameter names 'item'.|
198
| param=xdmValue | setParameter("numParam",value1) | set the value of a stylesheet parameter|
199

    
200
#### setProperty(string $name, string $propValue) Method ####
201

    
202
The properties are a subset to those specified for running XSLT from the [command line](http://www.saxonica.com/documentation/index.html#!using-xsl/commandline).
203

    
204
| Name | Example | Comment |
205
| :---- | :---- | :---- |
206
|![serialization name]=value  | setProperty("!INDENT","yes") | Influence the serialization of the XML by the parameters specified with a exclamation mark with a name and the value. See [Documentation](http://saxonica.com/documentation/index.html#!javadoc/net.sf.saxon.s9api/Serializer/Property) |
207
| 'o'=filename | setProperty("o", "output.xml") | Sets the destination for the result of the transformation to the specificed filename  |
208
| 'it'=name | setProperty("it", "name") | Set the initial named template for the transformation by name|
209
| 'dtd'=boolean | setProperty("dtd", "true") | Set whether DTD validation should be applied to documents loaded |
210
| 'im'=name | setProperty("im", "mode-name")  | Set the initial mode for the transformation |
211
| 's'=filename | setProperty("s", "filename") | Identifies the source file or directory. Mandatory unless the -it option is used. |
212
| 'resources'=directory | setProperty("resources", "dir") | Specifies the directory where the resources file are found|
213
| 'tunnel' | setProperty("tunnel", "true") | XSLT3.0 only. Accepts the values true, false, yes, no. True if the initial template parameter values are to be used for setting tunnel parameters; false if they are to be used for non-tunnel parameters |
214
| 'outvalue' | setProperty("outvalue", "true") | XSLT30 only. Accepts the values true, false, yes, no. Set if the return type of callTemplate, applyTemplate and transform methods is to return XdmValue, otherwise return XdmNode object with root Document node |
215
| 'extc'=dir/saxonc | setProperty("extc", "dir/saxonc") | Specifies the full path to the C/C++ Saxon/C API library which contains the extension function. See example in samples/cppTests|
216
| 'm' | setProperty("m", "") | The presence of this property creates a message listener which is available in the C/C++ API of Saxon/C|
217

    
218

    
219

    
220
Example 1:
221
 
222
<pre><code>
223
	SaxonProcessor *processor = new SaxonProcessor(true);
224
	XsltProcessor * xslt = processor->newXsltTransformer();
225
	cout<<"Hello World"<<endl;
226
	cout<<"Test output: "<<xslt->transformFileToString("cat.xml","test.xsl")<<endl;
227
</code></pre>
228

    
229
Example 2:
230

    
231
<pre><code>
232
	SaxonProcessor * processor = new SaxonProcessor(false);
233
	XsltProcessor * xslt = processor->newXsltTransformer();
234

    
235
        xslt->setSourceFile("xml/foo.xml");
236
	XdmAtomicValue * xdmvaluex =processor->makeStringValue("Hello to you");
237
	if(xdmvaluex !=NULL){
238
		cerr<< "xdmvaluex ok"<<endl; 			
239
	}
240
	xslt->setParameter("a-param", xdmvaluex);
241
        const char * result = test->transformFileToString(NULL, "xsl/foo.xsl");
242
	if(result != NULL) {
243
		cerr<<result<<endl;
244
	} else {
245
		cerr<<"Result is NULL"<<endl;
246
	}
247
	processor->clearParameters(true);
248
	processor->clearProperties();
249
</code></pre>
250

    
251
Example 3:
252

    
253
<pre><code>
254
	SaxonProcessor * processor = new SaxonProcessor(false);
255
	Xslt30Processor * xslt = processor->newXslt30Transformer();
256

    
257
    xslt->setInitialMatchSelectionAsFile("cat.xml");
258
    const char * output = xslt->applyTemplatesReturningString("test.xsl");
259
	if(output !=NULL){
260
		cerr<< output<<endl; 			
261
	}
262
	XdmValue * values = new XdmValue(processor);
263
    values->addXdmItem((XdmItem*)processor->makeIntegerValue(10));
264
    values->addXdmItem((XdmItem*)processor->makeIntegerValue(5));
265
    values->addXdmItem((XdmItem*)processor->makeIntegerValue(6));
266
    values->addXdmItem((XdmItem*)processor->makeIntegerValue(7));
267
       
268
    xslt->setParameter("values",(XdmValue *)values);
269
        
270
    xslt->setInitialMatchSelection((XdmValue*)input);
271
	xslt->compileFromFile("test2.xsl");
272
    
273
    const char * rootValue = trans->callTemplateReturningString(NULL, "main");
274

    
275
	
276
	if(rootValue != NULL) {
277
		cerr<<rootValue<<endl;
278
	} else {
279
		cerr<<"Result is NULL"<<endl;
280
	}
281
	xslt->clearParameters(true);
282
	xslt->clearProperties();
283
</code></pre>
284

    
285
### XQuery ###
286

    
287
#### setParameter(string $name, XdmValue $value) Method ####
288

    
289
| Name | Example | Comment |
290
| :---- | :---- | :---- |
291
| 'node'=xdmValue | setParameter("node",xdmNodeObj) | Sets the source document for query. We also accept the parameter names 'item'.|
292
| param=xdmValue | setParameter("numParam",value1) | Set the value of external variable defined in the query |
293

    
294
#### setProperty(string $name, string $propValue) Method ####
295

    
296
The properties are a subset to those specified for running XQuery from the [command line](http://www.saxonica.com/documentation/index.html#!using-xquery/commandline).
297
| Name | Example | Comment |
298
| :---- | :---- | :---- |
299
| 'base'=base-URI | setProperty("base", "/home/username/example") | |
300
| 'q'=query-fileName | setProperty("q", "filename") | Identifies the file containing the query. |
301
|'qs'=query-string  | setProperty("qs", "saxon:line-number((//person)[1])") | Allows the query to be specified inline. |
302
|![serialization name]=value  | setProperty("!INDENT","yes") | Influence the serialization of the XML by the parameters specified with a exclamation mark with a name and the value. See [Documentation](http://saxonica.com/documentation/index.html#!javadoc/net.sf.saxon.s9api/Serializer/Property) |
303
| 'o'=filename | setProperty("o", "output.xml") | Sets the destination for the result of the XQuery to the specificed filename  |
304
| 'dtd'=boolean | setProperty("dtd", "true") | Set whether DTD validation should be applied to documents loaded |
305
| 's'=filename | setProperty("s", "filename") | Identifies the source file or directory. Mandatory unless the -it option is used. |
306
| 'resources'=directory | setProperty("resources", "dir") | Specifies the directory where the resources file are found|
307
| 'sa'=boolean | setProperty("sa", "true") | Invoke a schema-aware query. Requires Saxon-EE to be installed. |
308
| 'extc'=dir/saxonc | setProperty("extc", "dir/saxonc") | Specifies the full path to the C/C++ Saxon/C API library which contains the extension function. See example in samples/cppTests|
309

    
310
Example:
311

    
312
<pre><code>
313
	SaxonProcessor *processor = new SaxonProcessor(true);
314
	XsltProcessor * xslt = processor->newXQueryProcessor();
315
	 queryProc->setProperty("s", "cat.xml");
316

    
317
        queryProc->setProperty("q", "family.xq");
318
        queryProc->runQueryToString();
319
</code></pre>
320

    
321
### XPath ###
322

    
323
#### setParameter(string $name, XdmValue $value) Method ####
324

    
325
| Name | Example | Comment |
326
| :---- | :---- | :---- |
327
| 'node'=xdmValue | setParameter("node",xdmNodeObj) | Sets the source document for query. We also accept the parameter names 'item'.|
328
| param=xdmValue | setParameter("numParam",value1) | Set the value of external variable defined in the query |
329

    
330
#### setProperty(string $name, string $propValue) Method ####
331

    
332
| Name | Example | Comment |
333
| :---- | :---- | :---- |
334
|![serialization name]=value  | setProperty("!INDENT","yes") | Influence the serialization of the XML by the parameters specified with a exclamation mark with a name and the value. See [Documentation](http://saxonica.com/documentation/index.html#!javadoc/net.sf.saxon.s9api/Serializer/Property) |
335
| 'o'=filename | setProperty("o", "output.xml") | Sets the destination for the result of the XQuery to the specificed filename  |
336
| 'dtd'=boolean | setProperty("dtd", "true") | Set whether DTD validation should be applied to documents loaded |
337
| 's'=filename | setProperty("s", "filename") | Identifies the source file or directory. Mandatory unless the -it option is used. |
338
| 'resources'=directory | setProperty("resources", "dir") | Specifies the directory where the resources file are found|
339
| 'extc'=dir/saxonc | setProperty("extc", "dir/saxonc") | Specifies the full path to the C/C++ Saxon/C API library which contains the extension function. See example in samples/cppTests|
340

    
341
Example:
342

    
343
<pre><code>
344
	SaxonProcessor *processor = new SaxonProcessor();
345
	XPathProcessor * xpath = processor->newXPathProcessor();
346
 
347
	xpath->setContextFile("cat.xml");
348

    
349
	XdmValue * resultValues = xpath->evaluate("//person");
350
	
351
	if(resultValues == NULL) {
352
		 printf("result is null \n");
353
	} else {
354
		cout<<"Number of items="<<resultValues->size();
355
		for(int i =0; i< resultValues->size();i++){
356
			XdmItem * itemi = resultValues->itemAt(i);
357
			if(itemi == NULL) {
358
				cout<<"Item at position "<<i<<" should not be null";
359
				break;
360
			}
361
			cout<<"Item at "<<i<<" ="<<itemi->getStringValue(processor);		
362
		}
363
	}
364
	xpath->clearParameters(true);
365
  	xpath->clearProperties();
366
</code></pre>
367

    
368
### XML Schema Validation ###
369

    
370
| Name | Example | Comment |
371
| :---- | :---- | :---- |
372
| 'node'=xdmValue | setParameter("node",xdmNodeObj) | Sets the source document for the validation. We also accept the parameter names 'item'.|
373
| param=xdmValue | setParameter("numParam",value1) | Set the value of external variable defined in the query |
374

    
375
#### setProperty(string $name, string $propValue) Method ####
376

    
377
The properties are a subset to those specified for running the Schema Validator from the [command line](http://www.saxonica.com/documentation/index.html#!schema-processing/commandline).
378
| Name | Example | Comment |
379
| :---- | :---- | :---- |
380
|![serialization name]=value  | setProperty("!INDENT","yes") | Influence the serialization of the XML by the parameters specified with a exclamation mark with a name and the value. See [Documentation](http://saxonica.com/documentation/index.html#!javadoc/net.sf.saxon.s9api/Serializer/Property) |
381
| 'o'=filename | setProperty("o", "output.xml") | Sets the destination for the result of the XQuery to the specificed filename  |
382
| 'string'=xml-string | setProperty("string",xml-string) | Sets the source document aas a string for validation. Parsing will happen when the validate method has been called.|
383
| 'dtd'=boolean | setProperty("dtd", "true") | Set whether DTD validation should be applied to documents loaded |
384
| 's'=filename | setProperty("s", "filename") | Identifies the source file or directory. Mandatory unless the -it option is used. |
385
| 'resources'=directory | setProperty("resources", "dir") | Specifies the directory where the resources file are found|
386
| 'report-node'=boolean | setProperty("report-node", "true") | Flag for validation reporting feature. Error validation failures are represented in an XML document |
387
| 'report-file'=filename | setProperty("report-file", "filename") | Switches on the validation reporting feature. Validation failures collected and saved in an XML format in a file.|
388
| 'verbose'=boolean | setProperty("verbose", "true") | Set verbose mode to output to the terminal validation exceptions. The default is on providing the reporting feature has not been enabled.|
389
| 'element-type'=string | setProperty("element-type", "{uri}local") | Set the name of the required type of the top-level element of the document to be validated. The string should be in the Clark notation: {uri}local|
390
| 'element-name'=string | setProperty("element-name", "{uri}local") | Set the name of the required top-level element of the document to be validated (that is, the name of the outermost element of the document). The string should be in the Clark notation: {uri}local|
391
| 'lax'=boolean | setProperty("lax", "true") | The validation mode may be either strict or lax. Default is strict. This property indicates that lax validation is required.|
392

    
393
Example:
394

    
395
<pre><code>
396
	SaxonProcessor * processor = new SaxonProcessor(true);
397
	processor->setConfigurationProperty("xsdversion", "1.1");
398
	processor->setConfigurationProperty("http://saxon.sf.net/feature/multipleSchemaImports", "on");
399
	SchemaValidator * val = processor->newSchemaValidator();
400
	val->registerSchemaFromFile("family-ext.xsd");
401
      
402
	val->registerSchemaFromFile("family.xsd");
403
	val->setProperty("report-node", "true");	
404
	val->setProperty("verbose", "true");
405
	val->validate("family.xml");
406
	XdmNode * node = val->getValidationReport(); 
407
	if(node != NULL) {
408
		cout<<"Validation Report"<<node->getStringValue();
409
	} else {
410
		cout<<"Error: Validation Report is NULL";
411
	}
412
</code></pre>
413

    
414

    
415

    
416
<div id='php-api'/>
417
## PHP ##
418

    
419
#### PHP API ####
420
The PHP API is split up in the following class (links are to the C++ classes): SaxonProcessor, XsltProcessor, Xslt30Processor, XPathProcessor, XQueryProcessor  and SchemaValidator. We also have class for a sub-set of the  XDM data model: XdmValue, XdmNode, XdmItem and XdmAtomicValue.
421

    
422
The methods on these class are given below. For a more comprehensive description of the methods and their argument please see its counterpart in the C++ API.
423

    
424
#### Saxon\\SaxonProcessor class ####
425
<sup>PHP API</sup>
426

    
427

    
428
|  |  |
429
| ----: | :---- |
430
|     | *SaxonProcessor()* <br> *Default Constructor. Create an unlicensed Saxon Processor*   |
431
|   | SaxonProcessor(boolean $license)<br> *Constructor. Indicates whether the Processor requires features of Saxon that need a license file. If false, the method will creates a Configuration appropriate for Saxon HE (Home edition). If true, the method will create a Configuration appropriate to the version of the software that is running  Saxon-PE or Saxon-EE*  |
432
|  |SaxonProcessor(boolean $license, string $cwd) <br> *Constructor. Indicates whether the Processor requires features of Saxon that need a license file. The cwd arugment is used to manually set the current working directory used for executions of source files*  |
433
| XdmValue | createAtomicValue($primitive_type val)<br> *Create an Xdm Atomic value from any of the main primitive types (i.e. bool, int, float, double, string)* |
434
| Saxon\\XdmNode | parseXmlFromString(string $value) <br> *Create an XdmNode object. The $value is a lexical representation of the XML document* |
435
| Saxon\\XdmNode | parseXmlFromFile(string $fileName) <br> *Create an XdmNode object. Value is a string type and the file name to the XML document. File name can be relative or absolute. IF relative the cwd is used to resolve the file.* |
436
| void | setcwd(string $cwd) <br> *Set the current working directory used to resolve against files* |
437
| Saxon\\XdmNode | parseXmlFromFile(string $fileName) <br> *Create an XdmNode object. Value is a string type and the file name to the XML document. File name can be relative or absolute. IF relative the cwd is used to resolve the file.* |
438
| void | setResourceDirectory(string $dir) <br> *Set the resources directory of where Saxon can locate data folder* |
439
| void | setConfigurationProperty(string $name, string $value) <br> *Set a configuration property specific to the processor in use. Properties specified here are common across all the processors. See [Configuration Features](http://www.saxonica.com/documentation/index.html#!configuration/config-features)* |
440
| Saxon\\XsltProcessor | newXsltProcessor() <br> *Create an XsltProcessor in the PHP environment. An XsltProcessor is used to compile and execute XSLT sytlesheets* |
441
| Saxon\\Xslt30Processor | newXslt30Processor() <br> *Create an Xslt30Processor in the PHP environment specifically designed for XSLT 3.0 processing. An Xslt30Processor is used to compile and execute XSLT 3.0 sytlesheets. Use this class object (Xslt30Processor) instead of the XsltProcessor for XSLT 3.0 processing.* |
442
| Saxon\\XQueryProcessor | newXQueryProcessor() <br> *Create an XQueryProcessor in the PHP environment. An XQueryProcessor is used to compile and execute XQuery queries* |
443
| Saxon\\XPathProcesssor | newXPathProcessor() <br> *Create an XPathProcessor in the PHP environment. An XPathProcessor is used to compile and execute XPath expressions* |
444
| Saxon\\SchemaValidator | newSchemaValidator() <br> *Create a SchemaValidator in the PHP environment. A SchemaValidator provides capabilities to load and cache XML schema definitions. You can also valdiate source documents with egistered XML schema definitions* |
445
| string | version() <br> *Report the Java Saxon version* |
446
| void | registerPHPFunctions(string $library) <br> *Enables the ability to use PHP functions as XSLT functions. Accepts as parameter the full path of the Saxon/C PHP Extension library. This is needed to do the callbacks* |
447

    
448

    
449
#### Saxon\\XsltProcessor class ####
450
<sup>PHP API</sup>
451

    
452
|  |  |
453
| ----: | :---- |
454
| void | transformFileToFile(string $sourceFileName, string $stylesheetFileName, string outputfileName) <br> *Perform a one shot transformation. The result is stored in the supplied outputfile name.*  |
455
| string | transformFileToString(string $sourceFileName, string $stylesheetFileName) <br> *Perform a one shot transformation. The result is returned as a string. If there are failures then a null is returned* |
456
| XdmValue | transformFileToValue(string $fileName) <br> *Perform a one shot transformation. The result is returned as an XdmValue* |
457
| void | transformToFile() <br> *Perform the transformation based upon cached stylesheet and source document.* |
458
| string | transformToString() |
459
| XdmValue | transformToValue() <br> *Perform the transformation based upon cached stylesheet and any source document. Result returned as an XdmValue object. If there are failures then a null is returned* |
460
| void | compileFromFile(string $fileName) <br> *Compile a stylesheet suplied as by file name* |
461
| void | compileFromString(string $str) <br> *Compile a stylesheet received as a string.*  |
462
| void | compileFromValue(XdmNode $node)<br> *Compile a stylesheet received as an XdmNode.* |
463
| void | setOutputFile(string $fileName) <br> *Set the output file name of where the transformation result is sent* |
464
| void | setSourceFromXdmValue(XdmValue $value) <br> *The source used for a query or stylesheet. Requires an XdmValue object* |
465
| void | setSourceFromFile(string $filename) <br> *The source used for query or stylesheet. Requires a file name as string* |
466
| void | setParameter(string $name, XdmValue $value) <br> *Set the parameters required for XSLT stylesheet* |
467
| void | setProperty(string $name, string $value) <br> *Set properties for the stylesheet.* |
468
| void | clearParameters() <br> *Clear parameter values set* |
469
| void | clearProperties() <br> *Clear property values set* |
470
| void | exceptionClear() <br> *Clear any exception thrown* |
471
| string | getErrorCode(int $i)  <br> *Get the ith error code if there are any errors* |
472
| string | getErrorMessage(int $i) <br> *Get the ith error message if there are any error* |
473
| int | getExceptionCount() <br> *Get number of error during execution or evaluate of stylesheet* |
474

    
475

    
476
#### Saxon\\Xslt30Processor class ####
477
<sup>PHP API</sup>
478

    
479

    
480
|  |  |
481
| ----: | :---- |
482
| void | addPackages(array packageFileNames) <br> *File names to XsltPackages stored on filestore are added to a set of packages, which will imported later for use when compiling.*  |
483
| void | applyTemplatesReturningFile(string $stylesheetFileName) <br> *Invoke the stylesheet by applying templates to a supplied input sequence, Saving the results to file. The stylesheet file name argument can be supplied here. If null then the most recently compiled stylsheet is used.*  |
484
| string | applyTemplatesReturningString(string $stylesheetFileName) <br> *Invoke the stylesheet by applying templates to a supplied input sequence. The result is returned as a serialized string. The stylesheet file name argument can be supplied here. If null then the most recently compiled stylsheet is used.* |
485
| PyXdmValue | applyTemplatesReturningValue(string $stylesheetFileName) <br> *Invoke the stylesheet by applying templates to a supplied input sequence. the result is returned as an XdmValue object. The stylesheet file name argument can be supplied here. If null then the most recently compiled stylsheet is used.* |
486
| void | compileFromAssociatedFile(string xmlFileName)<br> *Get the stylesheet associated via the xml-stylesheet processing instruction (see http://www.w3.org/TR/xml-stylesheet/) with the document document specified in the source parameter, and that match the given criteria.  If there are several suitable xml-stylesheet processing instructions, then the returned Source will identify a synthesized stylesheet module that imports all the referenced stylesheet module.* |
487
| void | compileFromFile(string $fileName) <br> *Compile a stylesheet suplied as by file name* |
488
| void | compileFromString(string $str) <br> *Compile a stylesheet received as a string.*  |
489
| void | compileFromValue(XdmNode $node)<br> *Compile a stylesheet received as an XdmNode.* |
490
| void | compileFromFileAndSave(string $fileName, string outputFileName) <br> *Compile a stylesheet suplied as by file name and save as an exported file (SEF)* |
491
| void | compileFromStringAndSave(string $str, string outputFileName) <br> *Compile a stylesheet received as a string and save as an exported file (SEF).*  |
492
| void | compileFromValueAndSave(XdmNode $node, string outputFileName)<br> *Compile a stylesheet received as an XdmNode and save as an exported file (SEF).* |
493
| void | callFunctionReturningFile(string $FunctionName, array arguments, string outputfileName) <br> *Call a public user-defined function in the stylesheet. Here we wrap the result in an XML document, and sending this document to a specified file. Arguments: function name and array of XdmValue objects - 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. *  |
494
| string | callFunctionReturningString(string $FunctionName, array arguments) <br> *Call a public user-defined function in the stylesheet. Here we wrap the result in an XML document, and serialized this document to string value. Arguments: function name and array of XdmValue objects - 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.* |
495
| PyXdmValue | callFunctionReturningValue(string $FunctionName, array arguments) <br> *Call a public user-defined function in the stylesheet. Here we wrap the result in an XML document, and return the document as an XdmVale. Arguments: function name and array of XdmValue objects - 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.* |
496
| void | callTemplateReturningFile(string $stylesheetFileName, string $templateName, string outputfileName) <br> *Invoke a transformation by calling a named template. The result is stored in the supplied outputfile name. If the templateName argument is null then the xsl:iitial-template is used. Parameters supplied using setInitialTemplateParameters are made available to the called template.*  |
497
| string | callTemplateReturningString(string $stylesheetFileName, string $templateName) <br> *Invoke a transformation by calling a named template and return result as a string. If the templateName argument is null then the xsl:iitial-template is used. Parameters supplied using setInitialTemplateParameters are made available to the called template.* |
498
| PyXdmValue | callTemplateReturningValue(string $stylesheetFileName, string $templateName) <br> *Invoke a transformation by calling a named template and return result as an XdmValue. If the templateName argument is null then the xsl:iitial-template is used. Parameters supplied using setInitialTemplateParameters are made available to the called template.* |
499
| void | transformFileToFile(string $sourceFileName, string $stylesheetFileName, string outputfileName) <br> *Perform a one shot transformation. The result is stored in the supplied outputfile name.*  |
500
| XdmValue | transformFileToValue(string $fileName) <br> *Perform a one shot transformation. The result is returned as an XdmValue* |
501
| XdmValue | transformFileToString(string $fileName) <br> *Perform a one shot transformation. The result is returned as a stringe* |
502
| void | transformToFile() <br> *Perform the transformation based upon cached stylesheet and source document. Result is saved to the supplied file name* |
503
| string | transformToString() <br> *Perform the transformation based upon cached stylesheet and source document. Result is returned as a serialized string* |
504
| PyXdmValue | transformToValue() <br> *Perform the transformation based upon cached stylesheet and any source document. Result returned as an XdmValue object. If there are failures then a null is returned* |
505
| void | setInitialTemplateParameters(array parameters, bool tunnel) <br> *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 tunnel argument if set to true these values are to be used for setting tunnel parameters.* |
506
| void | setInitialMatchSelection() <br> *The initial value to which templates are to be applied (equivalent to the 'select' attribute of xsl:apply-templates)*|
507
| void | setInitialMatchSelectionAsFile <br> *The initial filename to which templates are to be applied (equivalent to the 'select' attribute of xsl:apply-templates) * |
508
| void | setGlobalContextItem <br> *Set the source document from an XdmNode for the transformation.*|
509
| void | setGlobalContextFromFile <br> *Set the source from file for the transformation.* |
510
| void | setOutputFile(string $fileName) <br> *Set the output file name of where the transformation result is sent* |
511
| void | setParameter(string $name, XdmValue $value) <br> *Set the parameters required for XSLT stylesheet* |
512
| void | setProperty(string $name, string $value) <br> *Set properties for the stylesheet.* |
513
| void | setJustInTimeCompilation(bool $value) <br> *ay whether just-in-time compilation of template rules should be used.* |
514
| void | setResultAsRawValue(bool $value) <br> *Set true if the return type of callTemplate, applyTemplates and transform methods is to return XdmValue, otherwise return XdmNode object with root Document node.* |
515
| void | clearParameters() <br> *Clear parameter values set* |
516
| void | clearProperties() <br> *Clear property values set* |
517
| void | exceptionClear() <br> *Clear any exception thrown* |
518
| string | getErrorCode(int $i)  <br> *Get the ith error code if there are any errors* |
519
| string | getErrorMessage(int $i) <br> *Get the ith error message if there are any error* |
520
| int | getExceptionCount() <br> *Get number of error during execution or evaluate of stylesheet* |
521

    
522

    
523

    
524
#### Saxon\\XQueryProcessor class ####
525
<sup>PHP API</sup>
526

    
527
|  |  |
528
| ----: | :---- |
529
| XdmValue | runQueryToValue() <br> *compile and evaluate the query. Result returned as an XdmValue object. If there are failures then a null is returned* |
530
| string | runQueryToString() <br> *compile and evaluate the query. Result returned as string. If there are failures then a null is returned* |
531
| void | runQueryToFile(string $outfilename) <br> *compile and evaluate the query. Save the result to file* |
532
| void | setQueryContent(string $str) <br> *query supplied as a string* |
533
| void | setQueryItem(XdmItem $item) <br> ** |
534
| void | setQueryFile($string $filename) <br> *query supplied as a file* |
535
| void | setContextItemFromFile(string $fileName) <br> *Set the initial context item for the query. Supplied as filename* |
536
| void | setContextItem(Xdm $obj) <br> *Set the initial context item for the query. Any one of the objects are accepted: XdmValue, XdmItem, XdmNode and XdmAtomicValue.* |
537
| void | setQueryBaseURI(string $uri) <br> *Set the static base URI for a query expressions compiled using this XQuery Processor. The base URI is part of the static context, and is used to resolve any relative URIS appearing within a query* |
538
| void | declareNamespace(string $prefix, string $namespace) <br> *Declare a namespace binding as part of the static context for XPath expressions compiled using this XQuery processor* |
539
| void | setParameter(string $name, XdmValue $value) <br> *Set the parameters required for XQuery Processor* |
540
| void | setProperty(string $name, string $value) <br> *Set properties for Query.* |
541
| void | clearParameters() <br> *Clear parameter values set* |
542
| void | clearProperties() <br> *Clear property values set* |
543
| void | exceptionClear() <br> *Clear any exception thrown* |
544
| string | getErrorCode(int $i) <br> *Get the ith error code if there are any errors* |
545
| string | getErrorMessage(int $i) <br> *Get the ith error message if there are any error* |
546
| int | getExceptionCount() <br> *Get number of error during execution or evaluate of query* |
547

    
548
#### Saxon\\XPathProcessor class ####
549
<sup>PHP API</sup>
550

    
551
|  |  |
552
| ----: | :---- |
553
| void | setContextItem(string $fileName) <br> *Set the context item from a XdmItem* |
554
| void | setContextFile(string $fileName) <br> *Set the context item from  file* |
555
| boolean | effectiveBooleanValue(string $xpathStr) <br> *Evaluate the XPath expression, returning the effective boolean value of the result.* |
556
| XdmValue | evaluate(string $xpathStr) <br> *Compile and evaluate an XPath expression, supplied as a character string. Result is an XdmValue* |
557
| XdmItem | evaluateSingle(string $xpathStr) <br> *Compile and evaluate an XPath expression whose result is expected to be a single item, with a given context item. The expression is supplied as a character string.* |
558
| void | declareNamespace(string $prefix, string $namespace) <br> *Declare a namespace binding as part of the static context for XPath expressions compiled using this XPathProcessor* |
559
| void | setBaseURI(string $uri) <br> *Set the static base URI for XPath expressions compiled using this XQuery Processor. The base URI is part of the static context, and is used to resolve any relative URIS appearing within a query* |
560
| void | setParameter(string $name, XdmValue $value) <br> *Set the parameters required for XQuery Processor* |
561
| void | setProperty(string $name, string $value) <br> *Set properties for Query.* |
562
| void | clearParameters() <br> *Clear parameter values set* |
563
| void | clearProperties() <br> *Clear property values set* |
564
| void | exceptionClear() <br> *Clear any exception thrown* 
565
| string | getErrorCode(int $i) <br> *Get the ith error code if there are any errors*  |
566
| string | getErrorMessage(int $i) <br> *Get the ith error message if there are any error* |
567
| int | getExceptionCount() <br> *Get number of error during execution or evaluate of stylesheet and query, respectively* | 
568

    
569
#### Saxon\\SchemaValidator class ####
570
<sup>PHP API</sup>
571

    
572
|  |  |
573
| ----: | :---- |
574
| void | setSourceNode(XdmNode $node) <br> *The instance document to be validated. Supplied as an Xdm Node* |
575
| void | setOutputFile(string $fileName) <br> *The instance document to be validated. Supplied file name is resolved and accessed* |
576
| void | registerSchemaFromFile(string $fileName) <br> *Register the Schema which is given as file name.* |
577
| void | registerSchemaFromString(string $schemaStr) <br> *Register the Schema which is given as a string representation.* |
578
| void | validate() <br> *Validate an instance document supplied as a Source object. Assume source document has already been supplied through accessor methods* | 
579
| void | validate(string $fileName) <br> *Validate an instance document supplied as a Source object. $filename - The name of the file to be validated. $filename can be null* |
580
| XdmNode | validateToNode() <br> *Validate an instance document supplied as a Source object with the validated document returned to the calling program. Assume source document has already been supplied through accessor methods* |
581
| XdmNode | validateToNode(string $fileName) <br> *Validate an instance document supplied as a Source object with the validated document returned to the calling program. $filename - The name of the file to be validated. $filename can be null* |
582
| XdmNode | getValidationReport <br> *Get the valdiation report produced after valdiating the soucre document. The reporting feature is switched on via setting the property on the SchemaValidator: validator.setProperty('report', 'true'). Return XdmNode* |
583
| void | setParameter(string $name, XdmValue $value) <br> *Set the parameters required for XQuery Processor* |
584
| void | setProperty(string $name, string $value) <br> *Set properties for Schema Validator.* |
585
| void | clearParameters() <br> *Clear parameter values set* |
586
| void | clearProperties() <br> *Clear property values set* |
587
| void | exceptionClear() <br> *Clear any exception thrown* 
588
| string | getErrorCode(int $i) <br> *Get the ith error code if there are any errors*  |
589
| string | getErrorMessage(int $i) <br> *Get the ith error message if there are any error* |
590
| int | getExceptionCount() <br> *Get number of error during execution of the validator* |
591
#### Saxon\\XdmValue class ####
592
<sup>PHP API</sup>
593

    
594
|  |  |
595
| ----: | :---- |
596
| XdmItem | getHead() <br> *Get the first item in the sequence* |
597
| XdmItem | itemAt(int $index) <br> *Get the n'th item in the value, counting from zero* |
598
| int |  size() <br> *Get the number of items in the sequence* |
599
|  | addXdmItem(XdmItem $item) <br> *Add item to the sequence at the end.* |
600

    
601

    
602
#### Saxon\\XdmItem class ####
603
<sup>PHP API</sup>
604

    
605
|  |  |
606
| ----: | :---- |
607
| string | getStringValue() <br> *Get the string value of the item. For a node, this gets the string value of the node. For an atomic value, it has the same effect as casting the value to a string. In all cases the result is the same as applying the XPath string() function.* |
608
| boolean |  isNode() <br> *Determine whether the item is a node value or not.* |
609
| boolean |  isAtomic() <br> *Determine whether the item is an atomic value or not.* |
610
|  XdmAtomicValue| getAtomicValue() <br> *Provided the item is an atomic value we return the XdmAtomicValue otherwise return null* |
611
| XdmNode |  getNodeValue() <br> *Provided the item is a node value we return the XdmNode otherwise return null* |
612

    
613
#### Saxon\\XdmNode class ####
614
<sup>PHP API</sup>
615

    
616
|  |  |
617
| ----: | :---- |
618
| string | getStringValue() <br> *Get the string value of the item. For a node, this gets the string value of the node.* |
619
| int | getNodeKind() <br> *Get the kind of node* |
620
| string | getNodeName <br> *et the name of the node, as a EQName* |
621
| boolean | isAtomic() <br> *Determine whether the item is an atomic value or a node. This method will return FALSE as the item is not atomic* |
622
| int | getChildCount() <br> *Get the count of child node at this current node* |
623
| int | getAttributeCount() <br> *Get the count of  attribute nodes at this node* |
624
| XdmNode | getChildNode(int index) <br> *Get the n'th child node at this node. If the child node selected does not exist then return null* |
625
| XdmNode | getParent() <br> *Get the parent of this node. If parent node does not exist then return null* |
626
| XdmNode | getAttributeNode(int $index) <br> *Get the n'th attribute node at this node. If the attribute node selected does not exist then return null* |
627
| string | getAttributeValue(int $index) <br> *Get the n'th attribute node value at this node. If the attribute node selected does not exist then return null* |
628

    
629
#### Saxon\\XdmAtomicValue class ####
630
<sup>PHP API</sup>
631

    
632
|  |  |
633
| ----: | :---- |
634
| string | getStringValue <br> *Get the string value of the item. For an atomic value, it has the same effect as casting the value to a string. In all cases the result is the same as applying the XPath string() function.* |
635
| boolean | getBooleanValue <br> *Get the value converted to a boolean using the XPath casting rules* |
636
| double | getDoubleValue <br> *Get the value converted to a double using the XPath casting rules. If the value is a string, the XSD 1.1 rules are used, which means that the string "+INF" is recognised* |
637
| long | getLongValue <Br> *Get the value converted to an integer using the XPath casting rules* |
638
| boolean | isAtomic <br> *Determine whether the item is an atomic value or a node. Return TRUE if the item is an atomic value* |
639

    
640

    
641

    
642

    
643

    
644
#### PHP unit tests ####
645

    
646
In the Saxon/C download please see the PHP unit tests (i.e. xslt30_PHPUnit.php i nthe samples/php directory) for XSLT. There are also same files for XSLT, XQuery, XPath and Schema Validator. The PHP test files are contained in the 'samples/php' folder along with associated files. Namely: xsltExamples.php, xslt30Examples.php, xqueryExamples.php, xpathExamples.php, validatorExamples.php. These files contain many useful examples which will get you started.
647

    
648
The unit tests run under [PHPUnit](https://phpunit.de/) for PHP 7.2 which can be downloaded and installed seperately in the same directory of the unit tests.
649

    
650
Example command:
651
    
652
    cd samples/php
653
    ./phpunit xslt30_PHPUnit.php
654

    
655
To run a single test:
656

    
657
    ./phpunit --filter testPipeline xslt30_PHPUnit.php
658

    
659

    
660
Example code in the new XSLT3.0 API:
661

    
662
<pre><code>
663
    <?php
664
        $saxonproc = new Saxon\\SaxonProcessor();
665
        $transformer = $saxonProc->newXslt30Processor();
666
        $transformer->compileFromString("<xsl:stylesheet version='2.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>" .
667
                  "<xsl:template name='go'><a/></xsl:template>" .
668
                  "</xsl:stylesheet>");
669
      
670
        $root = $transformer->callTemplateReturningValue("go");
671
        
672
        $node = $root->getHead()->getNodeValue();
673
    
674
    
675
    
676
    ?>
677

    
678

    
679
</code>
680
</pre>
681

    
682
Example of the old styled PHP API designed for older XSLT API:
683
<pre><code>
684
	<?php 
685
	    $xmlfile = "xml/foo.xml";
686
	    $xslFile = "xsl/foo.xsl";
687
		$proc = new Saxon\\SaxonProcessor();
688
        $version = $proc->version();
689
        echo 'Saxon Processor version: '.$version;
690
		$xsltProc = $saxonProc->newXsltProcessor();
691
        $xsltProc->setSourceFromFile($xmlfile);
692
        $xsltProc->compileFromFile($xslFile);      
693
        $result = $xsltProc->transformToString();               
694
		if($result != null) {               
695
		  echo '<b>exampleSimple1:</b><br/>';
696
		  echo 'Output:'.$result;
697
		} else {
698
			echo "Result is null";
699
		}
700
		$xsltProc->clearParameters();
701
		$xsltProc->clearProperties(); 
702
	?>
703
</code></pre>
704

    
705

    
706
In the example below we show how to debug if something unexpected is happening. It is also very useful to examine the apache error.log file:
707

    
708
<pre><code>
709
	<?php 
710
	        $xmlfile = "xml/foo.xml";
711
	        $xslFile = "xsl/foo.xsl";
712
		    $proc = new Saxon\\SaxonProcessor();
713
		    $xsltProc = $saxonProc->newXsltProcessor();
714
            $xsltProc->setSourceFromFile($xmlFile);
715
            $xsltProc->compileFromFile($xslFile);
716
                
717
            $result = $xsltProc->transformToString();
718
                
719
            if($result == NULL) {
720
                    $errCount = $xsltProc->getExceptionCount();
721
				    if($errCount > 0 ){ 
722
				        for($i = 0; $i < $errCount; $i++) {
723
					       $errCode = $xsltProc->getErrorCode(intval($i));
724
					       $errMessage = $xsltProc->getErrorMessage(intval($i));
725
					       echo 'Expected error: Code='.$errCode.' Message='.$errMessage;
726
					   }
727
						$xsltProc->exceptionClear();	
728
					}
729
                
730
                
731
                }                
732
            echo $result;
733
            $xsltProc->clearParameters();
734
		    $xsltProc->clearProperties();
735
	?>
736
</code></pre>
737

    
738

    
739
<div id='python-api'/>
740
## Python ##
741
The Saxon/C Python extension API has been developed using [Cython](https://cython.org/).
742
Saxon/C only supports Python3. Cython is required to build the extension library.
743

    
744
### Python API ###
745

    
746
The Python API is split up in the following class (links are to the equivalent [C++ classes](https://www.saxonica.com/saxon-c/doc/html/annotated.html)): [PySaxonProcessor](https://www.saxonica.com/saxon-c/doc/html/saxonc.html#PySaxonProcessor), 
747
[PyXsltProcessor](https://www.saxonica.com/saxon-c/doc/html/saxonc.html#PyXsltProcessor), [PyXslt30Processor](https://www.saxonica.com/saxon-c/doc/html/saxonc.html#PyXslt30Processor), [PyXPathProcessor](https://www.saxonica.com/saxon-c/doc/html/saxonc.html#PyXPathProcessor), [PyXQueryProcessor](https://www.saxonica.com/saxon-c/doc/html/saxonc.html#PyXQueryProcessor) and 
748
[PySchemaValidator](https://www.saxonica.com/saxon-c/doc/html/saxonc.html#PySchemaValidator). 
749
We also have class for a sub-set of the XDM data model: [PyXdmValue](https://www.saxonica.com/saxon-c/doc/html/saxonc.html#PyXdmValue), [PyXdmNode](https://www.saxonica.com/saxon-c/doc/html/saxonc.html#PyXdmNode), [PyXdmItem](https://www.saxonica.com/saxon-c/doc/html/saxonc.html#PyXdmItem) and [PyXdmAtomicValue](https://www.saxonica.com/saxon-c/doc/html/saxonc.html#PyXdmAtomicValue).
750

    
751
The methods on these class are given below. For a more comprehensive description of the methods and their argument please see its counterpart in the C++ API.
752

    
753
Please see the [Python API documentation](http://www.saxonica.com/saxon-c/doc/html/saxonc.html)
754

    
755

    
756
#### Python unit tests ####
757

    
758
There are a collection of Python unit test cases to be run with the [pytest](https://docs.pytest.org) framework. Test unit files: test_saxonc.py and test_saxon_Schema.py. 
759
See also some python example scripts saxon_example.py, saxon_example2.py and saxon_example3.py to get started with Saxon/C and Python
760

    
761
The pyunit tests can be run with the following command:
762

    
763
    cd Saxon.C.API/python-saxon
764
    pytest test_saxonc.py
765

    
766

    
767
Example Python script with Saxon/C API:
768

    
769
<pre>
770
     <code>
771
     with saxonc.PySaxonProcessor(license=False) as proc:        
772
        print(proc.version)
773
        #print(dir(proc))
774
        xdmAtomicval = proc.make_boolean_value(False)
775
     
776
        xsltproc = proc.new_xslt_processor()
777
        document = proc.parse_xml(xml_text="<out><person>text1</person><person>text2</person><person>text3</person></out>")
778
        xsltproc.set_source(xdm_node=document)
779
        xsltproc.compile_stylesheet(stylesheet_file="test2.xsl")
780
        xsltproc.set_just_in_time_compilation(True)
781
     
782
        output2 = xsltproc.transform_to_string()
783
        print(output2)
784
        print('test 0 \n')
785
        xml = """\
786
         <out>
787
             <person>text1</person>
788
             <person>text2</person>
789
             <person>text3</person>
790
         </out>"""
791
        xp = proc.new_xpath_processor()
792
         
793
        node = proc.parse_xml(xml_text=xml)
794
        print('test 1\n node='+node.string_value)
795
        xp.set_context(xdm_item=node)
796
        item = xp.evaluate_single('//person[1]')
797
        if isinstance(item,saxonc.PyXdmNode):
798
            print(item.string_value)
799

    
800
     </code>
801

    
802
</pre  
803

    
804
<div id='tech'/>
805
## Technical Information: ##
806

    
807
Saxon/C is built by cross compiling the Java code of Saxon 9.9.1.5 using the Excelsior Jet Enterprise edition (MP1).
808
This generates platform specific machine code, which we interface with C/C++ using the Java Native Interace (JNI).
809

    
810
The PHP interface is in the form of a C/C++ PHP extension to Saxon/C created using the Zend module API.
811

    
812
The Python interface is in the form of a Cython module interfaced with the C/C++ Saxon/C API.
813

    
814
The XML parser used is the one supplied by the Excelsior JET runtime. There are currently no links to libxml.
815

    
816
<div id='limitations'/>
817
## Limitations: ##
818

    
819
The following limitations apply to the 1.2.1 release:
820

    
821
* No support for the XdmFunction type in the Xdm data model
822

    
823

    
824
### Feedback/Comments: ###
825

    
826
Please use the help forums and bug trackers at [saxonica.plan.io](https://saxonica.plan.io/projects/saxon-c) if you need help or advice.
827

    
828

    
(50-50/51)