XQuery Scripting Extension 1.0

2.1.1 Evaluation Order

XQSE defines an ordering on the evaluation of certain kinds of XQuery expressions. An implementation may use any execution strategy as long as the result complies with the semantics of this ordering. Since some of the expressions introduced by XQSE have immediate side effects, a well-defined evaluation order is necessary for a deterministic result.

XQSE semantics are defined by the following evaluation order:

FLWOR: The for, let, where, and order-by clauses are initially evaluated as specified by [XQuery 1.0], generating a tuple stream. Then the return clause is evaluated once for each tuple in the tuple stream, in order. If the return clause contains a sequential expression, the side effects of each iteration are visible to subsequent evaluations of the return clause.

Function calls: Argument expressions are evaluated before the function body.

If-then-else: The test expression is evaluated first. Next either the then expression or the else expression (but not both) is evaluated.

Typeswitch: The operand expression is evaluated first. Then, exactly one of the return expressions is evaluated.

Concatenate (comma): Operand expressions are evaluated once, from left to right. Side effects of each sequential operand expression are visible to subsequent operand expressions.

Block: Variable declarations are evaluated first, in the order written; then the expression in the body is evaluated.

While: The test expression is evaluated first. If its effective Boolean value is false, the body is not evaluated. If the effective Boolean value of the test expression is true, the body is evaluated repeatedly until the value of the test expression becomes false. Side effects of each iteration are visible to subsequent iterations.

2.1.2 Snapshot Scope

The term snapshot is defined in [XQuery Update Facility] as follows: [Definition: A snapshot is a scope within which expressions are evaluated with respect to a fixed XDM instance and updates are held pending.] A snapshot is terminated by invocation of the upd:applyUpdates operation. Unlike XQUF, XQSE permits a query to contain more than one snapshot. In XQSE, each of the following expressions is a snapshot:

• each ConcatExpr within an ApplyExpr

• each initialization expression in a BlockVarDecl

• the expression on the right-hand side of an AssignmentExpr

• the expression in an ExitExpr

• the test expression in a WhileExpr

Like [XQuery Update Facility], this specification defines the semantics of operations on an XDM instance. Propagation of changes to an underlying persistent store (if any) is beyond the scope of this specification. Thus, for example, it is implementation-defined whether the effects of an fn:put function are visible to an fn:doc, fn:doc-available, or fn:collection function executed in a subsequent snapshot.

2.1.3 Variable Binding Revalidation

To ensure type soundness, variable bindings are revalidated at the end of each scope to ensure that any updates applied have not made them invalid with repect to their declared types. It is a dynamic error [err:TBD] if, after applying a pending update list (using upd:applyUpdates), the XDM instance bound to any in-scope variable does not match the static type of that variable according to SequenceType matching rules.

2.2.1 Constants and Variables

[Definition: XQSE allows the keyword constant to be used in place of variable in a Prolog declaration. A variable declared in this way is called a constant.]

Rules for initializing variables and for determining the scope of variables apply equally to constants. The semantics of constants are the same as the semantics of variables, with the following exception: It is a static error [err:TBD] if a constant appears on the left-hand-side of an assignment expression.

The initializing expression in a variable or constant declaration in a Prolog must be a simple expression [err:TBD].

2.2.2 Function Declarations

Definitions:

[Definition: A simple function is a function whose declaration specifies neither updating nor sequential. A simple function may optionally specify the keyword simple.]

[Definition: An updating function is a function whose declaration specifies the keyword updating.]

[Definition: A sequential function is a function whose declaration specifies the keyword sequential.]

Category Rules:

If the body of a simple function is an EnclosedExpr, it must be a simple expression.

If the body of an updating function is an EnclosedExpr, it must be either an updating or simple expression.

If the body of a sequential function is a Block it must be either a sequential or simple expression.

Semantics:

The semantics of simple functions are defined in [XQuery Update Facility] and [XQuery 1.0], and remain unchanged in XQSE.

