Enclosed expressions that evaluate to elements

As you have seen with the li elements, elements in the sequence become children of the element being constructed (in this case, ul). Atomic values, on the other hand, become character data content. If the enclosed expression evaluates to a sequence of both elements and atomic values, as shown in Example 5-5, the result element has mixed content, with the order of the child elements and character data preserved.

for $prod in doc("catalog.xml")/catalog/product
return <li>number: {$prod/number}</li>

<li>number: <number>557</number></li>
<li>number: <number>563</number></li>
<li>number: <number>443</number></li>
<li>number: <number>784</number></li>

Example 5-3 used the data function in enclosed expressions to extract the values of the elements number and name. In this example, the number element is included without applying the data function. The results are somewhat different; instead of just the number value itself, the entire number element is included.

Enclosed expressions that evaluate to attributes

If an element constructor contains an enclosed expression that evaluates to one or more attributes, these attributes become attributes of the element under construction. This is exhibited in Example 5-6, where the enclosed expression {$prod/@dept} has been added at the beginning of the li constructor content.

for $prod in doc("catalog.xml")/catalog/product
return <li>{$prod/@dept}number: {$prod/number}</li>

<li dept="WMN">number: <number>557</number></li>
<li dept="ACC">number: <number>563</number></li>
<li dept="ACC">number: <number>443</number></li>
<li dept="MEN">number: <number>784</number></li>

The dept attribute appears in the results as an attribute of the li element rather than as content of the element. If the example had used the data function within the enclosed expression, the value of the dept attribute would have been the first character data content of the li element.

Enclosed expressions that evaluate to attributes must appear first in the element constructor content, before any other kinds of nodes.

Enclosed expressions that evaluate to atomic values

If an enclosed expression evaluates to one or more atomic values, those values are simply cast to xs:string and included as character data content of the element. When adjacent atomic values appear in the expression sequence, they are separated by a space in the element content. For example:

<li>{"x", "y", "z"}</li>

will return <li>x y z</li>, with spaces. To avoid this, you can use three separate expressions, as in:

<li>{"x"}{"y"}{"z"}</li>

Another option is to use the concat function to concatenate them together into a single expression, as in:

<li>{concat("x", "y", "z")}</li>

Enclosed expressions with multiple sub-expressions

Enclosed expressions may include more than one sub-expression inside the curly braces, using commas as separators. In Example 5-7, the enclosed expression in the li constructor contains four different sub-expressions, separated by commas.

for $prod in doc("catalog.xml")/catalog/product
return <li>{$prod/@dept, "string", 5+3, $prod/number}</li>

<li dept="WMN">string 8<number>557</number></li>
<li dept="ACC">string 8<number>563</number></li>
<li dept="ACC">string 8<number>443</number></li>
<li dept="MEN">string 8<number>784</number></li>

The first sub-expression, $prod/@dept, evaluates to an attribute, and therefore becomes an attribute of li.

The next two sub-expressions, "string" and 5+3, evaluate to atomic values: a string and an integer, respectively. Note that they are separated by a space in the results.

The final sub-expression, $prod/number, is an element, which is not separated from the atomic values by a space.

Boundary whitespace

Boundary whitespace is whitespace that occurs by itself (without any non-whitespace characters) in direct element constructors. It may appear between two element constructor tags, between two enclosed expressions, or between a tag and an enclosed expression. It can be made up of any of the XML whitespace characters, namely space, tab, carriage return, and line feed.

For example, in the constructor shown in Example 5-12, there is boundary whitespace in the ul constructor between the ul start tag and the left curly brace, as well as between the right curly brace and the ul end tag. In the li constructor, there is boundary whitespace between the li start tag and the b start tag, between the b end tag and the left curly brace, and between the right curly brace and the li end tag.

<ul>
  {  <li>  <b> number:</b> { "557" }  </li>   }
</ul>

With boundary whitespace discarded, the results look something like:

<ul><li><b> number:</b><number>557</number></li></ul>

Note that the space before the text number: is not discarded because it appears with other characters. Of course, if you choose to serialize and indent your results, new whitespace will be added for the indentation. Therefore, your results may vary.

Whitespace inside enclosed expressions that is not in quotes is never considered significant. It is simply the normal whitespace allowed by XQuery syntax. In the ul constructor, the spaces between the left curly brace and the li start tag fall into this category. It is not technically considered boundary whitespace, and it is always discarded. Using an xml:space attribute on a direct element constructor has no effect on the treatment of boundary whitespace.

There is no boundary whitespace in attribute values. For example, in the expression:

<product dept="    {$d}     "/>

the whitespace between the quotes and the enclosed expression is considered significant and therefore is preserved. The expression:

<product dept="{    $d     }"/>

