Project

Profile

Help

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

he / src / userdoc / extensions.xml @ d9cb5c62

1
<?xml version="1.0" encoding="utf-8"?>
2
<article id="extensions" title="Saxon Extensions">
3
  <h1>Saxon Extensions</h1>
4

    
5
  <p>This section describes the extensions and <dfn>implementation-defined features</dfn> provided
6
    with the Saxon product.</p>
7

    
8
  <p>If you want to implement your own extensions, see <a class="bodylink" href="/extensibility"
9
      >Extensibility Mechanisms</a>.</p>
10

    
11
  <aside>Most of the extensions described in this section require Saxon-PE (Professional Edition) or
12
    higher. A few work with Saxon-HE (Home Edition), and some require Saxon-EE (Enterprise Edition).
13
    Check the details for each extension.</aside>
14

    
15
  <p>The extensions described here were provided because there are things that are difficult to
16
    achieve, or inefficient, using standard XSLT/XQuery facilities alone. In some cases they are
17
    retained from earlier releases even though equivalent functionality is available using the
18
    standard language. As always, it is best to stick to the standard if you possibly can: and most
19
    things <i>are</i> possible, even if it's not obvious at first sight.</p>
20

    
21
  <p>All Saxon extensions require a namespace declaration
22
      <code>xmlns:saxon="http://saxon.sf.net/"</code> to appear. In XSLT this is typically declared
23
    on the <code>xsl:stylesheet</code> element; it is also useful to write
24
      <code>exclude-result-prefixes="saxon"</code> to prevent the Saxon namespace appearing in the
25
    result tree. In XQuery the namespace is declared by writing <code>declare namespace
26
      saxon="http://saxon.sf.net/";</code> in the Query prolog.</p>
27

    
28
  <p>If you use XSLT extension instructions such as <code>saxon:doctype</code>, it is also necessary
29
    to include the attribute <code>extension-element-prefixes="saxon"</code>. This does not apply,
30
    however, if you are only using extension functions.</p>
31

    
32
  <aside>XSLT uses the term "extension functions", XQuery calls them "external functions". They are
33
    the same thing.</aside>
34

    
35

    
36
  <p>For details of additional extensions available in XQuery only, see <a class="bodylink"
37
      href="/using-xquery/extensions">XQuery Extensions</a>.</p>
38

    
39
  <p>For details of extensions to XML Schema 1.1 used for schema processing, see <a class="bodylink"
40
      href="/schema-processing/extensions11">XML Schema 1.1 Extensions</a>.</p>
41

    
42
  <p>Saxon also provides a set of extension elements providing access to SQL databases, see <a
43
      class="bodylink" href="/sql-extension">Saxon SQL Extension</a>.</p>
44

    
45
  <p>Further information:</p>
46
  <nav>
47
    <ul/>
48
  </nav>
49

    
50
  <section id="functions" title="Extension functions">
51
    <h1>Extension functions</h1>
52

    
53
    <p>
54
      <i>This section describes extension functions built in to the Saxon product. For information
55
        on writing your own extension functions, see <a class="bodylink"
56
          href="/extensibility/functions">Writing extension functions (Java)</a> or <a
57
          class="bodylink" href="/extensibility/dotnetextensions">Writing extension functions
58
          (.NET)</a>.</i>
59
    </p>
60

    
61
    <p>Full details of all extension functions, along with functions in the core library, are found
62
      in the <a class="bodylink" href="/functions">Function Library</a>.</p>
63

    
64
    <aside>As a general policy, Saxon's extension functions require Saxon-PE or Saxon-EE. The vast
65
      majority are available in Saxon-PE; a few that are related to schema-aware processing or
66
      streaming require Saxon-EE. In some cases the source code of these extensions is open source
67
      code and can be compiled for use with the open-source Saxon-HE.</aside>
68

    
69
    <p>The extension functions in Saxon fall into three groups, described in the following
70
      subsections:</p>
71

    
72
    <ul>
73
      <li>
74
        <p><a class="bodylink" href="saxon-extension-functions">Saxon extension functions</a>
75
          defined by Saxonica and provided in the Saxon namespace
76
          <code>http://saxon.sf.net/</code></p>
77
      </li>
78
      <li>
79
        <p><a class="bodylink" href="exslt">EXSLT extensions</a> defined by the EXSLT initiative,
80
          using namespaces in the <code>http://exslt.org/...</code> family</p>
81
      </li>
82
      <li>
83
        <p><a class="bodylink" href="expath">EXPath extensions</a> defined by the EXPath initiative,
84
          using namespaces in the <code>http://expath.org/...</code> family</p>
85
      </li>
86
    </ul>
87

    
88
    <!--<p>There are two further groups of functions that deserve mention:</p>
89

90
    <ul>
91
      <li>
92
        <p>The mathematical and trigonometric functions in namespace
93
            <code>http://www.w3.org/2005/xpath-functions/math</code>. These functions (for example
94
            <code>sin</code>, <code>cos</code>, and <code>sqrt</code>) are defined in the XPath 3.0
95
          specification, though they are available in Saxon whether or not 3.0 syntax is enabled.
96
          For details see the <a class="bodylink" href="/functions"
97
            >Function Library</a>.</p>
98
      </li>
99
      <li>
100
        <p>The functions for handling maps, defined in the draft XSLT 3.0 specification. Saxon
101
          currently implements these in the namespace
102
            <code>http://www.w3.org/2005/xpath-functions/map</code>. They are available not only in
103
          XSLT, but also in XPath and XQuery. The functions do not require 3.0 syntax to be enabled,
104
          but new syntax associated with maps (the constructor syntax and the type designator) do
105
          require this. For details see the <a class="bodylink" href="/functions">Function
106
            Library</a>.</p>
107
      </li>
108
    </ul>-->
109

    
110

    
111
    <section id="saxon-extension-functions" title="Saxon extension functions">
112
      <h1>Saxon extension functions</h1>
113

    
114
      <p>These functions are listed and fully described, along with functions in the core library,
115
        in the <a class="bodylink" href="/functions">Function Library</a>.</p>
116

    
117
      <aside>These extension functions are available in Saxon-PE and Saxon-EE except where otherwise
118
        stated. They are not available in Saxon-HE.</aside>
119

    
120
      <p>The names of these functions are in the Saxon namespace <code>http://saxon.sf.net/</code>,
121
        conventionally prefixed <code>saxon</code>.</p>
122

    
123
      <p>You can use these functions simply by reference; you do not need to declare them or import
124
        them in any way. (Saxon makes no use of the <code>declare function ... external;</code>
125
        declaration in XQuery.)</p>
126

    
127
      <p>For example, to invoke the <code>saxon:evaluate()</code> function in XSLT, write:</p>
128
      <samp><![CDATA[<xsl:variable name="expression"
129
      select="concat('child::', $param, '[', $index, ']')"/>
130
..
131
<xsl:copy-of select="saxon:evaluate($expression)"
132
     xmlns:saxon="http://saxon.sf.net/"/>
133
]]></samp>
134

    
135
      <p>The equivalent in XQuery is:</p>
136
      <samp><![CDATA[declare namespace saxon="http://saxon.sf.net/";
137
declare variable $param as xs:string external;
138
declare variable $index as xs:integer external;
139
declare variable $expression :=
140
      concat('child::', $param, '[', $index, ']');
141
saxon:evaluate($expression)
142
]]></samp>
143

    
144
      <aside>Saxon extension functions are not as stable as functions in the core library. Many of
145
        them are retained over a long sequence of releases, but on occasions they are superseded by
146
        functions appearing in a standardized or portable library, and when this happens the Saxon
147
        version will eventually be dropped. There is a long tradition of functions that were first
148
        pioneered in Saxon eventually finding their way (typically in modified form) into a public
149
        standard.</aside>
150

    
151
    </section>
152

    
153
    <section id="exslt" title="EXSLT extensions">
154
      <h1>EXSLT extensions</h1>
155

    
156
      <p><a href="http://www.exslt.org/" class="bodylink">EXSLT</a> was an initiative to define a
157
        standardized set of extension functions and extension elements that can be used across
158
        different XSLT processors. Most of its activity was in the era of XSLT 1.0, and many of the
159
        functions that were defined are no longer needed in an XSLT 2.0 environment because there
160
        are suitable facilities in the standard. Nevertheless, Saxon implements some of these
161
        functions for compatibility reasons.</p>
162

    
163
      <p>Details of the functions supported (with some additional information about the Saxon
164
        implementation) can be found in the main <a class="bodylink" href="/functions">Function
165
          Library</a>.</p>
166

    
167
      <aside> These extensions are available in Saxon-PE and Saxon-EE "out of the box". Except for
168
        the Common module functions, they are not available in Saxon-HE. The source code is
169
        available in the Subversion repository on the
170
        <a href="http://dev.saxonica.com/" class="bodylink">dev.saxonica.com</a> site, package
171
          <code>net.sf.saxon.option.exslt</code>. The code is available under the Mozilla Public
172
        License version 2.0. </aside>
173

    
174
      <p>Saxon supports the <dfn>EXSLT</dfn> modules Common, Math, Sets, Dates and Times, and
175
        Random. These functions are available both in XSLT and in XQuery. The full list of EXSLT
176
        extension functions implemented is:</p>
177
      <ul>
178
        <li>
179
          <p>