The semantics of updating functions as originally defined in [XQuery Update Facility] are extended as follows:

• A return type is permitted.

• If external is specified, the external function may return both a non-empty pending update list and a non-empty XDM instance.

• If the result of an updating function does not match its declared result type (after applying function conversion rules as specified in Section 3.1.5 Function Calls^XQ), a type error is raised [err:XPTY0004]. The default result type of an updating function is item()*.

The semantics of sequential functions are as follows:

• The result of a sequential function is determined by the first [2.3.4 Exit Expression] encountered during evaluation of the Block. If no exit expression is encountered, the result of the function is the value returned by the Block that comprises its body.

• If the result of a sequential function does not match its declared result type (after applying function conversion rules as specified in Section 3.1.5 Function Calls^XQ), a type error is raised [err:XPTY0004]. The default result type of a sequential function is item()*.

• If a sequential function is declared external, its implementation is outside the XQuery environment. The means by which parameters are passed to an external function and its result is returned to the calling expression are implementation-defined. An external sequential function may not return a non-empty pending update list [err:TBD].

2.3.1 Apply Expression

Category Rules:

The operands of the apply expression may be an expression of any category.

An apply expression is a sequential expression.

Semantics:

An apply expression consists of one or more semicolon-terminated operand expressions. The operand expressions are evaluated in the order they appear. After the evaluation of each operand expression, the pending update list returned by the expression is applied (by upd:applyUpdates). The XDM instance returned by all expressions other than the last one is discarded. The side effects of each expression are visible during the evaluation of subsequent expressions.

The result of the apply expression is the XDM instance returned by the last operand expression, and an empty pending update list.

2.3.2 Block Expressions

Category Rules:

[Definition: The expression on the right-hand side of a block variable declaration is called an initializing expression.] Initializing expressions may be in any category.

Note:

Block variable declarations, unlike Prolog variable declarations, permit their initializing expressions to be updating or sequential expressions.

If a BlockExpr contains initializing expressions that are either updating or sequential expression, then the BlockExpr is a sequential expression. In this case the BlockBody must be either a simple or sequential expression.

If a BlockExpr only contains initializing expressions that are simple expressions (or contains no initializing expressions), then the BlockBody may be an expression of any category. In this case the BlockExpr has the same category as the BlockBody.

Semantics:

A block consists of zero or more block variable declarations followed by a body. Each block variable declaration defines a modifiable local variable whose scope is the remainder of the block (not including its initializing expression). The variable defined in a block variable declaration occludes (hides) any variable of the same name that is in scope at the location where the block appears.

It is a static error [err:TBD] if two or more variables declared in the same block have the same expanded QName.

The type of each declared variable is added to in-scope variables in the static context. If no explicit type is declared, the type of the variable is inferred from the type of its initializing expression. If the variable has neither an explicit type declaration nor an initializing expression, its type is item()*. If a variable has both an explicit type declaration and an initializing expression, the value of the initializing expression must match the declared type according to SequenceType matching rules; otherwise a type error is raised [err:TBD].

The block variable declarations are evaluated in the order written. The block variable declaration evaluates its initializing expression and adds the resulting XDM instance to the variable values in the dynamic context. Any pending update list returned is applied using upd:applyUpdates. If no initializing expression is present, the variable has no initial value. A reference to a variable, other than on the left-hand side of an assignment expression, is an error if the variable has no value in variable values when the reference is evaluated [err:TBD].

After all the block variable declarations have been evaluated, the BlockBody expression is evaluated. The result of the block expression is the XDM instance and pending update list returned by the BlockBody.

2.3.3 Assignment Expression

Category Rules:

An assignment expression is a sequential expression.

Semantics:

The variable on the left-hand side of the assignment must have been declared in one of three ways:

• By a block variable declaration

• As a parameter to a sequential function

• By a variable declaration in the Prolog

In all cases the variable must be in the in-scope variables, otherwise a static error is raised [err:TBD].

Note:

