[1] | Module |
::= |
VersionDecl? (LibraryModule | MainModule) |
|
[3] | MainModule |
::= |
Prolog
QueryBody
|
|
[4] | LibraryModule |
::= |
ModuleDecl
Prolog
|
|
[6] | Prolog |
::= | ((DefaultNamespaceDecl | Setter | NamespaceDecl | Import) Separator)* ((ContextItemDecl | AnnotatedDecl | OptionDecl) Separator)* |
|
[8] | Setter |
::= |
BoundarySpaceDecl | DefaultCollationDecl | BaseURIDecl | ConstructionDecl | OrderingModeDecl | EmptyOrderDecl | CopyNamespacesDecl | DecimalFormatDecl
|
|
[20] | Import |
::= |
SchemaImport | ModuleImport
|
|
[7] | Separator |
::= | ";" |
|
[43] | QueryBody |
::= |
Expr
|
A query can be assembled from one or more fragments called modules. [Definition: A module is a fragment of XQuery code that conforms to the Module grammar and can independently undergo the static analysis phase described in 2.3.3 Expression Processing. Each module is either a main module or a library module.]
[Definition: A main module consists of a Prolog followed by a Query Body.] A query has exactly one main module. In a main module, the Query Body is evaluated with respect to the static and dynamic contexts of the main module in which it is found, and its value is the result of the query.
[Definition: A module that does not contain a Query Body is called a library module. A library module consists of a module declaration followed by a Prolog.] A library module cannot be evaluated directly; instead, it provides function and variable declarations that can be imported into other modules.
The XQuery syntax does not allow a module to contain both a module declaration and a Query Body.
[Definition: A Prolog is a series of declarations and imports that define the processing environment for the module that contains the Prolog.] Each declaration or import is followed by a semicolon. A Prolog is organized into two parts.
The first part of the Prolog consists of setters, imports, namespace declarations, and default namespace declarations. [Definition: Setters are declarations that set the value of some property that affects query processing, such as construction mode, ordering mode, or default collation.] Namespace declarations and default namespace declarations affect the interpretation of lexical QNames within the query. Imports are used to import definitions from schemas and modules. [Definition: The target namespace of a module is the namespace of the objects (such as elements or functions) that it defines. ]
The second part of the Prolog consists of declarations of variables, functions, and options. These declarations appear at the end of the Prolog because they may be affected by declarations and imports in the first part of the Prolog.
[Definition: The Query Body, if present, consists of an expression that defines the result of the query.] Evaluation of expressions is described in 4 Expressions. A module can be evaluated only if it has a Query Body.
[2] | VersionDecl |
::= | "xquery" (("encoding" StringLiteral) | ("version" StringLiteral ("encoding" StringLiteral)?)) Separator
|
[Definition: A version declaration can identify the applicable XQuery syntax and semantics for a module, as well as its encoding.] [Definition: An XQuery version number consists of two integers separated by a dot. The first integer is referred to as the major version number; the second as the minor version number.] Any XQuery processor that implements any version of XQuery with a given major number must accept any query with the same major version number. The processor may reject queries labeled with a different major version number. The processor may reject queries with the same major version number and a greater minor version number than the processor recognizes. If a query is rejected because of a version mismatch with the processor, a static error [err:XQST0031] must be raised.
Note:
The processor is allowed to provide an option to require that minor versions also match, or that the minor number of the version in the query is not larger than the largest minor version understood by the processor in this major release of XQuery, or to allow more permissive version matching, perhaps with warnings, but the behaviour is then outside the scope of this specification.
The version number "1.0" indicates the intent that the module be processed by an XQuery 1.0 processor, the version number "3.0" indicates the intent that the module be processed by an XQuery 3.0 processor, the version number "3.1" indicates the intent that the module be processed by an XQuery 3.1 processor. If the version declaration is not present or the version is not included in the declaration, an XQuery 3.1 processor assumes a version of "3.1".
[Definition: If present, a version
declaration may optionally include an encoding declaration. The value of the
string literal following the keyword encoding
is an encoding name, and must
conform to the definition of EncName
specified in [XML 1.0]
[err:XQST0087]. The purpose of an encoding declaration is to allow the writer of
a query to provide a string that indicates how the query is encoded, such as
"UTF-8
", "UTF-16
", or "US-ASCII
".] Since
the encoding of a query may change as the query moves from one environment to another, there
can be no guarantee that the encoding declaration is correct.
The handling of an encoding declaration is implementation-dependent. If an implementation has a priori knowledge of the encoding of a query, it may use this knowledge and disregard the encoding declaration. The semantics of a query are not affected by the presence or absence of an encoding declaration.
If a version declaration is present, no Comment may occur before the end of the version declaration. If such a Comment is present, the result is implementation-dependent; an implementation may raise an implementation-dependent static error, or ignore the comment.
Note:
The effect of a Comment before the end of a version declaration is implementation-dependent because it may suppress query processing by interfering with detection of the encoding declaration.
The following examples illustrate version declarations:
xquery version "1.0";
xquery version "3.0" encoding "utf-8";
[5] | ModuleDecl |
::= | "module" "namespace" NCName "=" URILiteral
Separator
|
[Definition: A module
declaration serves to identify a module as a
library module. A module declaration begins
with the keyword module
and contains a namespace prefix and a URILiteral.] The URILiteral must be of nonzero length
[err:XQST0088]. The URILiteral identifies the target namespace of the library module, which is the
namespace for all variables and functions exported by the library module. The name of every
variable and function declared in a library module must have a namespace URI that is the same
as the target namespace of the module; otherwise a static
error is raised [err:XQST0048]. The (prefix,URI) pair is added
to the set of statically known namespaces.
The namespace prefix specified in a module declaration must not be xml
or
xmlns
[err:XQST0070], and must not be the same as any namespace prefix bound in
the same module by a schema import, by a namespace declaration, or by a module import with a different target namespace [err:XQST0033].
Any module may import one or more library modules by means of a module import that specifies the target namespace of the library modules to be imported. When a module imports one or more library modules, the variables and functions declared in the imported modules are added to the static context and (where applicable) to the dynamic context of the importing module.
The following is an example of a module declaration:
module namespace gis = "http://example.org/gis-functions";
[9] | BoundarySpaceDecl |
::= | "declare" "boundary-space" ("preserve" | "strip") |
[Definition: A boundary-space
declaration sets the boundary-space
policy in the static context,
overriding any implementation-defined default. Boundary-space policy controls whether
boundary whitespace is preserved by
element constructors during processing of the query.] If boundary-space policy is
preserve
, boundary whitespace is preserved. If boundary-space policy is
strip
, boundary whitespace is stripped (deleted). A further discussion of
whitespace in constructed elements can be found in 4.12.1.4 Boundary Whitespace.
The following example illustrates a boundary-space declaration:
declare boundary-space preserve;
If a Prolog contains more than one boundary-space declaration, a static error is raised [err:XQST0068].
[10] | DefaultCollationDecl |
::= | "declare" "default" "collation" URILiteral
|
[Definition: A default
collation declaration sets the value of the default
collation in the static context,
overriding any implementation-defined default.] The default collation is the
collation that is used by functions and operators that require a collation if no other
collation is specified. For example, the gt
operator on strings is defined by a
call to the fn:compare
function, which takes an optional collation parameter.
Since the gt
operator does not specify a collation, the fn:compare
function implements gt
by using the default collation.
If neither the implementation nor the Prolog specifies a default collation, the Unicode
codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint
)
is used.
The following example illustrates a default collation declaration:
declare default collation "http://example.org/languages/Icelandic";
If a default collation declaration specifies a collation by a relative URI, that relative URI is resolved to an absolute URI using the Static Base URI. If a Prolog contains more than one default collation declaration, or the value specified by a default collation declaration (after resolution of a relative URI, if necessary) is not present in statically known collations, a static error is raised [err:XQST0038].
[11] | BaseURIDecl |
::= | "declare" "base-uri" URILiteral
|
[Definition: A base URI declaration
specifies the Static Base URI property. The
Static Base URI property is used when
resolving relative URI references.] For example, the Static Base URI property is used when resolving relative
references for module import and for the
fn:doc
function.
Note:
As discussed in the definition of Static Base URI, if there is no base URI declaration, or if the value of the declaration is a relative URI reference, then the value of the Static Base URI may depend on the location of the query, and it is permissible for this to vary between the static analysis phase and the dynamic evaluation phase.
The following is an example of a base URI declaration:
declare base-uri "http://example.org";
If a Prolog contains more than one base URI declaration, a static error is raised [err:XQST0032].
In the terminology of [RFC3986] Section 5.1, the URILiteral of the base URI
declaration is considered to be a "base URI embedded in content". If no base URI declaration
is present, Static Base URI property is
established according to the principles outlined in [RFC3986] Section
5.1—that is, it defaults first to the base URI of the encapsulating entity, then to the
URI used to retrieve the entity, and finally to an implementation-defined default. If the
URILiteral in the base URI declaration is a relative URI, then it is made absolute by
resolving it with respect to this same hierarchy. For example, if the URILiteral in the base
URI declaration is ../data/
, and the query is contained in a file whose URI is
file:///C:/temp/queries/query.xq
, then the Static Base URI property is file:///C:/temp/data/
.
It is not intrinsically an error if this process fails to establish an absolute base URI; however, the Static Base URI property is then absentDM31 [err:XPST0001]. When the Static Base URI property is absentDM31, any attempt to use its value to resolve a relative URI reference will result in an error [err:XPST0001].
[12] | ConstructionDecl |
::= | "declare" "construction" ("strip" | "preserve") |
[Definition: A construction
declaration sets the construction
mode in the static context,
overriding any implementation-defined default.] The construction mode governs the
behavior of element and document node constructors. If construction mode is
preserve
, the type of a constructed element node is xs:anyType
,
and all attribute and element nodes copied during node construction retain their original
types. If construction mode is strip
, the type of a constructed element node is
xs:untyped
; all element nodes copied during node construction receive the type
xs:untyped
, and all attribute nodes copied during node construction receive the
type xs:untypedAtomic
.
The following example illustrates a construction declaration:
declare construction strip;
If a Prolog specifies more than one construction declaration, a static error is raised [err:XQST0067].
[13] | OrderingModeDecl |
::= | "declare" "ordering" ("ordered" | "unordered") |
[Definition: An ordering mode
declaration sets the ordering mode in the
static context, overriding any
implementation-defined default.] This ordering mode applies to all expressions in a
module (including both the Prolog and the Query Body, if any), unless
overridden by an ordered
or unordered
expression.
The following example illustrates an ordering mode declaration:
declare ordering unordered;
If a Prolog contains more than one ordering mode declaration, a static error is raised [err:XQST0065].
[14] | EmptyOrderDecl |
::= | "declare" "default" "order" "empty" ("greatest" | "least") |
[Definition: An empty order
declaration sets the default order for empty
sequences in the static context,
overriding any implementation-defined default. This declaration controls the processing of
empty sequences and NaN
values as ordering keys in an order by
clause in a FLWOR expression.] An individual order by
clause may
override the default order for empty sequences by specifying empty greatest
or
empty least
.
The following example illustrates an empty order declaration:
declare default order empty least;
If a Prolog contains more than one empty order declaration, a static error is raised [err:XQST0069].
Note:
It is important to distinguish an empty order
declaration from an ordering mode
declaration. An empty order
declaration applies only when an order by
clause is present, and
specifies how empty sequences are treated by the order by
clause (unless
overridden). An ordering mode declaration, on
the other hand, applies only in the absence of an order by
clause.
[15] | CopyNamespacesDecl |
::= | "declare" "copy-namespaces" PreserveMode "," InheritMode
|
|
[16] | PreserveMode |
::= | "preserve" | "no-preserve" |
|
[17] | InheritMode |
::= | "inherit" | "no-inherit" |
[Definition: A copy-namespaces declaration sets the value of copy-namespaces mode in the static context, overriding any implementation-defined default. Copy-namespaces mode controls the namespace bindings that are assigned when an existing element node is copied by an element constructor or document constructor.] Handling of namespace bindings by element constructors is described in 4.12.1 Direct Element Constructors.
The following example illustrates a copy-namespaces declaration:
declare copy-namespaces preserve, no-inherit;
If a Prolog contains more than one copy-namespaces declaration, a static error is raised [err:XQST0055].
[18] | DecimalFormatDecl |
::= | "declare" (("decimal-format" EQName) | ("default" "decimal-format")) (DFPropertyName "=" StringLiteral)* |
|
[19] | DFPropertyName |
::= | "decimal-separator" | "grouping-separator" | "infinity" | "minus-sign" | "NaN"
| "percent" | "per-mille" | "zero-digit" | "digit" | "pattern-separator"
| "exponent-separator" |
[Definition: A decimal format
declaration adds a decimal format to the statically known decimal formats, which define the properties used to format
numbers using the fn:format-number()
function], as described in
[XQuery and XPath Functions and Operators 4.0].
If the form decimal-format EQName
is used, then the declaration
defines the properties of the decimal format whose name is EQName
, while the form default decimal-format
defines the properties of the unnamed decimal format. The declaration contains a set of
(DFPropertyName
, StringLiteral
) pairs, where the DFPropertyName
is the name
of the property and the StringLiteral
is its value. The valid values and default values for each
property are defined in statically known decimal formats.
If a format declares no properties, default values are used for all properties.
Error conditions are defined as follows:
It is a static error for a query prolog to contain two decimal format declarations with the same name, or to contain two default decimal format declarations [err:XQST0111].
It is a static error for a decimal format declaration to define the same property more than once [err:XQST0114].
It is a static error for a decimal format declaration to specify a value that is not valid for a given property, as described in statically known decimal formats [err:XQST0097].
It is a static error if, for any named or unnamed decimal format, the properties representing characters used in a picture string do not have distinct values [err:XQST0098].
The following properties represent characters used in a picture string: decimal-separator, exponent-separator, grouping-separator, percent, per-mille, the family of ten decimal digits starting with zero-digit, digit, and pattern-separator.
The following query formats numbers using two different decimal format declarations:
declare decimal-format local:de decimal-separator = "," grouping-separator = "."; declare decimal-format local:en decimal-separator = "." grouping-separator = ","; let $numbers := (1234.567, 789, 1234567.765) for $i in $numbers return ( format-number($i, "#.###,##", "local:de"), format-number($i, "#,###.##", "local:en") )
The output of this query is:
1.234,57 1,234.57 789 789 1.234.567,76 1,234,567.76
[21] | SchemaImport |
::= | "import" "schema" SchemaPrefix? URILiteral ("at" URILiteral ("," URILiteral)*)? |
|
[22] | SchemaPrefix |
::= | ("namespace" NCName "=") | ("default" "element" "namespace") |
[Definition: A schema import imports the element declarations, attribute declarations, and type definitions from a schema into the in-scope schema definitions. For each named user-defined simple type in the schema, schema import also adds a corresponding constructor function. ] The schema to be imported is identified by its target namespace. The schema import may bind a namespace prefix to the target namespace of the imported schema, adding the (prefix, URI) pair to the statically known namespaces, or it may declare that target namespace to be the default element namespace and the default type namespace . The schema import may also provide optional hints for locating the schema.
The namespace prefix specified in a schema import must not be xml
or
xmlns
[err:XQST0070], and must not be the same as any namespace prefix bound in
the same module by another schema import, a module
import, a namespace declaration,
or a module declaration
[err:XQST0033].
If the schema import declaration specifies default element namespace
then the prolog must not contain a namespace declaration
that specifies default element namespace
or default type namespace
.
The first URILiteral in a schema import specifies the target
namespace of the schema to be imported.
The URILiterals that follow the at
keyword are optional location hints, and can be interpreted or disregarded in an
implementation-dependent way. Multiple location hints might be used to indicate more than one
possible place to look for the schema or multiple physical resources to be assembled to form
the schema.
If the target
namespace is http://www.w3.org/2005/xpath-functions
then the schema described in
Section
C Schemas
FO31 is imported; any location hints are ignored.
A schema import that specifies a zero-length string as target namespace is considered to
import a schema that has no target namespace. Such a schema import must not bind a namespace
prefix [err:XQST0057], but it may set the default element and/or type namespace
to a zero-length string (representing "no namespace"), thus enabling the definitions in the
imported namespace to be referenced. If the default element and/or type namespace is not set to "no
namespace", the only way to reference the definitions in an imported schema that has no
target namespace is using the EQName syntax Q{}local-name
.
It is a static error
[err:XQST0058] if more than one schema import in the same Prolog specifies the same target namespace. It is a static error
[err:XQST0059] if the implementation is not able to process a schema
import by finding a valid schema with the specified target namespace. It is a static error
[err:XQST0035] if multiple imported schemas, or multiple physical
resources within one schema, contain definitions for the same name in the same symbol space
(for example, two definitions for the same element name, even if the definitions are
consistent). However, it is not an error to import the schema with target namespace
http://www.w3.org/2001/XMLSchema
(predeclared prefix xs
), even
though the built-in types defined in this schema are implicitly included in the in-scope schema types.
It is a static error [err:XQST0012] if the set of definitions contained in all schemas imported by a Prolog do not satisfy the conditions for schema validity specified in Sections 3 and 5 of [XML Schema 1.0] or [XML Schema 1.1] Part 1--i.e., each definition must be valid, complete, and unique.
The following example imports a schema, specifying both its target namespace and its
location, and binding the prefix soap
to the target namespace:
import schema namespace soap="http://www.w3.org/2003/05/soap-envelope" at "http://www.w3.org/2003/05/soap-envelope/";
The following example imports a schema by specifying only its target namespace, and makes it the default namespace for elements and types:
import schema default element namespace "http://example.org/abc";
The following example imports a schema that has no target namespace, providing a location hint, and sets the default namespace for elements and types to "no namespace" so that the definitions in the imported schema can be referenced:
import schema default element namespace "" at "http://example.org/xyz.xsd";
The following example imports a schema that has no target namespace and sets the default namespace for elements and types to "no namespace". Since no location hint is provided, it is up to the implementation to find the schema to be imported.
import schema default element namespace "";
[23] | ModuleImport |
::= | "import" "module" ("namespace" NCName "=")? URILiteral ("at" URILiteral ("," URILiteral)*)? |
[Definition: A module import imports the public variable declarations, public function declarations, and public item type declarations from one or more library modules into the statically known function definitions, in-scope variables , or item type aliases of the importing module.] Each module import names a target namespace and imports an implementation-defined set of modules that share this target namespace. The module import may bind a namespace prefix to the target namespace, adding the (prefix, URI) pair to the statically known namespaces, and it may provide optional hints for locating the modules to be imported.
If a module A
imports module B
, the static context of module
A
will contain the in-scope schema definitions
and statically known function definitions of
module B
, and the dynamic context of module A
will contain the
variable values and dynamically known function definitions of module B
, with the
exception of non-public functions and variables, and of the functions and variables not
declared directly in B
.
The following example illustrates a module import:
import module namespace gis="http://example.org/gis-functions";
If a query imports the same module via multiple paths, only one instance of the module is imported. Because only one instance of a module is imported, there is only one instance of each variable declared in a module's prolog.
A module may import its own target namespace (this is interpreted as importing an implementation-defined set of other modules that share its target namespace.)
The namespace prefix specified in a module import must not be xml
or
xmlns
[err:XQST0070], and must not be the same as any namespace prefix bound in
the same module by another module import, a schema
import, a namespace declaration,
or a module declaration with a different target
namespace [err:XQST0033].
The first URILiteral in a module import must be of nonzero length
[err:XQST0088], and specifies the target namespace of the modules to be
imported. The URILiterals that follow the at
keyword are optional location hints,
and can be interpreted or disregarded in an implementation-defined way.
It is a static error
[err:XQST0047] if more than one module import in a Prolog specifies the same target namespace. It is a static error
[err:XQST0059] if the implementation is not able to process a module
import by finding a valid module definition with the specified target namespace. It is a
static error if two or more variables declared or
imported by a module have equal expanded QNames (as defined by the eq
operator) [err:XQST0049].
Each module has its own static context. A module import imports only functions, variable declarations, and item type declaratons; it does not import other objects from the imported modules, such as in-scope schema definitions or statically known namespaces. Module imports are not transitive—that is, importing a module provides access only to declarations contained directly in the imported module. For example, if module A imports module B, and module B imports module C, module A does not have access to the functions and variables declared in module C.
A module import does not import schema definitions from the imported module. In the following query, the type geometry:triangle is not defined, even if it is known in the imported module, so the variable declaration raises an error [err:XPST0051]:
(: Error - geometry:triangle is not defined :) import module namespace geo = "http://example.org/geo-functions"; declare variable $t as geometry:triangle := geo:make-triangle(); $t
Without the type declaration for the variable, the variable declaration succeeds:
import module namespace geo = "http://example.org/geo-functions"; declare variable $t := geo:make-triangle(); $t
Importing the schema that defines the type of the variable, the variable declaration succeeds:
import schema namespace geometry = "http://example.org/geo-schema-declarations"; import module namespace geo = "http://example.org/geo-functions"; declare variable $t as geometry:triangle := geo:make-triangle(); $t
The target namespace of a module should be treated in the same way as other namespace URIs.
To maximize interoperability, query authors should use a string that is a valid absolute IRI.
Implementions must accept any string of Unicode characters. Target namespace URIs are compared using the Unicode codepoint collation rather than any concept of semantic equivalence.
Implementations may provide mechanisms allowing the target namespace URI to be used as input to a process that delivers the module as a resource, for example a catalog, module repository, or URI resolver. For interoperability, such mechanisms should not prevent the user from choosing an arbitrary URI for naming a module.
Similarly, implementations may perform syntactic transformations on the target namespace URI to obtain the names of related resources, for example to implement a convention relating the name or location of compiled code to the target namespace URI; but again, such mechanisms should not prevent the user from choosing an arbitrary target namespace URI.
As with other namespace URIs, it is common practice to use target namespace URIs whose scheme is "http" and whose authority part uses a DNS domain name under the control of the user.
The specifications allow, and some users might consider it good practice, for the target namespace URI of a function library to be the same as the namespace URI of the XML vocabulary manipulated by the functions in that library.
Several different modules with the same target namespace can be used in the same query. The names of public variables and public functions must be unique within the module contexts of a query: that is, if two modules with the same target namespace URI are used in the same query, the names of the public variables and functions in their module contexts must not overlap.
If one module contains an "import module" declaration with the target namespace
M
, then all public variables and public functions in the contexts of modules
whose target namespace is M
must be accessible in the importing module,
regardless whether the participation of the imported module was directly due to this "import
module" declaration.
The term "location URIs" refers to the URIs in the "at" clause of an "import module" declaration.
Products should (by default or at user option) take account of all the location URIs in an "import module" declaration, treating each location URI as a reference to a module with the specified target namespace URI. Location URIs should be made absolute with respect to the static base URI of the module containing the "import module" declaration where they appear. The mapping from location URIs to module source code or compiled code MAY be done in any way convenient to the implementation. If possible given the product's architecture, security requirements, etc, the product should allow this to fetch the source code of the module to use the standard web mechanisms for dereferencing URIs in standard schemes such as the "http" URI scheme.
When the same absolutized location URI is used more than once, either in the same "import module" declaration or in different "import module" declarations within the same query, a single copy of the resource containing the module is loaded. When different absolutized location URIs are used, each results in a single module being loaded, unless the implementation is able to determine that the different URIs are references to the same resource. No error due to duplicate variable or functions names should arise from the same module being imported more than once, so long as the absolute location URI is the same in each case.
Implementations must report a static error if a location URI cannot be resolved after all available recovery strategies have been exhausted.
[24] | NamespaceDecl |
::= | "declare" "namespace" NCName "=" URILiteral
|
[Definition: A namespace declaration declares a namespace prefix and associates it with a namespace URI, adding the (prefix, URI) pair to the set of statically known namespaces.] The namespace declaration is in scope throughout the query in which it is declared, unless it is overridden by a namespace declaration attribute in a direct element constructor.
If the URILiteral part of a namespace declaration is a zero-length string, any existing
namespace binding for the given prefix is removed from the statically known namespaces. This feature provides a way to remove predeclared
namespace prefixes such as local
.
The following query illustrates a namespace declaration:
declare namespace foo = "http://example.org"; <foo:bar> Lentils </foo:bar>
In the query result, the newly created node is in the namespace associated with the namespace
URI http://example.org
.
The namespace prefix specified in a namespace declaration must not be xml
or
xmlns
[err:XQST0070]. The namespace URI specified in a namespace declaration
must not be http://www.w3.org/XML/1998/namespace
or
http://www.w3.org/2000/xmlns/
[err:XQST0070]. The namespace prefix specified in a namespace declaration
must not be the same as any namespace prefix bound in the same module by a module import, schema
import, module declaration, or another
namespace declaration [err:XQST0033].
It is a static error [err:XPST0081] if an expression contains a lexical QName with a namespace prefix that is not in the statically known namespaces.
XQuery has several predeclared namespace prefixes that are present in the statically known namespaces before each query is
processed. These prefixes may be used without an explicit declaration. They may be overridden
by namespace declarations in a Prolog or by namespace
declaration attributes on constructed elements (however, the prefix
xml
must not be redeclared, and no other prefix may be bound to the namespace
URI associated with the prefix xml
[err:XQST0070]). The predeclared namespace prefixes are as follows:
xml = http://www.w3.org/XML/1998/namespace
xs = http://www.w3.org/2001/XMLSchema
xsi = http://www.w3.org/2001/XMLSchema-instance
fn = http://www.w3.org/2005/xpath-functions
local = http://www.w3.org/2005/xquery-local-functions
(see 5.18 Function Declaration.)
Additional predeclared namespace prefixes may be added to the statically known namespaces by an implementation.
When element or attribute names are compared, they are considered identical if the local parts and namespace URIs match on a codepoint basis. Namespace prefixes need not be identical for two names to match, as illustrated by the following example:
declare namespace xx = "http://example.org"; let $i := <foo:bar xmlns:foo = "http://example.org"> <foo:bing> Lentils </foo:bing> </foo:bar> return $i/xx:bing
Although the namespace prefixes xx
and foo
differ, both are bound
to the namespace URI http://example.org
. Since xx:bing
and
foo:bing
have the same local name and the same namespace URI, they match. The
output of the above query is as follows.
<foo:bing xmlns:foo = "http://example.org"> Lentils </foo:bing>
[25] | DefaultNamespaceDecl |
::= | "declare" "default" ("element" | "type" | "function") "namespace" URILiteral
|
Default namespace declarations can be used in a Prolog to facilitate the use of unprefixed QNames.
The namespace URI specified in a default namespace declaration must not be
http://www.w3.org/XML/1998/namespace
or
http://www.w3.org/2000/xmlns/
[err:XQST0070].
The following kinds of default namespace declarations are supported:
[Definition: PLACEHOLDER]
A default element namespace declaration declares a namespace URI that
is associated with unprefixed names of elements .
This declaration is recorded as
the default element namespace in the
static context. A Prolog may contain at most one default element namespace declaration
and it must not contain
both a default element namespace declaration and an import schema
declaration
that specifies a default element namespace
[err:XQST0066] .
If the URILiteral in a
default element namespace declaration is a zero-length string, the default element namespace is undeclared (set to
absentDM31), and unprefixed names of elements are
considered to be in no namespace. The following example illustrates the declaration of a
default namespace for elements:
declare default element namespace "http://example.org/names";
If no default element namespace declaration is present, unprefixed element names are in no namespace (however, an implementation may define a different default as specified in C.1 Static Context Components.)
A default element namespace declaration also establishes a binding for the zero-length prefix in the statically known namespaces.
Note:
The default element namespace is used primarily for resolving unprefixed element names appearing
in path expressions such as /orders/order/price
. The binding for the zero-length prefix
in the statically known namespaces is used primarily for resolving unprefixed element
names in direct element constructors such as
<orders>{$x}</orders>
. Although the
default element namespace declaration sets both to the same namespace, they can be different
within the query: the binding for the zero-length prefix is affected by the presence of
a a namespace declaration attribute
(such as xmlns=""
)in a direct element constructor
In the absence of a default type namespace declaration, such a namespace declaration attribute also overrides the default element namespace.
For backwards compatibility reasons, if the prolog contains a default element namespace declaration and no default type namespace declaration, then the default namespace for types is set to be the same as the default namespace for elements.
A default type namespace declaration declares a namespace URI that
is associated with unprefixed names of types.
This declaration is recorded as
the default type namespace in the
static context. A Prolog may contain at most one default type namespace declaration
and it must not contain
both a default type namespace declaration and an import schema
declaration
that specifies a default element namespace
[err:XQST0066] .
If the URILiteral in a
default type namespace declaration is a zero-length string, the default type namespace is undeclared (set to
absentDM31), and unprefixed names of types are
considered to be in no namespace. The following example illustrates the declaration of a
default namespace for types:
declare default type namespace "http://www.w3.org/2001/XMLSchema";
This declaration allows names of built-in types to be used without a prefix, for example a function
parameter can be declared as $arg as integer
rather than $arg as xs:integer
.
Note however that it does not apply to the names of constructor functions, which use the default namespace
for functions.
A default type namespace declaration applies throughout the query module and cannot be overridden.
For backwards compatibility reasons, if the prolog contains no explicit default type namespace declaration, then:
A default element namespace declaration
in the prolog also sets the default namespace for types;
and
A namespace declaration attribute
xmlns="uuuu"
in a direct element constructor overrides both the default element namespace
and the default type namespace declared in the query prolog.
If no default element namespace declaration is present, unprefixed element names are in no namespace (however, an implementation may define a different default as specified in C.1 Static Context Components.)
For backwards compatibility reasons, if the prolog contains a default element namespace declaration and no default type namespace declaration, then the default namespace for types is set to be the same as the default namespace for elements.
A default function namespace declaration declares a namespace URI that is associated with unprefixed function names in static function calls and function declarations.
A Prolog may contain at most one
default function namespace declaration [err:XQST0066]. If the
StringLiteral
in a default function namespace declaration is a zero-length string, the
default function namespace is undeclared (set to absentDM31).
In that case, any functions that are associated with a namespace can be called only by
using an explicit namespace prefix.
If no default function namespace declaration is present, the default function namespace
is the namespace of XPath/XQuery functions,
http://www.w3.org/2005/xpath-functions
(however, an implementation may
define a different default as specified in C.1 Static Context Components.)
The following example illustrates the declaration of a default function namespace:
declare default function namespace "http://www.w3.org/2005/xpath-functions/math";
The effect of declaring a default function namespace is that all functions in the default function namespace, including implicitly declared constructor functions, can be invoked without specifying a namespace prefix. When a static function call uses a function name with no prefix, the local name of the function must match a function (including implicitly declared constructor functions) in the default function namespace [err:XPST0017].
Note:
Only constructor functions can be in no namespace.
Unprefixed attribute names and variable names are in no namespace.
[26] | AnnotatedDecl |
::= | "declare" Annotation* (VarDecl | FunctionDecl | ItemTypeDecl) |
|
[188] | InlineFunctionExpr |
::= |
Annotation* (("function" FunctionSignature) | ("->" FunctionSignature?)) FunctionBody
|
|
[27] | Annotation |
::= | "%" EQName ("(" Literal ("," Literal)* ")")? |
XQuery uses annotations to declare properties associated with functions (inline or declared
in the prolog) and variables. For instance, a function may be declared %public
or
%private
. The semantics associated with these properties are described in
5.18 Function Declaration.
Annotations are (QName, value)
pairs. If the EQName of the annotation is a
lexical QName, the prefix of the QName is resolved using
the statically known namespaces; if no prefix is present, the name is in the
http://www.w3.org/2012/xquery
namespace.
Implementations may define further annotations, whose behaviour is
implementation-defined. For instance, if the eg
prefix is bound to a namespace
associated with a particular implementation, it could define an annotation like
eg:sequential
.
If the namespace URI of an annotation is not recognized by the
implementation, then the annotation is ignored. Implementations may also provide a way for users to define their own annotations.
Implementations must not define annotations in
reserved namespaces; it
is a static error
[err:XQST0045]
for a user to define an annotation in a reserved namespace.
An annotation can provide values explicitly using a parenthesized list of literals. For instance, the annotation
%java:method("java.lang.Math.sin")
sets the value of the
java:method
annotation to the string value java.lang.Math.sin
.
[26] | AnnotatedDecl |
::= | "declare" Annotation* (VarDecl | FunctionDecl | ItemTypeDecl) |
|
[27] | Annotation |
::= | "%" EQName ("(" Literal ("," Literal)* ")")? |
|
[28] | VarDecl |
::= | "variable" "$" VarName
TypeDeclaration? ((":=" VarValue) | ("external" (":=" VarDefaultValue)?)) |
|
[151] | VarName |
::= |
EQName
|
|
[202] | TypeDeclaration |
::= | "as" SequenceType
|
|
[29] | VarValue |
::= |
ExprSingle
|
|
[30] | VarDefaultValue |
::= |
ExprSingle
|
A variable declaration adds the static type of a variable to the in-scope variables, and may also add a value for the variable to the variable values.
Note:
A variable declaration always refers to a declaration of a variable in a Prolog. The binding of a variable to a value in a query expression, such as a FLWOR expression, is known as a variable binding, and does not make the variable visible to an importing module.
During static analysis, a variable declaration causes a pair (expanded QName N, type
T)
to be added to the in-scope
variables. The expanded QName N is the VarName
. If N is equal (as
defined by the eq operator) to the expanded QName of another variable in in-scope variables, a
static error is raised [err:XQST0049].
The type T of the declared variable is as follows:
If TypeDeclaration
is present, then the SequenceType
in the
TypeDeclaration
; otherwise
If the Static Typing Feature is in effect and VarValue
is present, then the
static type inferred from static analysis of the expression VarValue
;
Note:
Type inference might not be computable until after the check for circular dependencies, described below, is complete.
Otherwise, item()*
.
All variable names declared in a library module must (when expanded) be in the target
namespace of the library module [err:XQST0048]. A variable declaration may
use annotations to specify that the variable is %private
or %public
(which is the default). [Definition: A
private variable is a variable with a %private
annotation. A
private variable is hidden from module import,
which can not import it into the in-scope
variables of another module.]
[Definition: A public variable is a
variable without a %private
annotation. A public variable is accessible to
module import, which can import it into the
in-scope variables of another module. Using
%public
and %private
annotations in a main module is not an
error, but it does not affect module imports, since a main module cannot be imported. It is
a static error
[err:XQST0116] if a variable declaration contains both a
%private
and a %public
annotation, more than one
%private
annotation, or more than one %public
annotation.]
Variable names that have no namespace prefix are in no namespace. Variable declarations that have no namespace prefix may appear only in a main module.
Here are some examples of variable declarations:
The following declaration specifies both the type and the value of a variable. This
declaration causes the type xs:integer
to be associated with variable
$x
in the static context, and
the value 7
to be associated with variable $x
in the dynamic context.
declare variable $x as xs:integer := 7;
The following declaration specifies a value but not a type. The static type of the variable is inferred from the static
type of its value. In this case, the variable $x
has a static type of
xs:decimal
, inferred from its value which is 7.5.
declare variable $x := 7.5;
The following declaration specifies a type but not a value. The keyword
external
indicates that the value of the variable will be provided by the
external environment. At evaluation time, if the variable $x
in the dynamic context does not have a value of type
xs:integer
, a type error is
raised.
declare variable $x as xs:integer external;
The following declaration specifies neither a type nor a value. It simply declares that
the query depends on the existence of a variable named $x
, whose type and
value will be provided by the external environment. During query analysis, the type of
$x
is considered to be item()*
. During query evaluation, the
dynamic context must include a type and a
value for $x
, and its value must be compatible with its type.
declare variable $x external;
The following declaration, which might appear in a library module, declares a variable whose name includes a namespace prefix:
declare variable $sasl:username as xs:string := "jonathan@example.com";
This is an example of an external variable declaration that provides a
VarDefaultValue
:
declare variable $x as xs:integer external := 47;
An implementation can provide annotations it needs. For instance, an implementation that supports volatile external variables might allow them to be declared using an annotation:
declare %eg:volatile variable $time as xs:time external;
[Definition: If a variable
declaration includes an expression (VarValue
or VarDefaultValue
),
the expression is called an initializing expression. The static context for an
initializing expression includes all functions, variables, and namespaces that are declared
or imported anywhere in the Prolog, other than the variable being declared.]
If a required type is defined, then the value obtained by evaluating the initializing expression is converted to the required type by applying the coercion rules. A type error occurs if this is not possible. In invoking the coercion rules, XPath 1.0 compatibility mode does not apply.
In a module's dynamic context, a variable value (or the context item) may depend on another variable value (or the context item). [Definition: A variable value (or the context item) depends on another variable value (or the context item) if, during the evaluation of the initializing expression of the former, the latter is accessed through the module context.]
In the following example, the value of variable $a
depends on the value of variable $b
because the evaluation of $a's initializing expression accesses the value of $b during the
evaluation of local:f()
.
declare variable $a := local:f(); declare variable $b := 1; declare function local:f() { $b };
A directed graph can be built with all variable values and the context item as nodes, and with the depend on relation as edges. This graph must not contain cycles, as it makes the population of the dynamic context impossible. If it is discovered, during static analysis or during dynamic evaluation, that such a cycle exists, error [err:XQDY0054] must be raised.
During query evaluation, each variable declaration causes a pair (expanded QName N,
value V)
to be added to the variable
values. The expanded QName N is the VarName
. The value V is as
follows:
If VarValue
is specified, then V is the result of evaluating
VarValue
.
If external
is specified, then:
if a value is provided for the variable by the external environment, then V is that value. The means by which typed values of external variables are provided by the external environment is implementation-defined.
if no value is provided for the variable by the external environment, and
VarDefaultValue
is specified, then V is the result of evaluating
VarDefaultValue
.
If no value is provided for the variable by the external environment, and
VarDefaultValue
is not specified, then a dynamic error is raised [err:XPDY0002].
It is implementation-dependent whether this error is raised if the evaluation of the query does not reference the value of the variable.
In all cases the value V must match the type T according to the rules for SequenceType matching; otherwise a type error is raised [err:XPTY0004].
[31] | ContextItemDecl |
::= | "declare" "context" "item" ("as" ItemType)? ((":=" VarValue) | ("external" (":=" VarDefaultValue)?)) |
A context item declaration allows a query to specify the static type, value, or default value for the initial context item.
Only the main module can set the value of the initial context item. In a library module, a context item declaration must be external, and specifies only the static type. Specifying a VarValue or VarDefaultValue for a context item declaration in a library module is a static error [err:XQST0113].
In every module that does not contain a context item declaration, the effect is as if the declaration
declare context item as item() external;
appeared in that module.
During static analysis, the context item declaration has the effect of setting the context
item static type T
in the static context. The context item static type is set to
ItemType
if specified, or to item()
otherwise.
If a module contains more than one context item declaration, a static error is raised [err:XQST0099].
The static context for an initializing expression includes all functions, variables, and namespaces that are declared or imported anywhere in the Prolog.
During query evaluation, a singleton focus is
created in the dynamic context for the evaluation of the QueryBody
in the main
module, and for the initializing expression of every variable declaration in every module.
The context item of this singleton focus is called
the initial context item,
which is selected as follows:
If VarValue
is specified, then
the initial context item is
the result of evaluating VarValue
.
Note:
In such a case, the initial context item does not obtain its value from the external environment. If the external environment attempts to provide a value for the initial context item, it is outside the scope of this specification whether that is ignored, or results in an error.
If external
is specified, then:
If the declaration occurs in a main module and a value is provided for the context item by the external environment, then the initial context item is that value.
Note:
If the declaration occurs in a library module, then it does not set the value of the initial context item, the value is set by the main module.
The means by which an external value is provided by the external environment is implementation-defined.
If no value is provided for the context item by the external environment, and
VarDefaultValue
is specified, then
the initial context item is
the result of evaluating
VarDefaultValue
as described below.
In all cases where the context item has a value, that value must match the type
T
according to the rules for SequenceType matching; otherwise a type error is
raised [err:XPTY0004]. If more than one module contains a context item
declaration, the context item must match the type declared in each one.
If VarValue
or VarDefaultValue
is evaluated, the static and dynamic
contexts for the evaluation are the current module's static and dynamic context.
If a required type is defined, then the value obtained by
evaluating VarValue
or VarDefaultValue
is converted to the required type by applying
the coercion rules. A type error occurs if this is not possible.
In invoking the coercion rules, XPath 1.0 compatibility mode does not apply.
Here are some examples of context item declarations.
Declare the type of the context item:
declare namespace env="http://www.w3.org/2003/05/soap-envelope"; declare context item as element(env:Envelope) external;
Declare a default context item, which is a system log in a default location. If the system log is in a different location, it can be specified in the external environment:
declare context item as element(sys:log) external := doc("/var/xlogs/sysevent.xml")/sys:log;
In addition to the built-in functions, XQuery allows users to declare functions of their own. A function declaration declares a family of functions having the same name and similar parameters. The declaration specifies the name of the function, the names and datatypes of the parameters, and the datatype of the result. All datatypes are specified using the syntax described in 3 Types.
Including a function declaration in the query causes a corresponding function definition to be added to the statically known function definitions of the static context. The associated functions also become available in the dynamically known function definitions of the dynamic context.
[26] | AnnotatedDecl |
::= | "declare" Annotation* (VarDecl | FunctionDecl | ItemTypeDecl) |
|
[27] | Annotation |
::= | "%" EQName ("(" Literal ("," Literal)* ")")? |
|
[32] | FunctionDecl |
::= | "function" EQName
FunctionSignatureWithDefaults (FunctionBody | "external") |
/* xgc: reserved-function-names */ |
[33] | FunctionSignatureWithDefaults |
::= | "(" ParamListWithDefaults? ")" TypeDeclaration? |
|
[35] | ParamListWithDefaults |
::= |
ParamWithDefault ("," ParamWithDefault)* |
|
[36] | ParamWithDefault |
::= | "$" EQName
TypeDeclaration? (":=" ExprSingle)? |
|
[39] | FunctionBody |
::= |
EnclosedExpr
|
|
[202] | TypeDeclaration |
::= | "as" SequenceType
|
|
[40] | EnclosedExpr |
::= | "{" Expr? "}" |
A function declaration specifies whether the implementation of the function is user-defined or external.
[Definition: User defined functions are functions that contain a function body, which provides the implementation of the function as a content expression.] The static context for a function body includes all functions, variables, and namespaces that are declared or imported anywhere in the Prolog, including the function being declared. Its in-scope variables component also includes the parameters of the function being declared. However, its context item static type component is absentDM31, and an implementation should raise a static error [err:XPST0008] if an expression depends on the context item.
The function declaration includes a list of zero or more function parameters. A parameter is
optional if a default value is supplied using the construct := ExprSingle
; otherwise it is required. If a parameter
is optional, then all subsequent parameters in the list must also be optional. In other words, the parameter list includes
zero or more required parameters followed by zero or more optional parameters.
The number of arguments that may be supplied in a call to this family of functions is this in the range M to N, where M is the number of required parameters, and N is the total number of parameters (whether required or optional). This is refered to as the arity range of the function definition.
The properties of the function definition F are derived from the syntax of the function declaration as follows:
The name of F is the expanded QName obtained by expanding the EQName
that follows the keyword function
.
The parameters of F are derived from the ParamWithDefault
entries in the
ParamListWithDefaults
:
The parameter name is the expanded QName obtained by expanding the EQName
that follows the $
symbol.
The required type of the parameter is given by the TypeDeclaration
, defaulting to item()*
.
The default value of the parameter is given by the expression that follows the :=
symbol; if there
is no default value, then the parameter is a required parameter.
The return type of the function is given by the final TypeDeclaration
that follows the ParamListWithDefaults
if present, defaulting to item()*
.
The function annotations are derived from the annotations that follow the %
symbol, if present.
The implementation of the function is given by the enclosed expression.
The static context may include more than one declared function with the same name, but their arity ranges must not overlap [err:XQST0034].
In function declarations, external functions are identified by the keyword
external
. The purpose of a function declaration for an external function is to
declare the datatypes of the function parameters and result, for use in type checking of the
query that contains or imports the function declaration.
In addition to user-defined functions and external functions, XQuery 4.0 allows anonymous functions to be declared in the body of a query using inline function expressions.
A function declaration may use the %private
or %public
annotations
to specify that a function is public or private; if neither of these annotations is used, the
function is public. [Definition: A private
function is a function with a %private
annotation. A private function
is hidden from module import, which can not import
it into the statically known function definitions of another module. ]
[Definition: A public function is a
function without a %private
annotation. A public function is accessible to
module import, which can import it into the
statically known function definitions of
another module. ] Using %public
and %private
annotations
in a main module is not an error, but it does not affect module imports, since a main module
cannot be imported. It is a static error
[err:XQST0106] if a function declaration contains both a
%private
and a %public
annotation, more than one
%private
annotation, or more than one %public
annotation.
An XQuery implementation may provide a facility whereby external functions can be implemented,
but it is not required to do so. If such a facility is
provided, the protocols by which parameters are passed to an external function, and the result
of the function is returned to the invoking query, are implementation-defined. An XQuery implementation
may augment the type system of [XQuery and XPath Data Model (XDM) 3.1] with additional types that
are designed to facilitate exchange of data, or it may provide
mechanism for the user to define such types. For example, a type might be provided that
encapsulates an object returned by an external function, such as an SQL database connection.
These additional types, if defined, are considered to be derived by restriction from
xs:anyAtomicType
.
An implementation can define annotations, in its own namespace, to support functionality beyond the scope of this specification. For instance, an implementation that supports external Java functions might use an annotation to associate a Java function with an XQuery external function:
declare %java:method("java.lang.StrictMath.copySign") function smath:copySign($magnitude, $sign) external;
Every declared function must be in a namespace; that is, every declared function name must (when expanded) have a non-null namespace URI [err:XQST0060]. If the function name in a function declaration has no namespace prefix, it is considered to be in the default function namespace. Every function name declared in a library module must (when expanded) be in the target namespace of the library module [err:XQST0048].
[Definition: A reserved namespace is a namespace that must not be used in the name of a function declaration.] It is a static error [err:XQST0045] if the function name in a function declaration (when expanded) is in a reserved namespace. The following namespaces are reserved namespaces:
http://www.w3.org/XML/1998/namespace
http://www.w3.org/2001/XMLSchema
http://www.w3.org/2001/XMLSchema-instance
http://www.w3.org/2005/xpath-functions
http://www.w3.org/2005/xpath-functions/math
http://www.w3.org/2012/xquery
http://www.w3.org/2005/xpath-functions/array
http://www.w3.org/2005/xpath-functions/map
In order to allow main modules to declare functions for local use within the module without
defining a new namespace, XQuery predefines the namespace prefix local
to the
namespace http://www.w3.org/2005/xquery-local-functions
. It is suggested (but not
required) that this namespace be used for defining local functions.
If a function parameter is declared using a name but no type, its default type is
item()*
. If the result type is omitted from a function declaration, its default
result type is item()*
.
The function body defines the implementation of the function definition. The rules for static function calls (see 4.4.1.2 Evaluating Static Function Calls) ensure that a value is available for each parameter, whether required or optional.
The parameters of a function declaration are considered to be variables whose scope is the function body. It is an static error [err:XQST0039] for a function declaration to have more than one parameter with the same name. The type of a function parameter can be any type that can be expressed as a sequence type.
The following example illustrates the declaration and use of a local function that accepts a
sequence of employee
elements, summarizes them by department, and returns a
sequence of dept
elements.
Using a function, prepare a summary of employees that are located in Denver.
declare function local:summary($emps as element(employee)*) as element(dept)* { for $d in fn:distinct-values($emps/deptno) let $e := $emps[deptno = $d] return <dept> <deptno>{$d}</deptno> <headcount> {fn:count($e)} </headcount> <payroll> {fn:sum($e/salary)} </payroll> </dept> }; local:summary(fn:doc("acme_corp.xml")//employee[location = "Denver"])
A function declaration may be recursive—that is, it may reference itself. Mutually
recursive functions, whose bodies reference each other, are also allowed. The following
example declares a recursive function that computes the maximum depth of a node hierarchy, and
calls the function to find the maximum depth of a particular document. The function
local:depth
calls the built-in functions empty
and
max
, which are in the default function namespace.
Find the maximum depth of the document named partlist.xml
.
declare function local:depth($e as node()) as xs:integer { (: A node with no children has depth 1 :) (: Otherwise, add 1 to max depth of children :) if (fn:empty($e/*)) then 1 else fn:max(for $c in $e/* return local:depth($c)) + 1 }; local:depth(fn:doc("partlist.xml"))
[TODO: add an example of a function with an optional parameter.]
An item type declaration defines a name for an item type. Defining a name for an item type
allows it to be referenced (using the syntax item-type(name)
rather than repeating
the item type definition in full.
[26] | AnnotatedDecl |
::= | "declare" Annotation* (VarDecl | FunctionDecl | ItemTypeDecl) |
|
[27] | Annotation |
::= | "%" EQName ("(" Literal ("," Literal)* ")")? |
|
[41] | ItemTypeDecl |
::= | "item-type" EQName "as" ItemType
|
An item-type declaration adds a named item type to the item type aliases of the containing module. This enables the item type to be referred to using a simple name.
For example, given the declaration:
declare item-type app:invoice as map("xs:string", element(inv:paid-invoice))
It becomes possible to declare a variable containing a sequence of such items as:
declare variable $invoices as app:invoice*
The definition can also be used within another item-type declaration:
declare item-type app:overdue-invoices as map("xs:date", app:invoice*)
If the name of the item type is written as an (unprefixed) NCName, then it is interpreted as being in no namespace.
All item type names declared in a library module must (when expanded) be in the target namespace of the library module [err:XQST0048].
An item type declaration may use the %private
or %public
annotations
to specify that an item type name is public or private; if neither of these annotations is used, the
declaration is public. [Definition: A private
item type is a named item type with a %private
annotation. A private item type
is hidden from module import, which can not import
it into the item type aliases of another module. ]
[Definition: A public item type is an
item type declaration without a %private
annotation. A public item type is accessible to
module import, which can import it into the
item type aliases of
another module. ] Using %public
and %private
annotations
in a main module is not an error, but it does not affect module imports, since a main module
cannot be imported. It is a static error
[err:XQST0106] if an item type declaration contains both a
%private
and a %public
annotation, more than one
%private
annotation, or more than one %public
annotation.
A static error must be reported if the definition of item types is cyclic: that is, if the definition of an item type depends directly or indirectly on itself. [TODO: ERROR CODE]
[Definition: An option declaration declares an option that affects the behavior of a particular implementation. Each option consists of an identifying EQName and a StringLiteral.]
[42] | OptionDecl |
::= | "declare" "option" EQName
StringLiteral
|
Typically, a particular option will be recognized by some implementations and not by others. The syntax is designed so that option declarations can be successfully parsed by all implementations.
If the EQName of an option is a lexical QName with a prefix, it must resolve to a namespace URI and local name, using the statically known namespaces [err:XPST0081].
If the EQName of an option is a lexical QName that does not have a prefix, the expanded QName is in the http://www.w3.org/2012/xquery
namespace,
which is reserved for option declarations defined by the XQuery family of specifications.
XQuery does not currently define declaration options in this namespace.
Each implementation recognizes the http://www.w3.org/2012/xquery
namespace URI
and and all options defined in this namespace in this specification. In addition, each
implementation recognizes an implementation-defined set of namespace URIs and an implementation-defined set of
option names defined in those namespaces. If the namespace part of an option declaration's
name is not recognized, the option declaration is ignored.
Otherwise, the effect of the option declaration, including its error behavior, is implementation-defined. For example, if the local part of the QName is not recognized, or if the StringLiteral does not conform to the rules defined by the implementation for the particular option declaration, the implementation may choose whether to raise an error, ignore the option declaration, or take some other action.
Implementations may impose rules on where particular option declarations may appear relative to variable declarations and function declarations, and the interpretation of an option declaration may depend on its position.
An option declaration must not be used to change the syntax accepted by the processor, or to suppress the detection of static errors. However, it may be used without restriction to modify the semantics of the query. The scope of the option declaration is implementation-defined—for example, an option declaration might apply to the whole query, to the current module, or to the immediately following function declaration.
The following examples illustrate several possible uses for option declarations:
This option declaration might be used to specify how comments in source documents
returned by the fn:doc()
function should be handled:
declare option exq:strip-comments "true";
This option declaration might be used to associate a namespace used in function names with a Java class:
declare namespace smath = "http://example.org/MathLibrary"; declare option exq:java-class "smath = java.lang.StrictMath";