has no boundary whitespace either, only whitespace in an enclosed expression. This whitespace is not preserved. Line breaks are never preserved in attribute values; they are converted to spaces. This is a standard feature of XML itself, known as attribute value normalization.

The boundary-space declaration

By default, a query processor discards all boundary whitespace. Sometimes you want to preserve the boundary whitespace in your query results because it is significant. The boundary-space declaration, specified in the query prolog, instructs the processor how to handle boundary whitespace in direct element constructors. Its syntax is shown in Figure 5-1.

Figure 5-1. Syntax of a boundary-space declaration

The two valid values are:

preserve

This value results in boundary whitespace being preserved.

strip

This value results in boundary whitespace being deleted.

The default is strip. For example, the boundary-space declaration:

declare boundary-space preserve;

causes whitespace to be preserved. With this boundary-space declaration, the result of the constructor in Example 5-12 becomes:

<ul>
  <li>  <b> number:</b> <number>557</number>  </li>
</ul>

Table 5-1 shows some additional examples of results with and without preserved whitespace.

<e>
  <c></c>
</e>

<e>
  <c></c>
</e>

<e><c></c></e>

<e> {"x"} </e>

<e> x </e>

<e>x</e>

<e> {()} </e>

<e> </e>

<e></e>

<e>{"x"} {"y"}</e>

<e>x y</e>

<e>xy</e>

<e> x {"y"}</e>

<e> x y</e>

<e> x y</e>

<e>{" x "}</e>

<e> x </e>

<e> x </e>

<e>{ "x" }</e>

<e>x</e>

<e>x</e>

<e> &#x20; {"x"}</e>

<e>   x</e>

<e>   x</e>

<e> </e>

<e> </e>

<e></e>

Forcing boundary whitespace preservation

If you don’t want to preserve all whitespace but wish to preserve it in one or more specific elements, you can do this in one of two ways. The first way is to include an enclosed expression that evaluates to whitespace. For example, <e>{" x "}</e> evaluates to <e> x </e>, regardless of the boundary-space declaration. This is because the whitespace is part of the value of the expression (the literal string).

Another method is to use a character reference to a whitespace character. Whitespace that is the result of a character reference is always considered significant. For example, <e> &#x20; {"x"}</e> always evaluates to <e>   x</e>. Character references are described further in “XML Entity and Character References”.

Names of computed element constructors

The name in a computed element constructor is represented by either a qualified name or an expression (in curly braces) that evaluates to a qualified name. This is then followed by an enclosed expression (also in curly braces) that contains the content of the element. For example, the constructor:

element h1 { "Product Catalog" }

uses a literal name to construct the element <h1>Product Catalog</h1>, while:

element {concat("h", $level)}  { "Product Catalog" }

uses an expression, enclosed in curly braces, to dynamically generate the name by concatenating the literal h with a variable value.

You could also copy the name of the new node from an existing node, using the node-name function. For example:

element {node-name($myNode)}  { "contents" }

will give the new element the same name as the node that is bound to the $myNode variable.

The expression used for the name can be untyped, or it can be either an xs:QName (which is what node-name returns) or an xs:string value. It can even be a node, in which case it is atomized to extract its typed value (not its name).

Default namespace declarations apply to element constructors. If you do not prefix your names, and you declare a default element namespace (e.g., in an outer expression or in the query prolog), the new elements are considered to be in that namespace.

Content of computed element constructors

After the name, the next part of the computed element constructor is an enclosed expression that contains the contents of the element, including attributes, character data, and child elements. As with direct XML constructors, any elements returned by the enclosed expression become children of the new element, attributes become attributes, and atomic values become character data content. Computed constructors have the same rule that the attributes must appear before any elements or character data.

The syntax is slightly different for computed constructors in that there can only be one pair of curly braces, containing the attributes and contents of the element. If several expressions are needed for the attributes, child elements, and character data content, they are separated by commas. For example, when using a direct element constructor, you can construct the li element this way:

<li>number: {data($prod/number)} , name: {data($prod/name)}</li>

where you intersperse literal text and enclosed expressions. To create an identical li element using a computed constructor, you would use the syntax:

element li {"number:", data($prod/number), ", name:", data($prod/name)}

Note that the literal text is in quotes and is separated from the expressions by commas. Also, the expressions, such as data($prod/number), are not themselves enclosed in curly braces as they were with the direct constructor.

The values of each of the four expressions in the li constructor will be separated by spaces in the results. If you do not wish to have those spaces in the results, you can use the concat function to concatenate the values together, as in:

element li {concat("number:", data($prod/number), ", name:", data($prod/name))}

If you want the constructed element to be empty, you can put nothing between the curly braces (as in { }), but the braces are still required.