Variables bound in FLWOR, typeswitch, or quantified expressions may not appear on the left-hand side of an assignment.

The expression on the right-hand side is evaluated, resulting in an XDM instance and a pending update list.

If the XDM instance returned by the expression on the right-hand side does not match the declared type of the variable according to SequenceType matching rules, a type error is raised [err:TBD]. If the types match, the XDM instance returned by the expression is bound to the variable (added to variable values in the dynamic context.)

The pending update list returned by the expression on the right-hand side is applied using upd:applyUpdates.

The result of an Assignment Expression is an empty XDM instance and an empty pending update list.

2.3.4 Exit Expression

Category Rules:

The operand of an exit expression may be an expression of any category.

An exit expression is a sequential expression.

Semantics:

An exit expression serves to define the result of the enclosing function or query body.

The operand expression of the exit expression is evaluated, resulting in an XDM instance and a pending update list. The pending update list returned by the operand expression is applied using upd:applyUpdates.

If an exit expression is evaluated within the body of a function, further evaluation of the function body is interrupted and the XDM instance returned by the operand expression is returned as the result of the function call.

If an exit expression is evaluated within a query body (i.e., not within the body of a function), further evaluation of the query is interrupted and the XDM instance returned by the operand expression is returned as the result of the query.

Note:

An exit expression in a block terminates evaluation of the enclosing function body or query, not just the immediately enclosing block.

2.3.5 While Expression

Category Rules:

[Definition: The expression enclosed in the parentheses of a while expression is called a test expression.] The test expression may be in any category.

The WhileBody can be an expression of any category.

A while expression is a sequential expression.

Semantics:

The while expression is used for conditional iteration. It is evaluated as follows:

The test expression is evaluated, resulting in an XDM instance and a pending update list. The pending update list returned by the test expression is applied using upd:applyUpdates.

If the effective Boolean value of the test expression is false, the block is not evaluated. If the effective Boolean value of the test expression is true, the block is evaluated repeatedly. Each evaluation of the block may cause side effects that affect the result of re-evaluating the test expression. The test expression is re-evaluated after each evaluation of the block. This process continues until the effective Boolean value of the test expression is evaluated to be false.

The result of a while expression is an empty XDM instance and an empty pending update list.

Example:

In the following query, a while expression is used to compute a sequence containing all the Fibonacci numbers that are less than 100.

block {
  declare $a as xs:integer := 0;
  declare $b as xs:integer := 1;  
  declare $c as xs:integer := $a + $b;
  declare $fibseq as xs:integer* := ($a, $b);
 
  while ($c < 100) { 
     set $fibseq := ($fibseq, $c);
     set $a := $b;
     set $b := $c;
     set $c := $a + $b;
  };

  $fibseq;
}

2.4.1 Function Calls

Category Rules:

If the function called is a simple function, the argument expressions must be simple expressions or updating expressions. If the argument expressions contain an updating expression then the function call is an updating expression, otherwise it is a simple expression.

If the function called is an updating function, the argument expressions must be simple expressions or updating expressions. The function call is an updating expression.

If the function called is a sequential function, the argument expressions must be simple expressions. The function call expression is a sequential expression.

Semantics:

The pending update lists returned by the argument expressions are merged with the pending update list returned by the function itself by calling upd:mergeUpdates.

2.4.2 FLWOR Expressions

Category Rules:

The for, let, where, and order by clauses must contain either simple expressions or updating expressions.

• If the above clauses contain an updating expression, then the return clause must be a simple expression or an updating expression. The FLWOR expression itself is an updating expression.

• If the above clauses do not contain an updating expression, then the return clause may be an expression of any category. The category of the FLWOR expression is the same as the category of the expression in its return clause.

Semantics:

The result of a FLWOR expression is the concatenation of the XDM instances or pending update lists returned by successive evaluations of the return clause in evaluation order, as well as the pending update lists returned by any of the other FLWOR clauses. Pending update lists are concatenated by the upd:mergeUpdates operation.