180
            <strong>common (namespace http://exslt.org/common):</strong> node-set(), object-type().
181
            These are retained for compatibility with XSLT 1.0 stylesheets.</p>
182
        </li>
183
        <li>
184
          <p>
185
            <strong>math (namespace http://exslt.org/math):</strong> abs(), acos(), asin(), atan(),
186
            atan2(), constant(), cos(), exp(), highest(), log(), lowest(), max(), min(), power(),
187
            random(), sin(), sqrt(), tan() </p>
188
        </li>
189
        <li>
190
          <p>
191
            <strong>sets (namespace http://exslt.org/sets):</strong> difference(), intersection(),
192
            leading(), trailing(), has-same-node()</p>
193
        </li>
194
        <li>
195
          <p>
196
            <strong>dates-and-times* (namespace http://exslt.org/dates-and-times):</strong> add(),
197
            add-duration(), date(), date-time(), day-abbreviation(), day-in-month(), day-in-week(),
198
            day-in-year(), day-name(), day-of-week-in-month(), difference(), duration(),
199
            hour-in-day(), leap-year(), minute-in-hour(), month-abbreviation(), month-in-year(),
200
            month-name(), second-in-minute(), seconds(), sum(), time(), week-in-month(),
201
            week-in-year(), year()</p>
202
        </li>
203
        <li>
204
          <p>
205
            <strong>random (namespace http://exslt.org/random):</strong> random-sequence()</p>
206
        </li>
207
      </ul>
208

    
209
      <aside>* The specifications of the EXSLT date-and-time handling functions have
210
        little to say about timezones. Saxon generally handles inputs with or without a timezone,
211
        and uses the XPath 2.0 concept of implicit timezone to interpret the meaning of dates/times
212
        without a timezone. The current date and time used by EXSLT functions is the same as that
213
        used by the XPath 2.0 <a class="bodylink code" href="/functions/fn/current-dateTime"
214
          >current-dateTime()</a> function.</aside>
215

    
216
      <p>EXSLT extensions that overlap XSLT 2.0 functionality have sometimes been retained in cases
217
        where they have no impact on the Saxon core code, but in cases (such as
218
          <code>func:function</code>) where the semantics are inconveniently different from XSLT
219
        2.0, they have been withdrawn.</p>
220

    
221
    </section>
222

    
223
    <section id="expath" title="EXPath extensions">
224
      <h1>EXPath extensions</h1>
225

    
226
      <p><a href="http://www.expath.org/" class="bodylink">EXPath</a> is a more recent initiative to
227
        define a standardized set of extension functions and extension elements that can be used
228
        across different XSLT and XQuery processors.</p>
229

    
230
      <p>Saxon supports the EXPath <strong>file</strong> module since release 9.5. Since 9.6 the
231
          <strong>binary</strong> and <strong>archive</strong> modules are supported too. Note that
232
        the <strong>zip</strong> module was withdrawn at 9.5.1 and is now replaced by
233
          <strong>archive</strong> and that some of the functions of <strong>file</strong> 
234
        changed between 9.5 and 9.6 as result of specification changes.</p>
235

    
236
      <p>Details of the functions supported (with some additional information about the Saxon
237
        implementation) can be found in the main <a class="bodylink" href="/functions">Function
238
          Library</a>.</p>
239

    
240

    
241
      <h3>The EXPath file module</h3>
242

    
243
      <p>The file module provides a set of functions to examine and manipulate the local file
244
        system. For the specification of the file module see <a href="http://expath.org/spec/file"
245
          class="bodylink">EXPath File Module</a>. </p>
246
      <aside>These extension functions require Saxon-PE or Saxon-EE. Implemented since Saxon
247
        9.5.</aside>
248
      <p>All functions in the file module are implemented.</p>
249
      <!-- <p>The variables <code>$file:dir.separator</code> and <code>$file:path.separator</code> are
250
        not implemented.</p>-->
251
      <p>Note that many of the functions in this module have side-effects, and therefore need to be
252
        used with care to ensure that they are called the right number of times, and in the right
253
        order. The best way of achieving this is to imagine that a function like
254
          <code>file:write()</code> produces an invisible result, and that this invisible result
255
        needs to be inserted into the final result of the query or stylesheet. So, for example, if
256
          <code>&lt;body&gt;...&lt;/body&gt;</code> is an element being written to the result tree,
257
        then the function call <code>&lt;body&gt;{file:write(...)}&lt;/body&gt;</code> will always
258
        be evaluated exactly once. By contrast, a call appearing as the initializer of a variable
259
        (for example in <code>let $x := file:write(...) return ...</code>) might be evaluated
260
        multiple times or not at all, depending on how the variable is actually used.</p>
261
      <p>A good way to invoke functions with side-effects is to use the <a class="bodylink code"
262
        href="/extensions/instructions/do">saxon:do</a>
263
      extension instruction: for example <code>&lt;saxon:do action="file:create-dir('temp')"/></code>.
264
      This is because instructions within a sequence constructor are always evaluated sequentially, in the order written.</p>
265
      <aside>Avoid calling functions with side effects in the initializing expression of a variable. It is unpredictable whether and when
266
      such expressions are evaluated. They might not be evaluated at all, or they might be evaluated partially, or they
267
      might be evaluated in an unexpected order.</aside>
268
      <p>Functions in the EXPath file module use file paths that are specified as being relative to the
269
        "current working directory". If the Java system property <code>expath.base.directory</code>
270
        is present, this is taken as the current working directory. In other cases, Saxon interprets
271
        the file name using the rules of the Java method <code>File.getCanonicalFile()</code>.</p>
272
      <aside>Note that the UNIX concept of "current working directory" does not translate directly to Microsoft Windows.
273
        On Windows, systems, there is in effect a current drive and an active directory in each drive.
274
        A simple relative file name like <code>a.xml</code> is interpreted relative to the active directory
275
        of the current drive. A file name of the form <code>E:a.xml</code> is interpreted relative to
276
        the active directory of the named drive (<code>E:</code>). A file name in the form <code>\p\q\a.xml</code>
277
        is interpreted relative to the root directory of the current drive. More specifically, file names
278
        are interpreted using the rules of the Java method <code>File.getCanonicalFile()</code>.</aside>
279
      <p>On Windows, a file name starting "//" or "\\" is interpreted as a UNC file name. In particular, 
280
        the function <code>file:path-to-uri(name)</code> converts <code>//server/p/q/a.xml</code> to
281
        <code>file://server/p/q/a.xml</code> - that is, the server part of the UNC name becomes the authority
282
        part of the URI.</p>
283
        
284

    
285

    
286

    
287
      <h3>The EXPath binary module</h3>
288

    
289
      <p>The binary module defines a library of functions for manipulating binary data and
290
        converting between binary data and string and numeric forms. For the specification of the
291
        binary module see <a href="http://expath.org/spec/binary" class="bodylink">EXPath Binary
292
          Module</a>. The specification has been stabilised at a Version 1.0 status so the functions
293
        can be considered stable.</p>
294
      <aside>These extension functions require Saxon-PE or Saxon-EE. Implemented since Saxon
295
        9.6.</aside>
296
      <p>All functions in the binary module are implemented and tested. Note that this module does
297
        not provide binary file i/o - functions from the EXPath file module should be used for such
298
        operations.</p>
299

    
300

    
301

    
302
      <h3>The EXPath archive module</h3>
303

    
304
      <p>The archive module defines facilities for reading, creating and manipulating content
305
        arranged into archive (ZIP, JAR) collections. For the specification of the archive module
306
        see <a href="http://expath.org/spec/archive" class="bodylink">EXPath Archive Module</a>. </p>
307
      <aside>These extension functions require Saxon-PE or Saxon-EE. Implemented since Saxon
308
        9.6.</aside>
309
      <p>Most functions in the archive module are implemented and tested. Note that this module does
310
        not provide file i/o of archives directly - functions from the EXPath file module should be
311
        used for such operations, or are used indirectly by the archive-file system conversion
312
        functions.</p>
313
      <p>Two groups of the archive module functions exist - one using element structures, the other
314
        using maps - for details see <a href="http://expath.org/spec/archive#using.maps"
315
          class="bodylink">Using map types to describe entries and options</a>. Note that mechanisms
316
        for describing options and properties through elements and attributes are not yet finalised.
317
        If you are using XPath 3.0 then we suggest <b>strongly</b> that you use the map-based function
318
        forms (which have names ending in <code>-map</code>), as their specification is much more
319
        likely to be stable, and the functions are easier to use. </p>
320

    
321

    
322

    
323
      <h3>Other EXPath modules</h3>
324
      <p>Implementations of other EXPath modules may be available from third parties.</p>
325

    
326
    </section>
327

    
328

    
329

    
330
  </section>
331
  <section id="attributes" title="Extension attributes (XSLT only)">
332
    <h1>Extension attributes (XSLT only)</h1>
333

    
334
    <p>An extension attribute is an extra attribute on an XSLT-defined element. These attributes are
335
      all in the Saxon namespace <code>http://saxon.sf.net/</code>. This namespace needs to be
336
      declared in a namespace declaration, but it does not need to be listed in the
337
        <code>extension-element-prefixes</code> attribute.</p>
338

    
339
    <p>For example, the <code>saxon:assignable</code> attribute can be set as follows:</p>
340
    <samp><![CDATA[<xsl:variable name="counter" saxon:assignable="yes" 
341
    xmlns:saxon="http://saxon.sf.net/">
342
]]></samp>
343
    
344
    <p>Like standard attributes in no namespace, extension attributes in the Saxon namespace
345
    can be prefixed with an underscore and used as shadow attributes (evaluated with a static expression).
346
    For example, <code>saxon:_explain="{$EXPLAIN}"</code>, where <code>$EXPLAIN</code> is a global
347
    variable or parameter declared with <code>static="yes"</code>.</p>
348

    
349
    <p>The extension attributes provided with the Saxon product are as follows:</p>
350
    <nav>
351
      <ul/>
352
    </nav>
353
    
354
    <aside>For the <code>select</code> attribute on <code>xsl:when</code> and <code>xsl:otherwise</code>,
355
    and the <code>then</code> and <code>else</code> attributes on <code>xsl:if</code>, see 
356
      <a class="bodylink code" href="/extensions/xslt-syntax-extensions">XSLT Syntax Extensions</a></aside>
357
    
358
    <section id="as" title="saxon:as">
359
      <h1>saxon:as</h1>
360
      
361
      <aside>Requires Saxon-PE or Saxon-EE. Available since Saxon 9.9. Added to xsl:mode in Saxon 10.</aside>
362
      
363
      <p>This attribute may be set on most XSLT elements that have an <code>as</code> attribute 
364
        (<a class="bodylink code" href="/xsl-elements/variable">xsl:variable</a>, <a class="bodylink
365
          code" href="/xsl-elements/param">xsl:param</a>, <a class="bodylink code"
366
            href="/xsl-elements/with-param">xsl:with-param</a>, <a class="bodylink code"
367
              href="/xsl-elements/function">xsl:function</a>,
368
        <a class="bodylink code" href="/xsl-elements/template">xsl:template</a>: but not currently
369
        <code>xsl:accumulator</code>) to declare an additional
370
        more specific type for a value.</p>
371
      
372
      <p>For example:</p>
373
      <samp><![CDATA[<xsl:param name="options" 
374
   as="map(xs:string, xs:anyAtomicType*)"
375
   saxon:as="tuple(validate as xs:boolean, duplicates as xs:boolean, limit as xs:integer, 
376
      codes as xs:string*)"
377
   xmlns:saxon="http://saxon.sf.net/"
378
   select="map{'validate': true(), 'duplicates': false(), 'limit': 17, 
379
      'codes': ('USD', 'GBP', 'EUR')}"/>]]></samp>
380
      
381
      <samp><![CDATA[<xsl:variable name="sqlConnection" 
382
   saxon:as="javatype:java.sql.Connection"
383
   xmlns:saxon="http://saxon.sf.net/"
384
   xmlns:javatype="http://saxon.sf.net/java-type"
385
   select="..."/>]]></samp>
386
      
387
      <samp><![CDATA[<xsl:param name="when"
388
   required="yes"
389
   as="xs:anyAtomicType"
390
   saxon:as="union(xs:date, xs:time, xs:dateTime)"
391
   xmlns:saxon="http://saxon.sf.net/">]]></samp>
392
      
393
      <p>If both the <code>as</code> and <code>saxon:as</code> attributes are present, then the type given in the
394
      <code>saxon:as</code> attribute must be a subtype of the type given in the <code>as</code> attribute.</p>
395
      
396
      <p>The <code>saxon:as</code> attribute will be ignored by a conformant XSLT processor that does not recognize
397
      the Saxon namespace. The attribute therefore allows type information to be specified for use by Saxon, which
398
      will be ignored by other XSLT processors (this applies to XSLT 1.0 and 2.0 processors as well as XSLT 3.0 processors).
399
      It therefore allows stylesheets to take advantage of Saxon extensions to the sequence type syntax (notably,
400
      tuple types, union types, and type aliases; see <a class="bodylink"
401
        href="/extensions/syntax-extensions">Syntax extensions</a>) without sacrificing stylesheet portability.</p>
402
      
403
      <p>The <code>saxon:as</code> attribute can also be defined on the <a class="bodylink code"
404
        href="/xsl-elements/mode">xsl:mode</a> element. Used here, it 
405
      provides a default for the <code>as</code> or <code>saxon:as</code> attribute of all template rules defined in this
406
      mode. </p>
407
      
408
    </section>
409

    
410
    <section id="assignable" title="saxon:assignable">
411
      <h1>saxon:assignable</h1>
412
      
413
      <aside>Requires Saxon-PE or Saxon-EE.</aside>
414

    
415
      <p>This attribute may be set on a global <a class="bodylink code"
416
          href="/xsl-elements/variable">xsl:variable</a> or <a class="bodylink code"
417
          href="/xsl-elements/param">xsl:param</a> element. The permitted values are
418
          <code>yes</code> and <code>no</code>. If the variable is the subject of a <a
419
          class="bodylink code" href="/extensions/instructions/assign">saxon:assign</a> instruction,
420
        it must be set to the value <code>yes</code>. Setting this value to <code>yes</code> also
421
        ensures that the variable is actually evaluated, which is useful if the <code>select</code>
422
        expression calls extension functions with side-effects; without this, a variable that is
423
        never referenced may never be evaluated.</p>
424
    </section>
425

    
426
    <section id="asynchronous" title="saxon:asynchronous">
427
      <h1>saxon:asynchronous</h1>
428
      
429
      <aside>Requires Saxon-EE.</aside>
430

    
431
      <p>This attribute may be set on the <a class="bodylink code"
432
          href="/xsl-elements/result-document">xsl:result-document</a> instruction. The default for
433
        Saxon-EE is <code>yes</code>, which causes the instruction to be evaluated in a separate
434
        thread, if there is a spare thread available (the maximum number of threads used is
435
        configurable using <a class="bodylink code" href="/configuration/config-features"
436
          >Feature.RESULT_DOCUMENT_THREADS</a>).</p>
437

    
438
      <p>A possible reason for setting the value to <code>no</code> is that the stylesheet calls
439
        extension functions with side-effects, where it is important for the calls to be in the
440
        right order.</p>
441

    
442
      <p>Asynchronous processing of <code>xsl:result-document</code> is automatically suppressed if
443
        tracing (using a <code>TraceListener</code>) is enabled.</p>
444
    </section>
445
    
446
    <section id="capture" title="saxon:capture">
447
      <h1>saxon:capture</h1>
448
      
449
      <aside>Requires Saxon-PE or Saxon-EE. Available since Saxon 9.9.</aside>
450
      
451
      <p>This attribute may be set on an <a class="bodylink code"
452
        href="/xsl-elements/accumulator-rule">xsl:accumulator-rule</a> element. It has no effect
453
      unless the accumulator is declared streamable and the rule has <code>phase="end"</code>. It is intended
454
        for use when the accumulator rule matches an element node. The value
455
      is a boolean with the default "no".</p>
456
      
457
      <p>The effect of setting this attribute is that the code for computing the new accumulator
458
      value when the element end tag is encountered now has access to a snapshot copy of the matched
459
      element (as if taken using the <a class="bodylink code"
460
        href="/functions/fn/snapshot">fn:snapshot</a> function), and is no longer required to be
461
        motionless.</p>
462
      
463
      <p>This means that if you want access to the typed value or string value of an element, you
464
      can now get this directly with a rule that matches the element, rather than having to write
465
      rules that match the element's text node children.</p>
466
      
467
      <p>It also opens up additional possibilities. For example:</p>
468
      
469
      <ul>
470
        <li>If a large document has a short header section containing metadata, you can capture
471
        a copy of the header in an accumulator, and the header then becomes available throughout
472
        the rest of the document processing using the <a class="bodylink code"
473
          href="/functions/fn/accumulator-after">accumulator-after()</a> function.</li>
474
        <li>If you want to produce a sorted index of terms that are marked up using <code>glossary</code>
475
        elements scattered throughout the document, you can define an accumulator that retains snapshot
476
        copies of all the <code>glossary</code> entries (use <code>select="($value, .)"</code> in the
477
          accumulator rule). At the end of processing, you can sort and group these glossary entries,
478
        and because they are snapshot copies retaining all the attributes of ancestors, you can link
479
        them to the <code>id</code> anchors of the containing sections.</li>
480
        
481
      </ul>
482
    </section>
483

    
484
    <section id="explain" title="saxon:explain">
485
      <h1>saxon:explain</h1>
486
      
487
      <aside>Requires Saxon-PE or Saxon-EE.</aside>
488

    
489
      <p>This attribute may be set on an <a class="bodylink code" href="/xsl-elements/template"
490
        >xsl:template</a> or <a class="bodylink code" href="/xsl-elements/function"
491
          >xsl:function</a> declaration. The permitted values are <code>yes</code> and
492
          <code>no</code>. If the value is <code>yes</code>, then at compile time Saxon outputs (to
493
        the standard error output) a representation of the optimized expression tree for the
494
        template or function containing that instruction. The tree is represented by indentation.
495
        For example, consider this source code:</p>
496
      <samp><![CDATA[<xsl:variable name="p" select="0"/>
497

    
498
 <xsl:template match="/" saxon:explain="yes" xmlns:saxon="http://saxon.sf.net/" exclude-result-prefixes="saxon">
499
   <a>
500
     <xsl:choose>
501
     <xsl:when test="$p != 0"><xsl:value-of select="1 div $p"/></xsl:when>
502
     <xsl:otherwise>12</xsl:otherwise>
503
     </xsl:choose>
504
   </a>
505
 </xsl:template>]]></samp>
506

    
507
      <p>This produces the output:</p>
508
      <samp><![CDATA[Optimized expression tree for template at line 8 in file:/e:/temp/test.xsl:
509
<directElement name="a" validation="skip">
510
  <valueOf>
511
    <literal value="12" type="xs:string"/>
512
  </valueOf>
513
</directElement>]]></samp>
514

    
515
      <p>This indicates that the template has been reduced to an instruction to create an element
516
        with name <code>a</code>, whose content is a single text node holding the string "12". This
517
        is because Saxon has established at compile time that it will always take the "otherwise"
518
        branch of the <code>xsl:choose</code> instruction. There is no <code>xsl:value-of</code>
519
        instruction in the source code, but the literal text node "12" is compiled to the same code
520
        as if the user had written <code>&lt;xsl:value-of select="'12'"/&gt;</code></p>
521

    
522
      <p>To get this output for all templates and functions in the stylesheet, you can use the
523
          <code>-explain</code> option on the command line.</p>
524
    </section>
525
    
526
    <section id="line-numbering" title="saxon:line-numbering">
527
      <h1>saxon:line-numbering</h1>
528
      
529
      <aside>Requires Saxon-PE or Saxon-EE. Available since Saxon 9.9.1.</aside>
530
      
531
      <p>This attribute may be set on the <a class="bodylink code"
532
        href="/xsl-elements/source-document">xsl:source-document</a> instruction to enable line numbering and column numbering for
533
        the document being read. The permitted values are: <code>yes|true|1</code> or <code>no|false|0</code>.</p>
534
      
535
      <p>If line and column numbering is enabled for a document, the line and column number of an element node in the document
536
        can be obtained using the extension functions <a class="bodylink code"
537
          href="/functions/saxon/line-number">saxon:line-number</a> and <a class="bodylink code"
538
            href="/functions/saxon/column-number">saxon:column-number</a> respectively.</p>
539
      
540
      <p>Line numbering of source documents can also be enabled using the configuration option 
541
        <a class="bodylink code"
542
          href="/configuration/config-features">Feature.LINE_NUMBERING</a> or the command-line
543
      option <code>-l</code> (letter ell).</p>
544
      
545
      <p>Assuming the XML parser is conformant with the SAX specification, the line and column number reported for an 
546
        element represent the position of the "&gt;" character at the end of the start tag.</p>
547
      
548
    </section>
549

    
550
    <section id="memo-function" title="saxon:memo-function">
551
      <h1>saxon:memo-function</h1>
552

    
553
      <aside>Requires Saxon-PE or Saxon-EE. When running under Saxon-HE, this attribute is ignored
554
        with a warning.</aside>
555

    
556
      <p>This attribute may be set on the <a class="bodylink code" href="/xsl-elements/function"
557
          >xsl:function</a> element. The permitted values are <code>yes</code> and <code>no</code>.
558
        Specifying <code>yes</code> indicates that Saxon should remember the results of calling the
559
        function in a cache, and if the function is called again with the same arguments, the result
560
        is retrieved from the cache rather than being recalculated. Don't use this if the function
561
        has side-effects (for example, if it calls <a class="bodylink code"
562
          href="/extensions/instructions/assign">saxon:assign</a>, or an extension function with
563
        side-effects). Don't use it if the function accesses context information such as the context
564
        node or <code>position()</code> or <code>last()</code>. And be careful if the function
565
        constructs and returns a temporary tree: the effect will be that the function returns the
566
        same tree each time, rather than a copy of the tree (this difference will only show up if
567
        you compare the identity of nodes in the two trees).</p>
568

    
569
      <p>From Saxon 9.6, when XSLT 3.0 is enabled, the same effect can be achieved by setting the
570
        attributes <code>cache="full"</code> and <code>identity-sensitive="no"</code> on the
571
          <code>xsl:function</code> element.</p>
572
    </section>
573
    
574
    <section id="on-duplicates" title="saxon:on-duplicates">
575
      <h1>saxon:on-duplicates</h1>
576
      
577
      <aside>Requires Saxon-PE or Saxon-EE. Available since Saxon 10.</aside>
578
      
579
      <p>The extension attribute <code>saxon:on-duplicates</code> is available on the <code>xsl:map</code>
580
      instruction to define how duplicate keys are to be handled. The value is an XPath expression that evaluates
581
      to a function. If the constructed map has duplicate keys, this function is called to determine how they
582
      are to be handled. The function takes two arguments, being two values for the key, and it returns a combined
583
      value to be used in the map with that key. For example if the function is <code>function($a, $b) { return max(($a, $b)) }</code>
584
      then the value in the final map will be the maximum of the values in the input.</p>
585
      
586
      <p>The function can also throw an error, reproducing the default behaviour if no function is specified.</p>
587
    </section>
588
      
589
    
590
    <section id="options" title="saxon:options">
591
      <h1>saxon:options</h1>
592
      
593
      <aside>Requires Saxon-PE or Saxon-EE. Available since Saxon 9.9.</aside>
594

    
595
      <p>An extension attribute <code>saxon:options</code> is available on the <a class="bodylink code"
596
        href="/xsl-elements/evaluate">xsl:evaluate</a> instruction: the value is an expression,
597
        which must evaluate to a map. The map allows additional Saxon-specific options for expression evaluation to be defined.</p>
598
      
599
      <p>Two options are defined:</p>
600
      
601
      <ul>
602
        <li>
603
          <p><b>allow-any-namespace</b></p>
604
          <p>If this option is set to the value <code>true()</code>, the XPath expression may reference schema components that
605
            are present in the Saxon <code>Configuration</code> whether or not they have been imported into the stylesheet
606
            using <code>xsl:import-schema</code>.</p>
607
        </li>
608
        <li>
609
          <p><b>default-collation</b></p>
610
          <p>The value of this option is a collation URI. This allows the default collation for evaluating the target
611
            expression to be selected dynamically (standard XSLT 3.0 facilities only allow it to be selected statically).</p>
612
        </li>
613
        
614
      </ul>
615
    </section>
616
    
617
    <section id="strip-space" title="saxon:strip-space">
618
      <h1>saxon:strip-space</h1>
619
      
620
      <aside>Requires Saxon-PE or Saxon-EE. Available since Saxon 9.9.1.</aside>
621
      
622
      <p>This attribute may be set on the <a class="bodylink code"
623
        href="/xsl-elements/source-document">xsl:source-document</a> instruction to specify whitespace
624
        stripping for the document being read. The permitted values are: <code>#all</code> strips all
625
        whitespace text nodes; <code>#none</code> means no whitespace stripping; <code>#ignorable</code>
626
        strips whitespace in elements declared as having element-only content; and <code>#default</code>
627
        follows the rules in <a class="bodylink code" href="/xsl-elements/strip-space">xsl:strip-space</a>/<a
628
          class="bodylink code" href="/xsl-elements/preserve-space">xsl:preserve-space</a> declarations.</p>
629
      
630
    </section>
631

    
632
    <section id="threads" title="saxon:threads">
633
      <h1>saxon:threads</h1>
634

    
635
      <aside>Requires Saxon-EE. When not running under Saxon-EE, this attribute is ignored with a
636
        warning.</aside>
637

    
638
      <p>This attribute may be set on the <a class="bodylink code" href="/xsl-elements/for-each"
639
          >xsl:for-each</a> instruction. The value must be an integer. When this attribute is used
640
        with Saxon-EE, the items selected by the <code>select</code> expression of the instruction
641
        are processed in <dfn>parallel</dfn>, using the specified number of threads.</p>
642

    
643
      <p>The threads are allocated on a round-robin basis: for example if <code>threads="3"</code>
644
        is specified, then the first item will be processed using thread 1, the second using thread
645
        2, the third using thread 3, the fourth using thread 1 again, and so on. These threads are
646
        in addition to the main control thread (so there will be 4 threads in total). Before firing
647
        off the processing of the third item, the control thread will read off the results of
648
        processing the first item, and send them to the destination of the <code>xsl:for-each</code>
649
        instruction.</p>
650

    
651
      <p>It is possible to specify <code>saxon:threads="1"</code>. In this case all the items in the
652
        input will be processed sequentially, but asynchronously with the thread that reads the
653
        items in the input sequence.</p>
654

    
655
      <p>Processing using multiple threads can take advantage of <dfn>multi-core CPUs</dfn>.
656
        However, there is an overhead, in that the results of processing each item in the input need
657
        to be buffered. The overhead of coordinating multiple threads is proportionally higher if
658
        the per-item processing cost is low, while the overhead of buffering is proportionally
659
        higher if the amount of data produced when each item is processed is high. Multi-threading
660
        therefore works best when the body of the <code>xsl:for-each</code> instruction performs a
661
        large amount of computation but produces a small amount of output.</p>
662

    
663
      <p>It is possible to combine multi-threading with sorting. However, the input is first read
664
        and sorted synchronously, and the items in the sorted sequence are then processed in
665
        parallel.</p>
666

    
667
      <p>The effect of using extensions that have side-effects (including <a class="bodylink code"
668
          href="/extensions/instructions/assign">saxon:assign</a>) in a multi-threaded loop is
669
        undefined (and probably fatal).</p>
670

    
671
      <p><dfn>Multi-threaded processing</dfn> is available only with Saxon-EE. The attribute
672
          <code>saxon:threads</code> is ignored with a warning if Saxon-EE is not in use. Under
673
        Saxon-EE it may also be disabled using the configuration option <a class="bodylink code"
674
          href="/configuration/config-features">Feature.ALLOW_MULTITHREADING</a> or
675
          <code>xslt/@allowMultiThreading='false'</code> in the configuration file. Multi-threaded
676
        processing is also disabled if code is compiled with tracing enabled, for example by using
677
        the <code>-T</code> option on the command line or by using an IDE debugger (this is because
678
        otherwise, the trace events would be hopelessly intermingled).</p>
679

    
680
      <p>With multi-threaded processing, the output of different <a class="bodylink code"
681
          href="/xsl-elements/message">xsl:message</a> instructions may appear in an unpredictable
682
        order. However, Saxon ensures that the <code>xsl:message</code> instruction is atomic, so
683
        one message will be completed before another starts. The same is true of the output from the
684
          <a class="bodylink code" href="/functions/fn/trace">trace()</a> function call.</p>
685
    </section>
686
    
687
    <section id="time" title="saxon:time">
688
      <h1>saxon:time</h1>
689
      
690
      <aside>Requires Saxon-PE or Saxon-EE. Available since Saxon 9.8.</aside>
691
      
692
      <p>This attribute may be set on the <a class="bodylink code" href="/xsl-elements/message">xsl:message</a>
693
        element.</p>
694
      
695
      <p>The value is a boolean. If set to true (or yes|1) then a timestamp will be added to the output message.</p>
696
    </section>
697
    
698
    <section id="trace" title="saxon:trace">
699
      <h1>saxon:trace</h1>
700
      
701
      <aside>Requires Saxon-PE or Saxon-EE. Available since Saxon 9.8.</aside>
702
      
703
      <p>The attribute <code>saxon:trace</code> on the <a class="bodylink code"
704
        href="/xsl-elements/accumulator">xsl:accumulator</a> element causes a trace message to be
705
        output (to the Configuration's Logger) whenever the value of the accumulator changes. The
706
        message includes the name of the accumulator, the path of the node, and the new accumulator
707
        value.</p>
708
      
709
      <p>Since 9.9.1, the attribute can also be used on the <a class="bodylink code"
710
        href="/xsl-elements/mode">xsl:mode</a> element. It causes tracing (messages output to the
711
        Configuration's Logger) of all template rules executed in the mode, showing the nodes selected by
712
        <code>xsl:apply-templates</code> and the rules used to process them.</p>
713
    </section>
714
  </section>
715
  <section id="syntax-extensions" title="XPath and XQuery Syntax Extensions">
716
    <h1>XPath and XQuery Syntax Extensions</h1>
717
    
718
    <p>Saxon provides a number of extensions to XPath and XQuery syntax. Because use of these extensions makes your code non-conformant
719
    with W3C specifications, these extensions are available only if explicitly enabled. This can be achieved using the configuration option
720
      <a class="bodylink code"
721
        href="/configuration/config-features">Feature.ALLOW_SYNTAX_EXTENSIONS</a> (use <code>--allowSyntaxExtensions:on</code> on the command line, 
722
      or <code>global/@allowSyntaxExtensions="true"</code> in the configuration file).</p>
723
    
724
    <aside>Extended type syntax is automatically enabled in the <code>saxon:as</code> attribute.</aside>
725
    
726
    <p>Like other Saxon extensions, these require Saxon-PE or higher.</p>
727
    
728
    <p>Further information:</p>
729
    <nav>
730
      <ul/>
731
    </nav>
732
    
733
    <section id="union-types" title="Union types">
734
    <h1>Union types</h1>
735
    
736
      <aside>Requires Saxon-EE, with syntax extensions enabled. Available since Saxon 9.8.</aside>
737

    
738
    <p>A construct of the form <code class="bold">union(type1, type2, type3)</code> can be used to define simple 
739
      unions of atomic types. For example, <code>union(xs:base64Binary, xs:hexBinary)</code>
740
      defines a union type whose members are <code>xs:base64Binary</code> and <code>xs:hexBinary</code>, while
741
      <code>union(xs:date, xs:time, xs:dateTime)</code> defines a union type whose members are <code>xs:date</code>,
742
      <code>xs:time</code>, and <code>xs:dateTime</code>. These types can conveniently be used in function signatures
743
      when writing a function that is designed to take arguments of more than one type.</p>
744
    
745
    <p>The names between the parentheses are strictly QNames (not general ItemTypes) and must refer to named atomic or 
746
      union types. If one of the members is a union type then it must be a "generalized atomic type"
747
    in the sense of the XPath 3.1 specification: that is, it must not contain any list types,
748
    and must not be derived by restriction from another union type.</p>
749
    
750
    <p>The order of member type names is significant, in that it determines the order used for casting or validating strings.</p>
751
    
752
    <p>This construct can be used anywhere that a conventional union
753
      type name defined in a schema would be recognized, for example in <code>instance of</code> and <code>cast as</code>
754
      expressions, in the <code>as</code> attribute of variable and function declarations, or in <code>typeswitch</code>
755
      expressions. The semantics are exactly the same as if the union type were declared in an imported schema and
756
    referenced by name.</p>
757
      
758
      <p>Union types can also be used in patterns, for example a template defined with 
759
        <code>match="union(xs:date, xs:time)"</code> will match atomic values of those types.
760
      Such a pattern is allocated a default priority designed to reflect the type hierarchy,
761
      so if U is a subtype of V, then the pattern corresponding to U will have a higher priority
762
      than the pattern corresponding to V. However, the algorithm does not ensure that ambiguous
763
      union patterns have the same priority, so ambiguities may go undetected.</p>
764
      
765
      <p>The pattern <code>match="atomic(xs:date)"</code> works in the same way; it can be
766
      regarded as syntactic sugar for a union with only one member.</p>
767
      
768
      <p>Two additional Saxon extensions help to improve the usability of union types:</p>
769
      
770
      <ul>
771
        <li>A commonly used type can be referenced using a <b>type alias</b>, for example
772
          <code>as="type(my:date-or-time)"</code>. Type aliases are available in both XSLT and XQuery,
773
          and are described in <a class="bodylink"
774
            href="/extensions/syntax-extensions/type-aliases">Type Aliases</a>. Type aliases go some way towards
775
          hiding the implementation details of the type, and allowing the implementation to be changed
776
          without affecting users of the function library; in addition they simply make the code more
777
          readable.</li>
778
        <li>In XSLT only, elements that have an <code>as</code> attribute to define the type
779
          of a variable, function, or parameter, also have an optional <a class="bodylink code"
780
            href="/extensions/attributes/as">saxon:as</a> attribute
781
          which allows additional type information to be supplied using Saxon extension syntax.
782
          If both attributes are present, then the type specified in <code>saxon:as</code>
783
          must be a subtype of the type specified in the <code>as</code> attribute. Typical usage
784
          might be <code>&lt;xsl:param name="x" as="xs:anyAtomicType" saxon:as="union(xs:date, xs:time, xs:dateTime)"/></code>.
785
          This device allows union types to be used without compromising the portability of the stylesheet
786
          to an XSLT 3.0 processor that does not recognize Saxon's extension syntax (an XSLT 3.0
787
          processor that does not recognize the <code>saxon:as</code> attribute is required to ignore it).</li>
788
      </ul> 
789
    
790
    <p>For example, the following code defines an XQuery function that formats a date, time, dateTime, or
791
    a string in the form of a date, time, or dateTime using the appropriate variant of the format-date/time
792
    function:</p>
793
    
794
    <samp><![CDATA[declare function local:format(
795
              $in as union(xs:dateTime, xs:date, xs:time, xs:string), 
796
              $fmt as xs:string) as xs:string {
797
   typeswitch ($in) 
798
   case xs:dateTime return format-dateTime($in, $fmt)
799
   case xs:date return format-date($in, $fmt)
800
   case xs:time return format-time($in, $fmt)
801
   case xs:string return local:format($in cast as union(xs:dateTime, xs:date, xs:time), $fmt)
802
   default return error()
803
   };    
804
local:format("2016-10-07", $fmt)]]></samp>
805
    </section>
806
    <section id="tuple-types" title="Tuple types">
807
    
808
    <h1>Tuple types</h1>
809
    
810
      <aside>Requires Saxon-PE or Saxon-EE, with syntax extensions enabled. Available since Saxon 9.8; 
811
        revised in 9.9; further revised in 10.</aside>
812
    
813
    <p>Wherever an item type can be used (for example, in the type signature of a function or variable,
814
    or in an <code>instance of</code> expression), Saxon allows a tuple type to appear. The syntax is:</p>
815
    
816
      <samp>"tuple" "(" fieldName ("as" sequenceType)? ("," fieldName ("as" sequenceType)? )* ("," "*")? ")"</samp>
817
    
818
    <p>where <code>fieldName</code> is either an NCName or a string literal. A final ", *" at the end of the list of fields indicates that the tuple
819
    type is <i>extensible</i>: additional fields beyond those that are explicitly declared are permitted to appear in the map. If the "as"
820
    clause is absent for any field, the assumed type is <code>item()+</code>.</p>
821
    
822
    <p>For example:</p>
823
    
824
      <samp>tuple(ssn as xs:string, emp as element(employee))</samp>
825
     
826
      
827
    <p>or: </p>
828
      
829
      <samp>tuple('first name', 'middle initial', 'last name', *)</samp>
830
    
831
      
832
      <p>The instances of a tuple type are maps. A tuple type is essentially a way of defining a more
833
      precise type for maps. The first example will be satisfied by any map that has an entry whose key is "ssn" and whose
834
      value is a string, plus an entry whose key is "emp" and whose value is an <code>employee</code> element. The second
835
    example matches any map with entries having the keys "first name" and "middle initial" and "last name, regardless of the 
836
    types of the values. Because the default type <code>item()+</code> does not permit an empty sequence, all three
837
    fields are required.</p>
838
    
839
    <p>More formally, a value <code>M</code> is an instance of a tuple type <code>tuple(N1 as T1, N2 as T2, ...)</code> if
840
    and only if all the following conditions are true:</p>
841
    
842
    <ol>
843
      <li><p><code>M is a map</code></p></li>
844
      <li><p>For every (<code>N</code>, <code>T</code>) pair in the tuple definition <code>map:get(M, N) instance of T</code> 
845
        returns true. (Note, this allows the case where there is no entry with key <code>M</code>, provided that the type <code>T</code>
846
      permits an empty sequence.)</p></li>
847
      <li><p>If the tuple type is not extensible (that is, there is no final ", *" after the list of field names), then every key present in the map is a string
848
      equal to one of the field names appearing in the tuple definition, when compared using codepoint collation.</p></li>
849
    </ol>
850
    
851
    <p>So for every field defined in the tuple definition, the map will typically contain an entry whose key
852
    matches the field name and whose value matches the corresponding type. The entry is allowed to be absent only
853
    if the type definition indicates that an empty sequence would be acceptable. Additional entries are allowed only if the type definition indicates
854
    that it is extensible.</p>
855
      
856
      <aside>The default type is <code>item()+</code>, which allows the value of the corresponding field
857
      to be anything other than an empty sequence. If you want to make the field optional, you need to assign
858
      a type that allows the empty sequence, for example <code>xs:string?</code>.</aside>
859
      
860
      <p>Since a tuple is a map, fields can be accessed using the lookup syntax <code>$T?NNN</code> where <code>$T</code>
861
      is an expression that returns a tuple, and <code>NNN</code> is the name of the field. Saxon allows the field name
862
      to be written as a string in quotes if it is not an NCName, for example $T?"date of birth".</p>
863
      
864
    <p>Using tuples makes stronger type checking possible. With a general-purpose map, any atomic value can be
865
    supplied as a key, and the <code>map:get()</code> function (or a dynamic call on the map as a function) returns
866
    an empty sequence if the entry is not present. With tuples, however, supplying a key value that is not a string,
867
    or that is not one of the known field names, results in a static type error if it can be detected at compile time.
868
    Furthermore, if <code>$T</code> is known to be a tuple type, then the type of an 
869
      expression such as <code>$T?field</code>
870
    can be statically inferred, which again enables better error detection and better optimization.</p>
871
      
872
      <aside>Although <code>$T?N</code> results in a static type error if <code>T</code> is a non-extensible
873
      tuple type that doesn't define field <code>N</code>, a run-time reference <code>$T("N")</code> works
874
      the same way as any other dynamic map lookup, returning an empty sequence.</aside>
875
    
876
    <p>Tuple types are useful where maps are used to hold information with a regular structure;
877
    for example when a function accepts maps as input or returns maps as output. Declaring the argument
878
    or result type of a function as a tuple type often gives better information about the expected contents 
879
    than when it is declared as a map.</p>
880
      
881
      <p>Tuple types can be used as patterns, to match maps (regardless whether the value was originally
882
      declared as a tuple or not). This can be especially useful when processing JSON. For example, if
883
      a JSON document containing the object <code>{'long': 23.1234, 'lat':55.624}</code> is parsed using the
884
      <code>parse-json()</code> or <code>json-doc()</code> functions, then the resulting map can be processed
885
      using a template rule declared with <code>match="tuple(lat, long)"</code>.</p>
886
      
887
      <aside>There is an algorithm to define a default priority for tuple patterns, but it
888
        is provisional. At this release, you should not rely on the default priority of template rules
889
      whose match pattern is a tuple type. It is safest to allocate explicit priorities if there
890
      is any ambiguity. The rules for default priority are likely to be refined in later releases.</aside>
891
      
892
      <p>Tuple types fit into the type hierarchy as subtypes of maps. A tuple type T1 is a subtype of
893
      another tuple type T2 if every possible instance of T1 is a permitted instance of T2 (this takes into account
894
      whether either or both tuple types are extensible). Similarly, a tuple type T is a subtype of a map
895
      type M if every possible instance of T is a permitted instance of M. By extension, because maps are functions,
896
      tuples are also functions, and tuple types are thus subtypes of function types.</p>
897
      
898
      <p>In XSLT, as described below, it is possible to declare the type in both
899
      portable and Saxon-specific syntax, for example 
900
        <code>&lt;xsl:param name="location" as="map(xs:string, xs:double)" saxon:as="tuple(x as xs:double, y as xs:double)"/&gt;</code>.</p>
901
      
902
      <p>A map that contains additional entries beyond those defined in an extensible tuple type still conforms to the type (so if the expected
903
        type of a function argument is <code>tuple(a as xs:integer, b as xs:integer, *)</code>, then you can supply any
904
        map that contains these two fields, even if it also contains others). A consequence of making a tuple
905
        type extensible is that incorrect static references are less likely to result in a compile-time error.</p>
906
      
907

    
908
      <p>The following XSLT example shows a couple of functions from a library designed to perform
909
      complex number arithmetic, where a complex number is defined as the type <code>tuple(r as
910
        xs:double, i as xs:double)</code>:</p>
911
      
912
      <samp><![CDATA[<xsl:function name="cx:complex" as="tuple(r as xs:double, i as xs:double)">
913
  <xsl:param name="real" as="xs:double"/>
914
  <xsl:param name="imag" as="xs:double"/>
915
  <xsl:sequence select="map{'r':$real, 'i':$imag}"/>
916
</xsl:function>
917

    
918
<xsl:function name="cx:add" as="tuple(r as xs:double, i as xs:double)">
919
  <xsl:param name="x" as="tuple(r as xs:double, i as xs:double)"/>
920
  <xsl:param name="y" as="tuple(r as xs:double, i as xs:double)"/>
921
  <xsl:sequence select="cx:complex($x?r + $y?r, $x?i + $y?i)"/>
922
</xsl:function>]]></samp>
923
      
924
      <p>The same functions could be written in XQuery:</p>
925
      
926
      <samp><![CDATA[declare function cx:complex ($real as xs:double, $imag as xs:double)
927
                 as tuple(r as xs:double, i as xs:double) {
928
  map{'r':$real, 'i':$imag}
929
};
930

    
931
declare function cx:add ($x as tuple(r as xs:double, i as xs:double),
932
                         $y as tuple(r as xs:double, i as xs:double))
933
                 as tuple(r as xs:double, i as xs:double) {
934
  cx:number($x?r + $y?r, $x?i + $y?i)
935
};]]></samp>
936
      
937
     <p>Two additional Saxon extensions help to improve the usability of tuple types:</p>
938
      
939
      <ul>
940
        <li>A commonly used type can be referenced using a <b>type alias</b>, for example
941
        <code>as="type(cx:complex)"</code>. Type aliases are available in both XSLT and XQuery,
942
          and are described in <a class="bodylink"
943
            href="/extensions/syntax-extensions/type-aliases">Type Aliases</a>. Type aliases go some way towards
944
        hiding the implementation details of the type, and allowing the implementation to be changed
945
        without affecting users of the function library; in addition they simply make the code more
946
        readable.</li>
947
        <li>In XSLT only, elements that have an <code>as</code> attribute to define the type
948
        of a variable, function, or parameter, also have an optional <a class="bodylink code"
949
          href="/extensions/attributes/as">saxon:as</a> attribute
950
        which allows additional type information to be supplied using Saxon extension syntax.
951
        If both attributes are present, then the type specified in <code>saxon:as</code>
952
        must be a subtype of the type specified in the <code>as</code> attribute. Typical usage
953
        might be <code>&lt;xsl:param name="x" as="map(*)" saxon:as="tuple(r as xs:double, i as xs:double)"/></code>.
954
        This device allows tuple types to be used without compromising the portability of the stylesheet
955
        to an XSLT 3.0 processor that does not recognize Saxon's extension syntax (an XSLT 3.0
956
        processor that does not recognize the <code>saxon:as</code> attribute is required to ignore it).</li>
957
      </ul>
958
      
959
    </section>
960
    
961
    <section id="type-aliases" title="Type aliases">
962
      <h1>Type aliases</h1>
963
      
964
      <aside>Requires Saxon-PE or Saxon-EE, with syntax extensions enabled. Available since Saxon
965
        9.8; revised in 10.</aside>
966
      
967
      <p>Wherever an <code>ItemType</code> may appear (for example in a function signature or variable declaration, or
968
      in <code>instance of</code> or <code>cast as</code> expressions), the syntax <code
969
        class="bold">type(alias)</code> is permitted,
970
      where <code>alias</code> is a name for an item type declared elsewhere. Type aliases are QNames, and prefixes are
971
      resolved in the usual way (using the default namespace for elements and types).</p>
972
      
973
      <p>Type aliases are useful because they abstract away from the detail of how a type is
974
        implemented: for example <code>type(cx:complex)</code>
975
      is more meaningful than <code>tuple(r as xs:double, i as xs:double)</code>, and it creates more scope for changing the
976
      way types are represented as the software evolves. However, type aliases do not provide any real encapsulation or information
977
      hiding. Type aliases cannot be used within their own definition, and the definition of a type alias cannot be circular.</p>
978
      
979
      <p>The mapping of type aliases to item types is an extension to the static context of an expression.</p>
980
    
981
    <p>In XSLT, type aliases can be defined using the top-level declaration <a class="bodylink code"
982
      href="/extensions/instructions/item-type">saxon:item-type</a>:</p>
983
    
984
    <examples>
985
      <example>
986
        <samp><![CDATA[<saxon:item-type name="cx:complex" as="tuple(r as xs:double, i as xs:double)"/>
987

    
988
<xsl:function name="cx:complex" as="type(cx:complex)">
989
  <xsl:param name="r" as="xs:double"/>
990
  <xsl:param name="i" as="xs:double"/>
991
  <xsl:sequence select="map{'r':$r, 'i':$i}"/>
992
</xsl:function>
993

    
994
<xsl:function name="cx:add" as="type(cx:complex)">
995
  <xsl:param name="x" as="type(cx:complex)"/>
996
  <xsl:param name="y" as="type(cx:complex)"/>
997
  <xsl:sequence select="cx:complex($x?r + $y?r, $x?i + $y?i)"/>
998
</xsl:function>
999
]]></samp></example></examples>
1000
      
1001
      <p>XSLT-defined type aliases are scoped to a package. The usual rules for import precedence apply.</p>
1002
      
1003
      <p>Type aliases can be used in XSLT match patterns (see <a class="bodylink" href="/extensions/xslt-syntax-extensions">XSLT Syntax Extensions</a>). For example:</p>
1004
      
1005
      <example><samp>&lt;xsl:template match="type(cx:complex)[?i=0]">{?r}&lt;/xsl:template></samp></example>
1006
      
1007
      <example><samp>&lt;xsl:template match="type(cx:complex)">{?r}{if (?i ge 0) then '+' else ''}{?i}i&lt;/xsl:template></samp></example>
1008
      
1009
      <p>The construct <code>type(T)</code> at the start of a pattern can be regarded as an abbreviation for
1010
        <code>.[. instance of T]</code>. The experimental syntax <code>~T</code> used in earlier releases
1011
      has been dropped.</p>
1012
    
1013
      <p>In XQuery, type aliases can be declared in the query prolog using the syntax <code>declare type QName = ItemType;</code>, 
1014
        for example: <code>declare type cx:complex = tuple(r as xs:double, i as xs:double);</code>.</p>
1015
    </section>
1016
    
1017
    <section id="simple-inline-functions" title="Simple inline functions">
1018
      <h1>Simple inline functions</h1>
1019
      
1020
      <aside>Requires Saxon-PE or Saxon-EE, with syntax extensions enabled. Available since Saxon 9.8.</aside>
1021
      
1022
      <h2>Dot functions</h2>
1023
      <p>An abbreviated syntax ("dot functions") is available for defining simple inline functions. For example,
1024
        the expression <code>.{@code}</code> represents a function that takes a single argument (presumably an element node),
1025
        and returns a selected attribute of that node. A simple inline function takes a single argument with required type <code>item()</code>,
1026
        and returns any sequence (type <code>item()*</code>). The function body is evaluated with a singleton focus based
1027
        on the supplied argument value.</p>
1028
      
1029
      <p>Simple inline functions are particularly convenient when providing functions as arguments to higher-order functions,
1030
        many of which accept a single item as their one argument.
1031
        For example, to sort employees in order of salary, you can write:</p>
1032
      <samp>sort(//employee, .{@salary})</samp>
1033
      
1034
      <p>Simple inline functions can access externally-defined local variables in the usual way (that is, they have a closure).</p>
1035
      
1036
      <p>The expression <code class="bold">.{EXPR}</code> is a syntactic shorthand for:</p>
1037
      <samp>function($x as item()) as item()* {$x!(EXPR)}</samp>
1038
      
1039
      <p><i>The experimental syntax <code>fn{EXPR}</code> used in earlier releases has been dropped.</i></p>
1040
    
1041
    <h2>Underscore functions</h2>
1042
      
1043
      <p>For functions taking more than one argument, or an argument that is not confined to a single
1044
      item, a second abbreviated syntax ("underscore functions") is provided. For example,
1045
      the expression <code>_{$1 + $2}</code> is a function that takes two arguments and returns their sum.
1046
      It is equivalent to the expression:</p>
1047
      <samp>function($a1 as item()*, $a2 as item()*) as item()* {$a1 + $a2}</samp>
1048
      
1049
      <p>The arity of an underscore function is determined by the highest-numbered parameter reference
1050
      appearing within the function. For example, <code>_{$2}</code> is a function that takes two arguments
1051
      and returns the value of the second argument.</p>
1052
      
1053
      <p>This syntax can also be used to define a zero-arity function, 
1054
        for example the following is a function that returns tomorrow's date:</p>
1055
      <samp>_{current-date() + xs:dayTimeDuration('P1D')}</samp>
1056
      
1057
      
1058
    </section>
1059
    
1060
    <section id="short-circuit" title="Short-circuit boolean operators">
1061
      <h1>Short-circuit boolean operators</h1>
1062
      
1063
      <aside>Requires Saxon-PE or Saxon-EE, with syntax extensions enabled. Available since Saxon 9.9.</aside>
1064
      
1065
      <p>Saxon provides two additional boolean operators: <code class="bold">orElse</code> and
1066
        <code class="bold">andAlso</code>.
1067
      These have the same effect as <code>or</code> and <code>and</code>, except that there is a guarantee
1068
      that the second operand will not be evaluated unnecessarily. This makes it possible to ensure that
1069
      evaluating the second operand does not produce an error. For example, the expression:</p>
1070
      
1071
      <samp>//chapter[pages=0 orElse length div pages]</samp>
1072
      
1073
      <p>will never fail with a divide-by-zero error, because the division will never be executed if the
1074
      value of <code>pages</code> is zero.</p>
1075
      
1076
      <p>When the ordinary <code>or</code> and <code>and</code> operators are used, the W3C specification
1077
      gives XPath processors license to re-arrange the order of execution, and Saxon will occasionally do so.
1078
      Using these operators is therefore advised when the first condition is a guard to prevent the second condition
1079
      failing.</p>
1080
      
1081
      <p>The same effect can be achieved without relying on extensions, by writing
1082
      <code>A orElse B</code> as <code>if (A) then true() else boolean(B)</code>, and rewriting 
1083
        <code>X andAlso Y</code> as <code>if (X) then boolean(Y) else false()</code>.</p>
1084
    </section>
1085
    
1086
    <section id="otherwise" title="Otherwise operator">
1087
      <h1>Otherwise operator</h1>
1088
      
1089
      <aside>Requires Saxon-PE or Saxon-EE, with syntax extensions enabled. Available since Saxon 10.</aside>
1090
      
1091
      <p>Saxon provides an additional operator: <code class="bold">otherwise</code>. The expression <code>A otherwise B</code>
1092
        returns the value of <code>A</code> unless it is an empty sequence, in which case it returns the value of <code>B</code>.
1093
        For example, the expression:</p>
1094
      
1095
      <samp>chapter[title='Introduction'] otherwise chapter[1]</samp>
1096
      
1097
      <p>returns the chapter(s) entited "Introduction" if such a chapter exists; otherwise it returns the first chapter.</p>
1098
      
1099
      <p>The precedence of the operator is greater than arithmetic operators (so <code>$n div $m otherwise 1</code>
1100
        means <code>$n div ($m otherwise 1)</code>), but less than the "union" operator (so <code>a/b/c otherwise 0</code>
1101
        means <code>(a/b/c) otherwise 0</code>).</p>
1102
      
1103
      
1104
    </section>
1105
    
1106
    <section id="kindtests" title="KindTests">
1107
      <h1>KindTests</h1>
1108
      
1109
      <aside>Requires Saxon-PE or Saxon-EE, with syntax extensions enabled. Available since Saxon 10.</aside>
1110
      
1111
      <p>The syntax for the <code>element()</code> and <code>attribute()</code>
1112
        <code>KindTests</code> is extended to allow constructs of the form</p>
1113
      <samp>element(*:div)</samp> 
1114
      <p>or </p>
1115
      <samp>attribute(myns:*, myns:someType)</samp>
1116
        <p>More specifically, the grammar for <code>ElementNameOrWildCard</code>
1117
      changes from <code>ElementName | "*"</code> to simply <code>NameTest</code>; and similarly <code>AttribNameOrWildCard</code> also 
1118
        expands simply to <code>NameTest</code>. This change is made largely for orthogonality reasons (there is no reason to have 
1119
      different rules for the two constructs) and also because it provides some useful extra functionality: for example in XSLT it
1120
      is now possible to match all elements in a particular namespace having a particular type with a template rule that specifies
1121
      <code>match="element(my:*, my:type)"</code>.</p>
1122
      
1123
      <p>The default priority for an XSLT pattern in the form <code>element(X)</code> is always the same as the default priority for
1124
      <code>X</code>, so for example the default priority of <code>element(my:*)</code> is -0.25. If a type is present, then we
1125
      follow the principle that the default priority of <code>element(my:*, T)</code> is midway between the priorities of
1126
      <code>element(*, T)</code> and <code>element(E, T)</code>: that is, 0.125.</p>
1127
    </section>
1128
    
1129
    <section id="for-member-expression" title="For-Member Expressions">
1130
      <h1>For-Member expressions</h1>
1131
      
1132
      <aside>Requires Saxon-PE or Saxon-EE, with syntax extensions enabled. Available since Saxon 10.</aside>
1133
      
1134
      <p>The <code class="bold">for member</code> expression is a Saxon extension to XPath 3.1 syntax introduced in Saxon 10. It allows
1135
      convenient iterative processing of the members of an array.</p>
1136
      
1137
      <p>For example: </p>
1138
      <samp>for member $m in [(3,5,6), (8,12)] return sum($m)</samp> 
1139
      <p>returns the sequence <code>(14, 20)</code>.</p>
1140
      
1141
      <p>A <code>ForMemberExpr</code> is a new kind of <code>ExprSingle</code>; this means it can be used anywhere a <code>ForExpr</code>
1142
      or <code>LetExpr</code> is allowed. The syntax is:</p>
1143
      
1144
      <samp>ForMemberExpr ::= "for" "member" SimpleForBinding ("," SimpleForBinding)* "return" ExprSingle</samp>
1145
      
1146
      <p>Here <code>SimpleForBinding</code> takes the same form as in a <code>ForExpr</code>: </p>
1147
      <samp>"$" VarName "in" ExprSingle</samp>
1148
      
1149
      <p>The semantics are as follows:</p>
1150
      
1151
      <ul>
1152
        <li>Each expression in a <code>SimpleForBinding</code> must evaluate to a single array.</li>
1153
        <li>The expression <code>for member $x in X, $y in Y return R</code> is equivalent to 
1154
          <code>for member $x in X return for member $y in Y return R</code>.</li>
1155
        <li>The expression <code>for $x in X return R</code> binds the variable <code>$x</code> to each member of the
1156
        array <code>X</code> in turn, evaluates <code>R</code> with this variable binding in scope, and returns the
1157
        sequence-concatenation of all the evaluations of <code>R</code>, in order.</li>
1158
      </ul>
1159
      
1160
      <p>The <code>for member</code> expression is currently available only as a free-standing expression; it cannot be
1161
      used as a clause within an XQuery FLWOR expression.</p>
1162
      
1163
      <p>Some further examples:</p>
1164
      
1165
      <samp><![CDATA[let $json := '[{"x":1, "y":"one"}, {"x":2, "y":"two"}]'
1166
return for member $map in parse-json($json) return $map?y]]></samp>
1167
      
1168
      <p>returns <code>"one", "two"</code>.</p>
1169
      
1170
      <samp><![CDATA[let $json := '[[1,2,3], [4,5,6]]'
1171
return for member $A in parse-json($json), $a in $A return $a*2]]></samp>
1172
      
1173
      <p>returns <code>2, 4, 6, 8, 10, 12</code>.</p>
1174
      
1175
      <p>Note that the result of the expression is a sequence, not an array.</p>
1176
    </section>
1177
    
1178
  </section>
1179
  <section id="xslt-syntax-extensions" title="XSLT Syntax Extensions">
1180
    <h1>XSLT Syntax Extensions</h1>
1181
    
1182
    <aside>Requires Saxon-PE or Saxon-EE.</aside>
1183
    
1184
    <p>Most Saxon extensions to the XSLT 3.0 language have been implemented using the extensibility
1185
    mechanisms defined in the W3C XSLT 3.0 specification: they are typically implemented as extension
1186
    instructions, declarations, attributes, or functions in the Saxon namespace.</p>
1187
    
1188
    <p>A few experimental extensions have also been implemented by changing the native syntax. These
1189
    are intended for usability evaluation, with a view to inclusion in some future version of the XSLT
1190
    language. These extensions (described in this section) are available only if explicitly enabled.
1191
    This can be achieved using the configuration option
1192
      <a class="bodylink code"
1193
        href="/configuration/config-features">Feature.ALLOW_SYNTAX_EXTENSIONS</a> (use <code>--allowSyntaxExtensions:on</code> on the command line, 
1194
      or <code>global/@allowSyntaxExtensions="true"</code> in the configuration file).</p>
1195
    
1196
    <aside>Use of forwards compatibility mode (by specifying <code>version="4.0"</code>, say), does not
1197
      affect the way these extensions are handled: they are allowed if extensions are enabled, and disallowed
1198
      if extensions are disabled, regardless of the effective <code>version</code> in the stylesheet.
1199
    </aside>
1200
    
1201
    <p>Enabling syntax extensions not only allows the use of the XSLT extensions described in this section,
1202
    it also allows XPath extensions to be used in expressions and sequence types within the stylesheet, 
1203
    as described in <a class="bodylink" href="/extensions/syntax-extensions">XPath and XQuery Syntax Extensions</a>.</p>
1204
    
1205
    <h2>Match Patterns</h2>
1206
    
1207
    <p>The syntax of match patterns is extended to make it easier to match maps and
1208
      arrays. As for the XPath syntax extensions, these extensions are available only if explicitly enabled. </p>
1209
    
1210
    <p>In particular the syntax <code>ma-type predicate*</code> is allowed in a pattern, where <code>ma-type</code>
1211
      is any of:</p>
1212
    
1213
    <ol>
1214
      <li><code>type(...)</code></li>
1215
      <li><code>atomic(...)</code></li>
1216
      <li><code>union(...)</code></li>
1217
      <li><code>tuple(...)</code></li>
1218
      <li><code>map(...)</code></li>
1219
      <li><code>array(...)</code></li>
1220
    </ol>
1221
    
1222
    <p>For example if a <a class="bodylink" href="/extensions/syntax-extensions/type-aliases">type alias</a> has been declared:</p>
1223
    
1224
    <samp>&lt;saxon:item-type name="cx:complex" type="tuple(r as xs:double, i as xs:double)"/></samp>
1225
    
1226
    <p>Then it can be used in a match pattern to match instances of the type, with or without predicates:</p>
1227
    
1228
    <samp>&lt;xsl:template match="type(cx:complex)[?i=0]">{?r}&lt;/xsl:template></samp>
1229
    
1230
    <samp>&lt;xsl:template match="type(cx:complex)">{?r}{if (?i ge 0) then '+' else ''}{?i}i&lt;/xsl:template></samp>
1231
    
1232
    <p>The construct <code>type(T)</code> at the start of a pattern can be regarded as an abbreviation for
1233
      <code>.[. instance of type(T)]</code>.</p>
1234
    
1235
    <h2>Conditional Instructions</h2>
1236
    
1237
    <p>If syntax extensions are enabled, then the <a class="bodylink code"
1238
      href="/xsl-elements/choose">xsl:choose</a> and <a class="bodylink code" href="/xsl-elements/if">xsl:if</a>
1239
    instructions are enhanced as follows:</p>
1240
    
1241
    <ul>
1242
      <li><p>Within <code>xsl:choose</code>, the <code>xsl:when</code> and <code>xsl:otherwise</code>
1243
        instructions can define the returned value using a <code class="bold">select</code> attribute in place
1244
      of a sequence constructor. For example:</p>
1245
      <samp><![CDATA[<xsl:choose>
1246
  <xsl:when test="$day = 'Monday'" select="1"/>
1247
  <xsl:when test="$day = 'Tuesday'" select="2"/>
1248
  <xsl:when test="$day = 'Wednesday'" select="3"/>
1249
  <xsl:when test="$day = 'Thursday'" select="4"/>
1250
  <xsl:when test="$day = 'Friday'" select="5"/>
1251
  <xsl:otherwise select="-1"/>
1252
</xsl:choose>]]></samp>
1253
      </li>
1254
      <li><p>The <code>xsl:if</code> instruction can deliver its results using <code class="bold">then</code>
1255
        and <code class="bold">else</code> attributes in place of a contained sequence constructor. For example:</p>
1256
        <samp><![CDATA[<xsl:if test="$day = 'Monday'" then="1" else="0"/>]]></samp>
1257
        <p>If the <code>then</code> attribute is present, the <code>xsl:if</code> instruction must
1258
          be empty (have no children). Either attribute can be used independently; there is no
1259
        requirement for both to be present.</p>
1260
      </li>
1261
    </ul>
1262
    
1263
    <p>These new forms of <code>xsl:choose</code> and <code>xsl:if</code> are particularly useful
1264
    to compute the return value of a function, replacing <code>xsl:sequence</code>.</p>
1265
    
1266
  </section>
1267
  <section id="output-extras" title="Additional serialization parameters">
1268
    <h1>Additional serialization parameters</h1>
1269

    
1270
    <aside> Requires Saxon-PE or Saxon-EE. These extensions are not recognized in Saxon-HE. </aside>
1271

    
1272
    <p>Saxon provides a number of additional serialization parameters, and several additional
1273
      serialization methods: these have names in the Saxon namespace. These can be specified as
1274
      attributes on the <a class="bodylink code" href="/xsl-elements/output">xsl:output</a> and <a
1275
        class="bodylink code" href="/xsl-elements/result-document">xsl:result-document</a> elements
1276
      (XSLT-only), in the Query prolog (XQuery only), as parameters in the <a class="bodylink code"
1277
        href="/functions/fn/serialize">fn:serialize()</a> function, or as extra parameters on the
1278
      Query or Transform command line. They can also be specified in the query or transformation
1279
      API.</p>
1280

    
1281
    <p>The Saxon-supplied serialization parameters and methods are described on the following
1282
      pages:</p>
1283
    <nav>
1284
      <ul/>
1285
    </nav>
1286

    
1287
    <p>For example, to request an <dfn>indentation</dfn> depth of one column, specify
1288
        <code>!{http://saxon.sf.net/}indent-spaces=1</code> on the command line.</p>
1289

    
1290
    <p>In XQuery, Saxon allows both standard serialization options and Saxon-specific serialization
1291
      parameters to be specified by means of a <code>saxon:output</code> option declaration in the
1292
      query prolog. For example:</p>
1293
    <samp><![CDATA[declare namespace saxon="http://saxon.sf.net/";
1294
declare option saxon:output "indent=yes";
1295
declare option saxon:output "saxon:indent-spaces=3";
1296
]]></samp>
1297

    
1298
    <h3 class="subtitle">Standard serialization parameters</h3>
1299

    
1300
    <p>The standard serialization parameters described in the <a
1301
        href="http://www.w3.org/TR/xslt-xquery-serialization-30/" class="bodylink">W3C Serialization
1302
        specification</a> are all available, namely:</p>
1303
    <ul>
1304
      <li>
1305
        <p>allow-duplicate-names (requires XSLT 3.0/XQuery 3.1)</p>
1306
      </li>
1307
      <li>
1308
        <p>build-tree (requires XSLT 3.0/XQuery 3.0)</p>
1309
      </li>
1310
      <li>
1311
        <p>byte-order-mark</p>
1312
      </li>
1313
      <li>
1314
        <p>cdata-section-elements</p>
1315
      </li>
1316
      <li>
1317
        <p>doctype-public</p>
1318
      </li>
1319
      <li>
1320
        <p>doctype-system</p>
1321
      </li>
1322
      <li>
1323
        <p>encoding</p>
1324
      </li>
1325
      <li>
1326
        <p>escape-uri-attributes</p>
1327
      </li>
1328
      <li>
1329
        <p>html-version (requires XSLT 3.0/XQuery 3.0)</p>
1330
      </li>
1331
      <li>
1332
        <p>include-content-type</p>
1333
      </li>
1334
      <li>
1335
        <p>indent</p>
1336
      </li>
1337
      <li>
1338
        <p>item-separator (requires XQuery 3.0)</p>
1339
      </li>
1340
      <li>
1341
        <p>json-node-output-method (requires XSLT 3.0/XQuery 3.1)</p>
1342
      </li>
1343
      <li>
1344
        <p>media-type</p>
1345
      </li>
1346
      <li>
1347
        <p>method</p>
1348
      </li>
1349
      <li>
1350
        <p>normalization-form</p>
1351
      </li>
1352
      <li>
1353
        <p>omit-xml-declaration</p>
1354
      </li>
1355
      <li>
1356
        <p>standalone</p>
1357
      </li>
1358
      <li>
1359
        <p>suppress-indentation (requires XSLT 3.0/XQuery 3.0)</p>
1360
      </li>
1361
      <li>
1362
        <p>undeclare-prefixes</p>
1363
      </li>
1364
      <li>
1365
        <p>use-character-maps (only useful in XSLT)</p>
1366
      </li>
1367
      <li>
1368
        <p>version</p>
1369
      </li>
1370
    </ul>
1371

    
1372
    <p>
1373
      <i>Saxon interprets a zero-length value for <dfn><code>doctype-system</code></dfn> or
1374
            <dfn><code>doctype-public</code></dfn> as meaning "absent". This is equivalent to
1375
        omitting the value, except that in some interfaces it will override a value previously set
1376
        within the query or stylesheet.</i>
1377
    </p>
1378

    
1379

    
1380
    <h3 class="subtitle">User-defined serialization attributes</h3>
1381

    
1382
    <p>Any number of user-defined attributes may be defined on <code>xsl:output</code>. These
1383
      attributes must have names in a non-null namespace, which must not be either the XSLT or the
1384
      Saxon namespace. The value of the attribute is inserted into the <code>Properties</code>
1385
      object made available to the <a class="javalink" href="net.sf.saxon.event.Receiver"
1386
        >Receiver</a> handling the output; they will be ignored by the standard output methods, but
1387
      can supply arbitrary information to a user-defined output method. The name of the property
1388
      will be the expanded name of the attribute in JAXP format, for example
1389
        <code>{http://my-namespace/uri}local-name</code>, and the value will be the value as given
1390
      in the stylesheet. </p>
1391

    
1392

    
1393
    <xi:include href="extensions/serialization-params.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
1394

    
1395
    <section id="method" title="Serialization methods">
1396
      <h1>Serialization methods</h1>
1397

    
1398
      <p>The <code>method</code> attribute of <a class="bodylink code" href="/xsl-elements/output"
1399
          >xsl:output</a> can take the standard values <code>xml</code>, <code>html</code>,
1400
          <code>xhtml</code>, or <code>text</code>, or a QName.</p>
1401

    
1402
      <p>If a QName in the Saxon namespace is specified, the name must be one of the Saxon
1403
        serialization methods supported in Saxon-PE and Saxon-EE. These are:</p>
1404
      <nav>
1405
        <ul/>
1406
      </nav>
1407

    
1408
      <p>If a QName is specified, the local name must be the fully-qualified class name of a class
1409
        that implements either the SAX2 <code>org.xml.sax.ContentHandler</code> interface, or the <a
1410
          class="javalink" href="net.sf.saxon.event.Receiver">net.sf.saxon.event.Receiver</a>
1411
        interface. If such a value is specified, output is directed to a newly-created instance of
1412
        the user-supplied class. You can pass additional information to this class by means of extra
1413
        user-defined attributes on the <code>xsl:output</code> element.</p>
1414

    
1415
      <p> The prefix of the QName must correspond to a valid namespace URI. It is recommended to use
1416
        the Saxon URI "http://saxon.sf.net/", but this is not enforced.</p>
1417

    
1418
      <p>When output is sent to a user-specified <code>ContentHandler</code> or
1419
          <code>Receiver</code>, other serialization options (for example indentation, addition of
1420
        meta elements in HTML, and generation of a DOCTYPE declaration) have no effect.</p>
1421

    
1422
      <aside>As an alternative to specifying your own output method, you can customize Saxon's
1423
        serialization pipeline. There is a Saxon class <a class="javalink"
1424
          href="net.sf.saxon.lib.SerializerFactory">net.sf.saxon.lib.SerializerFactory</a> that
1425
        constructs the pipeline, from individual components that perform the various stages of
1426
        serialization. You can define your own subclass of <code>SerializerFactory</code>, and
1427
        register this using the method <code>setSerializerFactory()</code> on the <a
1428
          class="javalink" href="net.sf.saxon.Configuration">Configuration</a> object. This allows
1429
        you to insert your own steps into the pipeline, or to override any of the standard pipeline
1430
        components with classes of your own.</aside>
1431

    
1432

    
1433
      <section id="base64Binary-method" title="saxon:base64Binary serialization method">
1434
        <h1>saxon:base64Binary serialization method</h1>
1435

    
1436
        <aside> Requires Saxon-PE or Saxon-EE. </aside>
1437

    
1438
        <p>The serialization method <code>saxon:base64Binary</code> is intended to be useful when
1439
          creating <dfn>binary output files</dfn>, for example images. All serialization properties
1440
          other than <code>method</code> are ignored.</p>
1441

    
1442
        <p>As with the <code>text</code> output method, all nodes in the result tree other than text
1443
          nodes are ignored. Each text node must hold a string that is in the lexical space of the
1444
            <code>xs:base64Binary</code> data type. The sequence of octets corresponding to this
1445
          base64 value is written to the binary output file.</p>
1446

    
1447
        <p>When invoking this method via an API, use the property value
1448
            <code>{http://saxon.sf.net/}base64Binary</code>.</p>
1449

    
1450
        <p>When using this serialization method, the <code>omit-xml-declaration</code> parameter is
1451
          automatically set to <code>yes</code>.</p>
1452

    
1453
        <p> In the following example, the image displays as a small red dot. Note that whitespace
1454
          can be freely inserted into the base64Binary string. </p>
1455
        <samp><![CDATA[<xsl:template name="main">
1456
  <html>
1457
    <head>
1458
      <title>An image</title>
1459
    </head>
1460
    <body>
1461
      <h1>An image</h1>
1462
      <p><img src="image.gif"/></p>
1463
    </body>
1464
  </html>
1465
  <xsl:result-document method="saxon:base64Binary" href="image.gif" media-type="image/gif">
1466
    <xsl:text>iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAABGdBTUEAALGPC/xhBQAAAAlwSFlzAAA
1467
        LEwAACxMBAJqcGAAAAAd0SU1FB9YGARc5KB0XV+IAAAAddEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIFRoZSBH
1468
        SU1Q72QlbgAAAF1JREFUGNO9zL0NglAAxPEfdLTs4BZM4DIO4C7OwQg2JoQ9LE1exdlYvBBeZ7jqch9//q1uH
1469
        4TLzw4d6+ErXMMcXuHWxId3KOETnnXXV6MJpcq2MLaI97CER3N0vr4MkhoXe0rZigAAAABJRU5ErkJggg==
1470
    </xsl:text>
1471
  </xsl:result-document>
1472
</xsl:template>
1473
]]></samp>
1474

    
1475
        <p>It is of course possible to construct the base64Binary value programmatically. 
1476
          The functions in the EXPath binary module are useful for this purpose: see the 
1477
          <a class="bodylink" href="/functions/expath-binary">EXPath binary function library</a>.
1478
          See also the Saxon extension function <a class="bodylink code" href="/functions/saxon/octets-to-base64Binary"
1479
            >saxon:octets-to-base64Binary()</a>.</p>
1480

    
1481
        <p>When writing output that is not entirely binary, but contains mixed binary and text, it
1482
          may be more convenient to use the text output method with the
1483
            <code>saxon:recognize-binary</code>
1484
          <a class="bodylink" href="/extensions/output-extras/serialization-parameters"
1485
            >serialization parameter</a>.</p>
1486

    
1487
        <p>See also the <a class="bodylink code" href="../hexBinary-method">saxon:hexBinary</a>
1488
          serialization method.</p>
1489
      </section>
1490

    
1491
      <section id="hexBinary-method" title="saxon:hexBinary serialization method">
1492
        <h1>saxon:hexBinary serialization method</h1>
1493

    
1494
        <aside> Requires Saxon-PE or Saxon-EE. </aside>
1495

    
1496
        <p>The serialization method <code>saxon:hexBinary</code> is intended to be useful when
1497
          creating <dfn>binary output files</dfn>, for example images. All serialization properties
1498
          other than <code>method</code> are ignored.</p>
1499

    
1500
        <p>As with the <code>text</code> output method, all nodes in the result tree other than text
1501
          nodes are ignored. Each text node must hold a string that is in the lexical space of the
1502
            <code>xs:hexBinary</code> data type. The sequence of octets corresponding to this
1503
          hexBinary value is written to the binary output file.</p>
1504

    
1505
        <p>When invoking this method via an API, use the property value
1506
            <code>{http://saxon.sf.net/}hexBinary</code>.</p>
1507

    
1508
        <p>When using this serialization method, the <code>omit-xml-declaration</code> parameter is
1509
          automatically set to <code>yes</code>.</p>
1510

    
1511
        <p> In the following example, the image displays as a small red dot. Note that whitespace
1512
          cannot appear in the middle of an <code>xs:hexBinary</code> value, but the string can be
1513
          split into multiple text nodes so long as each contains an even number of characters. </p>
1514

    
1515
        <samp><![CDATA[<xsl:template name="main">
1516
  <html>
1517
    <head>
1518
      <title>An image</title>
1519
    </head>
1520
    <body>
1521
      <h1>An image</h1>
1522
      <p><img src="image004.gif"/></p>
1523
    </body>
1524
  </html>
1525
  <xsl:result-document method="saxon:hexBinary" href="image004.gif" media-type="image/gif">
1526
    <xsl:text>89504E470D0A1A0A0000000D49484452</xsl:text>
1527
    <xsl:text>0000000A0000000A08060000008D32CF</xsl:text>
1528
    <xsl:text>BD0000000467414D410000B18F0BFC61</xsl:text>
1529
    <xsl:text>05000000097048597300000B1300000B</xsl:text>
1530
    <xsl:text>1301009A9C180000000774494D4507D6</xsl:text>
1531
    <xsl:text>06011739281D1757E20000001D744558</xsl:text>
1532
    <xsl:text>74436F6D6D656E740043726561746564</xsl:text>
1533
    <xsl:text>2077697468205468652047494D50EF64</xsl:text>
1534
    <xsl:text>256E0000005D4944415418D3BDCCBD0D</xsl:text>
1535
    <xsl:text>825000C4F11F74B4ECE0164CE0320EE0</xsl:text>
1536
    <xsl:text>2ECEC1083626843D2C4D5EC5D958BC10</xsl:text>
1537
    <xsl:text>5E67B8EA721F7FFEAD6E1F84CBCF0E1D</xsl:text>
1538
    <xsl:text>EBE12B5CC31C5EE1D6C4877728E1139E</xsl:text>
1539
    <xsl:text>75D757A309A5CAB630B688F7B0844773</xsl:text>
1540
    <xsl:text>74BEBE0C921A177B4AD98A0000000049</xsl:text>
1541
    <xsl:text>454E44AE426082</xsl:text>
1542
  </xsl:result-document>
1543
</xsl:template>
1544
]]></samp>
1545

    
1546
        <p>It is of course possible to construct the hexBinary value programmatically. The EXPath binary
1547
          library is however geared towards creating base64Binary values, so that will usually be a better option.</p>
1548

    
1549
        <p>When writing output that is not entirely binary, but contains mixed binary and text, it
1550
          may be more convenient to use the text output method with the
1551
            <code>saxon:recognize-binary</code>
1552
          <a class="bodylink" href="/extensions/output-extras/serialization-parameters"
1553
            >serialization parameter</a>.</p>
1554

    
1555
        <p>See also the <a class="bodylink code" href="../base64Binary-method"
1556
            >saxon:base64Binary</a> serialization method.</p>
1557
      </section>
1558

    
1559
      
1560

    
1561
      <section id="xquery-method" title="saxon:xquery serialization method">
1562
        <h1>saxon:xquery serialization method</h1>
1563

    
1564
        <aside> Requires Saxon-PE or Saxon-EE. </aside>
1565

    
1566
        <p>The serialization method <code>saxon:xquery</code> is intended to be useful when
1567
          generating an XQuery query as the output of a query or stylesheet. This method differs
1568
          from the XML serialization method in that "&lt;" and "&gt;" characters appearing between
1569
          curly braces (but not between quotes) in text nodes and attribute nodes are not escaped.
1570
          The idea is to allow queries to be generated, or to be written within an XML document, and
1571
          processed by first serializing them with this output method, then parsing the result with
1572
          the XQuery parser. For example, the document <code>&lt;a&gt;{$a &amp;lt;
1573
            '&amp;lt;'}&lt;/a&gt;</code> will serialize as <code>&lt;a&gt;{$a &lt;
1574
            '&amp;lt;'}&lt;/a&gt;</code>. </p>
1575

    
1576
        <p>When invoking this method via an API, use the property value
1577
            <code>{http://saxon.sf.net/}xquery</code>.</p>
1578

    
1579
        <p>When using this serialization method, the <code>omit-xml-declaration</code> parameter is
1580
          automatically set to <code>yes</code>.</p>
1581
      </section>
1582
    </section>
1583
  </section>
1584

    
1585
  <xi:include href="extensions/instructions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
1586

    
1587
</article>
(12-12/21)