<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="using-xquery" page="extensions" subpage=""/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Extensions</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title" content="Saxonica: XSLT and XQuery Processing: Extensions"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Extensions</h1>
<p>The full library of Saxon and EXSLT functions described in <a class="bodylink" href="../extensions/intro.xml">Extensions</a>
is available, except for those (for example, some forms of <code>saxon:serialize</code>)
that have an intrinsic dependency on an XSLT stylesheet.</p>
<p class="subhead">declare option saxon:default</p>
<p><i>This extension is obsolescent, as the functionality is available from Saxon 9.2 onwards using the syntax
appearing in the draft XQuery 3.0 specification.</i></p>
<p>An XQuery option declaration is defined allowing a default value to be specified for a query parameter (external variable).
The syntax is illustrated below:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>
declare namespace saxon="http://saxon.sf.net/";
declare option saxon:default "20";
declare variable $x external;
</code>
</pre>
</div>
<p>The default value is written as an XPath expression. The surrounding quotes are part of the "declare option"
syntax, not part of the expression: therefore, if the default value is to be supplied as a string literal, two
sets of quotes are needed. In the above example, the default value is the integer 20, not a string.
Perhaps it would be clearer to show this by writing <code>saxon:default "(+20)"</code></p>
<p class="subhead">declare option saxon:output</p>
<p>Saxon provides an option declaration to set serialization parameters. This takes the form
shown in the following example:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>
declare namespace saxon="http://saxon.sf.net/";
declare option saxon:output "method=html";
declare option saxon:output "saxon:indent-spaces=1";
</code>
</pre>
</div>
<p>The standard serialization parameters described in
<a href="http://www.w3.org/TR/xslt-xquery-serialization/" class="bodylink">The W3C Serialization specification</a>
are all available, namely:</p>
<ul>
<li content="para">
<p>byte-order-mark</p>
</li>
<li content="para">
<p>cdata-section-elements</p>
</li>
<li content="para">
<p>doctype-public</p>
</li>
<li content="para">
<p>doctype-system</p>
</li>
<li content="para">
<p>encoding</p>
</li>
<li content="para">
<p>escape-uri-attributes</p>
</li>
<li content="para">
<p>include-content-type</p>
</li>
<li content="para">
<p>indent</p>
</li>
<li content="para">
<p>media-type</p>
</li>
<li content="para">
<p>method</p>
</li>
<li content="para">
<p>normalization-form</p>
</li>
<li content="para">
<p>omit-xml-declaration</p>
</li>
<li content="para">
<p>standalone</p>
</li>
<li content="para">
<p>undeclare-prefixes</p>
</li>
<li content="para">
<p>use-character-maps (only useful in XSLT)</p>
</li>
<li content="para">
<p>version</p>
</li>
</ul>
<p>In addition some Saxon-specific serialization parameters are available:
see <a class="bodylink" href="../extensions/output-extras.xml">Additional serialization parameters</a>.</p>
<p class="subhead">declare option saxon:memo-function</p>
<p>Saxon provides an option declaration to treat the immediately following function as a memo-function.
This takes the form shown in the following example:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>
declare namespace saxon="http://saxon.sf.net/";
declare option saxon:memo-function "true";
declare function local:factorial($n as xs:integer) as xs:integer {
local:factorial($n - 1) * n
};
</code>
</pre>
</div>
<p>A memo function remembers the results of previous calls, so if it is called twice with the same
arguments, it will not repeat the computation, but return the previous result.</p>
<p>The allowed values of the option are "true" and "false" (the default is false), and any other value
is ignored with a warning.</p>
<p class="subhead">declare option saxon:allow-cycles</p>
<p>Saxon checks for the error XQST0093 which was introduced in the Proposed Recommendation. This error
makes it illegal for a function or variable in module A to reference a function or variable in module B if there
is a function or variable in module B that references one in A. Because this restriction is quite unnecessary
and makes it very difficult to write modular applications, Saxon provides an option
<code>declare option saxon:allow-cycles "true"</code> to disable this check. This option also disables
error XQST0073, which otherwise occurs when two modules in different namespaces import each other</p>
<p>The allowed values of the option are "true" and "false" (the default is false), and any other value
is ignored with a warning.</p>
<p>This option does not disable the check for cycles that would actually cause execution to fail, for
example a global variable $V1 whose initializer uses $V2, when $V2 similarly depends on $V1.</p>
<p>Note that this option declaration must be written <i>after</i> the module imports, but before any
variable or function declarations.</p>
<p class="subhead">The saxon:validate-type pragma</p>
<p><i>This extension is largely obsolescent: Saxon 9.3 implements the XQuery 3.0 syntax for validation
by type. The extension does serve one remaining purpose, which is to allow attributes to be validated.
(The standard syntax requires an element or document node.).</i></p>
<p>Saxon-EE provides a pragma (a language extension) to allow constructed elements to be validated
against a schema-defined global type definition. The standard <code>validate</code> expression allows validation
only against a global element declaration, but some schemas (an example is FpML) provide very few global elements,
and instead rely heavily on locally-declared elements having a global type. This makes it impossible to construct
fragments of an FpML document in a way that takes advantage of static and dynamic type checking.</p>
<p>The extension takes the form:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>
(# saxon:validate-type my:personType #) { expr }
</code>
</pre>
</div>
<p>Conceptually, it makes a copy of the result of evaluating <code>expr</code> and validates it against the named
schema type, causing the copied nodes to acquire type annotations based on the validation process. The effect is the
same as that of the <code>type</code> attribute in XSLT instructions such as <code>xsl:element</code> and
<code>xsl:copy-of</code>. The schema type (shown in the above example as <code>myPersonType</code>) may be a
simple type or a complex type defined in an imported schema, or a built-in type; it is written as a QName,
using the default namespace for elements and types if it is unprefixed.</p>
<p>Note that XQuery processors other than Saxon will typically ignore this pragma, and return the value of
<code>expr</code> unchanged. Such processors will report type-checking failures if the value is used in a
context where the required type is <code>element(*, type-name)</code>.</p>
<p>You can use a different namespace prefix in place of "saxon", but it must be bound using a
namespace declaration to the namespace "http://saxon.sf.net/".</p>
<p>Here is a complete example:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>
module namespace tim="http://www.example.com/module/hour-minute-time";
declare namespace saxon="http://saxon.sf.net/";
import schema namespace fpml = "http://www.fpml.org/2005/FpML-4-2" at "....";
declare function time:getCurrentHourMinuteTime() as element(*, fpml:HourMinuteTime) {
let $time = string(current-time())
return
(# saxon:validate-type fpml:HourMinuteTime #) {
<time>{substring($time, 1, 5)}:00</time>
}
};
</code>
</pre>
</div>
<p>Saxon ignores any pragmas in a namespace other than the Saxon namespace; it rejects any pragmas whose QName is
ill-formed, as well as pragmas in the Saxon namespace whose local name is not recognized.</p>
<p>The construct also allows validation of attributes against a simple type definition, for example:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>
module namespace tim="http://www.example.com/module/hour-minute-time";
declare namespace saxon="http://saxon.sf.net/";
import schema namespace fpml = "http://www.fpml.org/2005/FpML-4-2" at "....";
declare function time:getCurrentHourMinuteTime() as attribute(*, fpml:HourMinuteTime) {
let $time = string(current-time())
return (# saxon:validate-type fpml:HourMinuteTime #) {
attribute time {concat(substring($time, 1, 5), ':00')}
}
};
</code>
</pre>
</div>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="usecases.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