2.4.3 Conditional Expressions

Category Rules:

The test expression must be a simple expression or an updating expression.

Let the then and else expressions be called branches. Then:

• If one branch is an updating expression, the other branch must be an updating expression or a simple expression. In this case, the conditional expression is an updating expression.

• If one branch is a sequential expression, the other branch must be a sequential expression or a simple expression. In this case, the conditional expression is a sequential expression.

• Otherwise, the conditional expression is a simple expression.

Semantics:

The pending update list returned by the conditional expression is calculated by merging the pending update lists from the test expression and the executed branch of the conditional expression using upd:mergeUpdates.

2.4.4 Typeswitch Expressions

Category Rules:

The expression in the operand expression must be a simple expression or an updating expression.

Let the expressions in the case and default clauses be called branches. Then:

• If any branch is an updating expression, the other branches must be updating expressions or simple expressions. In this case, the typeswitch expression is an updating expression.

• If any branch is a sequential expression, then all branches must be sequential or simple expressions. In this case, the typeswitch expression is a sequential expression.

• Otherwise, the typeswitch expression is a simple expression.

Semantics:

The pending update list returned by the typeswitch expression is calculated by merging the pending update lists from the operand expression and the executed branch of the typeswitch expression using upd:mergeUpdates.

2.4.5 Comma Expressions

Category Rules:

The category of a comma expression is determined by the following rules:

• If any operand is an updating expression, then all operands must be updating or simple expressions. In this case, the comma expression is an updating expression.

• If any operand is a sequential expression, then all operands must be sequential or simple expressions. In this case, the comma expression is a sequential expression.

• Otherwise, the comma expression is a simple expression.

Semantics:

The comma expression evaluates each of its operands and concatenates the resulting XDM instances and pending update lists, in order. Pending update lists are concatenated by the upd:mergeUpdates operation.

2.4.6 Parentheses

Category Rules:

An expression of any category may be enclosed in parentheses; the resulting expression has the same category as the original expression. An empty parenthesized expression ( ) is a simple expression.

2.4.7 Ordered and Unordered Expressions

Category Rules:

The operand of an ordered or unordered expression may be an expression of any category. The category of the ordered or unordered expression is the same as the category of its operand.

2.4.8 Transform Expressions

Category Rules:

The modify clause must contain an updating or simple expression.

The copy clause must contain a simple expression or an updating expression.

• If the copy clause contains a simple expression, the return clause may be an expression of any category. In this case, the category of the transform expression is the same as the category of its return clause.

• If the copy clause contains an updating expression, the return clause can contain an updating or simple expression. In this case, the transform expression is an updating expression.

Semantics:

The semantics of a transform expression as defined in Section 2.4.5 Transform^XU are extended as follows:

• If the modify clause returns a non-empty XDM instance it is discarded.

• The pending update list returned by the transform expression is calculated by merging the pending update lists from the copy clause and the return clause using upd:mergeUpdates.

2.4.9 Extension Expressions

Category Rules:

The operand of an extension expression may be an expression of any category. The category of the extension expression is the same as the category of its operand.

2.4.10 Insert, Delete, Replace, and Rename Expressions

Category Rules:

Insert, delete, replace, and rename expressions are updating expressions, and are extended to accept both updating and simple expressions as their operands.

Semantics:

The pending update list returned by insert, delete, replace, and rename expressions is calculated by merging the pending update lists from the operands of the expression and the pending update list produced by the expression itself using upd:mergeUpdates.

2.4.11 Other Expressions

Category Rules:

All expressions not listed above are extended to accept both updating and simple expressions as their operands. If an operand of the expression is updating then the expression itself is updating, otherwise it is simple.

This includes the following kinds of expressions:

• Path expressions

• Filter expressions

• Range expressions

• Union, intersect, and except expressions

• Arithmetic, comparison, and logical expressions

• Constructors of all kinds

• Quantified expressions

• Instance of, cast, castable, and treat expressions

• Validate expressions