Extensions
The full library of Saxon, EXSLT and EXPath functions described in Extensions is available, except for those (for example, some
forms of saxon:serialize
) that have an intrinsic dependency on an XSLT
stylesheet.
declare option saxon:default
An XQuery option declaration is defined allowing a default value to be specified for a query parameter (external variable). The syntax is illustrated below:
declare namespace saxon="http://saxon.sf.net/"; declare option saxon:default "20"; declare variable $x external;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 XQuery 3.0, the above syntax can be replaced by:
declare variable $x external := 20;declare option saxon:output
Saxon provides an option declaration to set serialization parameters. This takes the form shown in the following example:
declare namespace saxon="http://saxon.sf.net/"; declare option saxon:output "method=html"; declare option saxon:output "saxon:indent-spaces=1";All the standard serialization parameters described in the W3C Serialization specification are available
-
allow-duplicate-names (requires XSLT 3.0/XQuery 3.1)
-
build-tree (requires XSLT 3.0/XQuery 3.0)
-
byte-order-mark
-
cdata-section-elements
-
doctype-public
-
doctype-system
-
encoding
-
escape-uri-attributes
-
html-version (requires XSLT 3.0/XQuery 3.0)
-
include-content-type
-
indent
-
item-separator (requires XQuery 3.0)
-
json-node-output-method (requires XSLT 3.0/XQuery 3.1)
-
media-type
-
method
-
normalization-form
-
omit-xml-declaration
-
standalone
-
suppress-indentation (requires XSLT 3.0/XQuery 3.0)
-
undeclare-prefixes
-
use-character-maps (only useful in XSLT)
-
version
In addition some Saxon-specific serialization parameters are available: see Additional serialization parameters.
declare option saxon:memo-function
Saxon provides an option declaration to treat the immediately following function as a memo-function. This takes the form shown in the following example:
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 };Alternatively:
declare namespace saxon="http://saxon.sf.net/"; declare %saxon:memo-function function local:factorial($n as xs:integer) as xs:integer { local:factorial($n - 1) * n };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.
The allowed values of the option are "true" and "false" (the default is false), and any other value is ignored with a warning.
declare option saxon:allow-cycles
In XQuery 1.0, it was an error XQST0093 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. This restriction was dropped in XQuery 3.0. Saxon introduced the option declare option saxon:allow-cycles
"true"
to disable the check in XQuery 1.0. The option also disables error XQST0073, which
otherwise occurs when two modules in different namespaces import each other.
The allowed values of the option are "true" and "false" (the default is false), and any other value is ignored with a warning.
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
.
Note that this option declaration must be written after the module imports, but before any variable or function declarations.
The saxon:validate-type pragma
This extension is largely obsolescent: since version 9.3, Saxon 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.)
Saxon-EE provides a pragma (a language extension) to allow constructed elements to be
validated against a schema-defined global type definition. The standard
validate
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.
The extension takes the form:
(# saxon:validate-type my:personType #) { expr }Conceptually, it makes a copy of the result of evaluating expr
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 type
attribute in XSLT instructions such as xsl:element
and
xsl:copy-of
. The schema type (shown in the above example as
myPersonType
) 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.
Note that XQuery processors other than Saxon will typically ignore this pragma, and return
the value of expr
unchanged. Such processors will report type-checking
failures if the value is used in a context where the required type is element(*,
type-name)
.
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/"
.
Here is a complete example:
module namespace time="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> } };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.
The construct also allows validation of attributes against a simple type definition, for example:
module namespace time="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')} } };