Prolog Declarations

The prolog consists of a series of declarations terminated by semicolon (;) characters. There are three distinct sections of the prolog.

The first declaration to appear in the query prolog is a version declaration, if it exists.

The second prolog section consists of setters, imports, and namespace declarations. Setters are the declarations listed in Table 12-1, along with a link to where they are covered fully in the book. Each kind of setter can only appear once.

Imports and namespace declarations, listed in Table 12-2, can appear multiple times (with different values), intermingled with setters in any order.

The last section of the prolog consists of function, variable, context item, and option declarations, listed in Table 12-3. They must appear after all the setters, imports, and namespace declarations.

It is important to note that your processor might also be setting these values. For example, different XQuery implementations can choose to build in different default collations or different sets of predefined functions. In addition, an implementation might allow the user to specify these values outside the query—for example, using a command-line interface. Prolog declarations override or augment the default settings defined outside the scope of the query.

The Version Declaration

The first of the declarations in Example 12-1 is a version declaration, whose syntax is shown in Figure 12-1. The version declaration is used to indicate the version of the XQuery language. Appropriate values are 1.0, 3.0 or 3.1. If the version is not specified, the default value depends on which version the processor supports. If it is an XQuery 3.1 processor, it will assume the version is 3.1. If a version declaration does appear, it must appear first in the query, even before any comments.

Figure 12-1. Syntax of a version declaration

The version declaration also allows you to specify a character encoding for the query itself by using the encoding keyword and a literal string. For example, the following version declaration specifies an encoding of UTF-8:

xquery version "3.1" encoding "UTF-8";

Other example values for the encoding include UTF-16, ISO-8859-1, and US-ASCII. The way encoding is handled is somewhat implementation-dependent, in that processors are allowed to ignore the encoding value specified in the query if they have other knowledge about the encoding.

Because the encoding of a file can easily change unintentionally—for example, when you save it by using a text editor—it’s safest to stick to using ASCII characters in the query, using numeric character references for any non-ASCII characters. This does not prevent you from specifying the encoding as UTF-8, because ASCII is a subset of UTF-8.

Library Modules

Library modules differ from main modules in that they cannot have a query body, only a prolog. They also differ in that they must start with a module declaration, whose syntax is shown in Figure 12-2.

Figure 12-2. Syntax of a module declaration

The module declaration identifies the module as a library module. It also declares the target namespace of the module and binds it to a prefix. For example, the expression:

module namespace strings = "http://datypic.com/strings";

declares the target namespace of the module to be http://datypic.com/strings and binds that namespace to the prefix strings.

The target namespace must be a literal value in quotes, not an evaluated expression. It should be a syntactically valid absolute URI, and cannot be a zero-length string.

The names of all the functions and variables declared in that library module must be qualified with that same target namespace. This differs from main modules, which do not have target namespaces and allow you to declare variables and functions in a variety of namespaces.

A library module is shown in Example 12-3, where the variable and function names are prefixed with strings.

module namespace strings = "http://datypic.com/strings";
declare variable $strings:maxStringLength := 32;
declare function strings:trim($arg as xs:string?) as xs:string? {
  replace(replace($arg,'^s+',''),'s+$','')
};

Importing a Library Module

Both main modules and library modules can import other library modules. Importing a library module allows its variables and functions to be referenced from the importing module. Only library modules can be imported; a main module can never be imported by another module.

A module import, which appears in the prolog, specifies the target namespace and location (URI) of the library module to be imported. Multiple module imports can appear in the query prolog. The syntax of a module import is shown in Figure 12-3.

Figure 12-3. Syntax of a module import

For example, the declaration:

import module "http://datypic.com/strings"
           at "http://datypic.com/input/strings.xqm";

imports the module from http://datypic.com/input/strings.xqm whose target namespace is http://datypic.com/strings. The target namespace specified in the module import must match the target namespace of the library module that is being imported. The module location and namespace must be literal values in quotes (not evaluated expressions), and they should be syntactically valid URIs. If the location is a relative URI, it is resolved relative to the static base URI, for example:

declare base-uri "http://datypic.com/";
import module "http://datypic.com/strings"
              at "strings.xqm";

Imported modules can have the same target namespace as the importing module, or they can have a different one. For convenience, it is also possible to bind a namespace prefix directly in the module import. For example:

import module namespace strings = "http://datypic.com/strings"
                        at "http://datypic.com/input/strings.xqm";

binds the prefix strings to the namespace, in addition to importing the module.

The at keyword and location are optional. If the processor has some other way to locate the module based on its target namespace, it can be omitted. In fact, the processor is not required to use the location even if it is provided. The processor also has some leeway in how it interprets the location. One implementation might treat the location like a filename and look for the module on the filesystem, while another might consider it an identifier that allows them to retrieve it from an XML database.

import module "http://datypic.com/strings"
               at "http://datypic.com/input/strings.xqm",
                  "http://datypic.com/input/strings2.xqm";

Loading a Library Module Dynamically

Starting in version 3.1, a built-in function load-xquery-module can also be used to gain access to the functions and variables in a library module. Calling this function has some benefits over using a module import declaration in the prolog. The function allows you to dynamically pass a context item, and values for external variables. It also allows modules to be loaded dynamically, only if they are needed. Detailed information on this function can be found in Appendix A, in the “load-xquery-module” section.

Variable Declaration Syntax

The syntax of a variable declaration is shown in Figure 12-4. As you can see, a variable declaration consists of several parts:

• The keyword declare.

• An optional %public or %private annotation, described in “Private Functions and Variables”. Other annotations are also allowed here, as described in “Annotations”.

• The keyword variable followed by the qualified variable name.

• An optional as clause, which declares the type of the variable, as described in “Type Declarations in Global Variable Declarations”.

• Either an initializing expression that binds a value to the variable, or the keyword external indicating that it is an external variable.

Figure 12-4. Syntax of a variable declaration

For example, the declaration:

declare variable $maxItems := 12;

binds the value 12 to the variable $maxItems.

The Scope of Variables

The processor evaluates all variable declarations before it evaluates the query body. When a variable declaration is evaluated, the variable is bound to a specific value, and you can reference that variable anywhere in the query. When variable declarations appear in library modules, those variables can be also referenced in any modules that import that library module.

As with all other XQuery variables, a variable can only be bound once. Therefore, you cannot declare a variable in the prolog and then set its value later, for example, in a let expression. If you attempt to do this, it will not raise an error, but it will be considered an entirely new variable with the same name and a smaller scope (the FLWOR).

Variable Names

Each variable declaration specifies a unique variable name. Variables have qualified names, meaning that they can be associated with a namespace. In the main module, variable declarations can have either unprefixed or prefixed names. If they have unprefixed names, they are not in any namespace, because variable names are not affected by default namespace declarations. If they are prefixed, they can be associated with any namespace that was also declared in the prolog.

In library modules, on the other hand, the names of declared variables must be in the target namespace of the module. Because default namespace declarations do not apply to variable names, they must be prefixed with a prefix bound to the target namespace. This applies only to the variables that are declared in the prolog. If other variables are bound inside a function body, for example in let clauses, they can be in no namespace (unprefixed) or associated with a namespace other than the target namespace.

Initializing Expressions

The initializing expression appears after := and specifies the value of the variable. It can be any XQuery expression. For example:

declare variable $firstNum := doc("catalog.xml")//product[1]/number;

binds the value of the first product number in the catalog to the $firstNum variable.

The initializing expression can call any function, or reference any other global variable, that is declared anywhere in the module or in an imported module. However, the variable declarations cannot be circular in that they depend on each other. For example, the following is invalid because the declarations of $varA and $varC depend on each other indirectly:

declare variable $varA := $varB + 1;
declare variable $varB := $varC + 1;
declare variable $varC := $varA + 1;

External Variables

External variables are variables whose values are passed to the query by the external environment. This is useful for parameterizing queries. For example, an external variable might allow a query user to specify the maximum number of items she wants returned from the query.

To declare an external variable, you use the keyword external instead of an initializing expression, as in:

declare variable $maxItems external;

In this case, the processor must pass a $maxItems value to the query, or error XPDY0002 is raised. Starting in version 3.0, it is also possible to specify a default value for an external variable. It is used in case a value is not passed to the query. This is done with an initializing expression after the keyword external, for example:

declare variable $maxItems external := 100;

In this case, if the processor passes a value to the query, it is used, otherwise the value 100 is used. Consult the documentation of your XQuery implementation to determine exactly how you can specify the values of external variables outside the query. It may allow them to be specified on a command-line interface or set programmatically.

Note that external variables are not the same thing as variables that are imported from other XQuery modules. Variables from imported modules do not need to be redeclared in the importing module.