Direct element constructors

Direct element constructors use an XML-like notation to create element nodes. The constructed node can be a simple element or a complex element that contains attributes, text content, and nested elements.

The result of a direct element constructor is a new element node that has its own node identity. All of the attribute and descendant nodes of the new element node are also new nodes that have their own identities.

Syntax

Namespace declaration attribute

ElementName: A QName that represents the name of the element to construct. The name that is used for ElementName in the end tag must exactly match the name that is used in the corresponding start tag, including the prefix or absence of a prefix. If ElementName includes a namespace prefix, the prefix is resolved to a namespace URI by using the statically known namespaces. If ElementName has no namespace prefix, the name is implicitly qualified by the default element/type namespace. The expanded QName that results from evaluating ElementName becomes the name of the constructed element node.

AttributeName: A QName that represents the name of the attribute to construct. If AttributeName includes a namespace prefix, the prefix is resolved to a namespace URI by using the statically known namespaces. If AttributeName has no namespace prefix, the attribute is in no namespace. The expanded QName that results from evaluating AttributeName becomes the name of the constructed attribute node. The expanded QName of each attribute must be unique, or the expression results in a error.
Each attribute in a direct element constructor creates a new attribute node, with its own node identity. The parent of the new attribute node is the constructed element node. The new attribute node is given a type annotation of xdt:untypedAtomic.

AttributeValue

A string of characters that specify a value for the attribute. The attribute value can contain enclosed expressions (expressions that are enclosed in curly braces) that are evaluated and replaced by their value when the element constructor is processed. Predefined entity references and character references are also valid and get replaced by the characters that they represent. The following table lists special characters that are valid within AttributeValue, but must be represented by double characters or an entity reference.

Table 1. Representation of special characters in attribute values
Character	Representation required in attribute values
{	two open curly braces ({{)
}	two closed curly braces (}})
<	<
&	&
"	" or two double quotation marks ("")
'	' or two single quotation marks ('')

xmlns

The word that begins a namespace declaration attribute. When specified as a prefix in a QName, xmlns indicates that the value of prefixToBind will be bound to the URI that is specified by URILiteral. This namespace binding is added to the statically-known namespaces for this constructor expression and for all of the expressions that are nested inside of the expression (unless the binding is overridden by a nested namespace declaration attribute). In the following example, the namespace declaration attribute xmlns:metric = "http://example.org/metric/units" binds the prefix metric to the namespace http://example.org/metric/units.

When specified as the complete QName with no prefix, xmlns indicates that the default element/type namespace is set to the value of URILiteral. This default element/type namespace is in effect for this constructor expression and for all expressions that are nested inside of the constructor expression (unless the declaration is overridden by a nested namespace declaration attribute). In the following example, the namespace declaration attribute xmlns = "http://example.org/animals" sets the default element/type namespace to http://example.org/animals.

prefixToBind

The prefix to be bound to the URI that is specified for URILiteral. The value of prefixToBind cannot be xml or xmlns. Specifying either of these values results in an error.

URILiteral

A string literal (a sequence of zero or more characters that is enclosed in single quotation marks or double quotation marks) that represents a URI. The string literal value must be a valid URI. The value of URILiteral can be a zero-length string only when the namespace declaration attribute is being used to set the default element/type namespace. Otherwise, specifying a zero-length string for URILiteral results in an error.

ElementContent

The content of the direct element constructor. The content consists of everything between the start tag and end tag of the constructor. How boundary space is handled within element constructors is controlled by the boundary-space declaration in the prolog. The resulting content sequence is a concatenation of the content entities. Any resulting adjacent text characters, including text resulting from enclosed expressions, are merged into a single text node. Any resulting attribute nodes must come before any other content in the resulting content sequence.

ElementContent can consist of any of the following content:

Text characters. Text characters create text nodes and adjacent text nodes are merged into a single text node. Line endings within sequences of characters are normalized according to the rules for end-of-line handling that are specified for XML 1.0. The following table lists special characters that are valid within ElementContent, but must be represented by double characters or an entity reference.

Table 2. Representation of special characters in element content
Character	Representation required in element content
{	two open curly braces ({{)
}	two closed curly braces (}})
<	<
&	&

Nested direct constructors.
CDataSections. CDataSections are specified using the following syntax: <![CDATA[contents]]> where contents consists of a series of characters. The characters that are specified for contents, including special characters such as < and &, are treated as literal characters rather than as delimiters. The sequence ]]> terminates the CDataSection and is therefore not allowed within contents.
Character references and predefined entity references. During processing, predefined entity references and character references are expanded into their referenced strings.
Enclosed expressions. An enclosed expression is an XQuery expression that is enclosed in curly braces. For example, {5 + 7} is an enclosed expression. The value of an enclosed expression can be any sequence of nodes and atomic values. Enclosed expressions can be used within the content of a direct element constructor to compute both the content and the attributes of the constructed node. For each node that is returned by an enclosed expression, a new copy is made of the node and all of its descendants, which retain their original type annotations. Any attribute nodes that are returned by ElementContent must be at the beginning of the resulting content sequence; these attribute nodes become attributes of the constructed element. Any element, content, or processing instruction nodes that are returned by ElementContent become children of the newly constructed node. Any atomic values that are returned by ElementContent are converted to strings and stored in text nodes, which become children of the constructed node. Adjacent text nodes are merged into a single text node.

Examples

The following direct element constructor creates a book element. The book element contains complex content that includes an attribute node, some nested element nodes, and some text nodes:
```
<book isbn="isbn-0060229357">
    <title>Harold and the Purple Crayon</title>
    <author>
        <first>Crockett</first>
        <last>Johnson</last>
    </author>
</book>
```
The following examples demonstrate how element content is processed in direct element constructors:
- The following expression constructs an element node that has one child, a text node that contains the value "1":
```
<a>{1}</a>
```
- The following expression constructs an element node that has one child, a text node that contains the value "1 2 3":
```
<a>{1, 2, 3}</a>
```
- The following expression constructs an element node that has one child, a text node that contains the value "123":
```
<c>{1}{2}{3}</c>
```
- The following expression constructs an element node that has one child, a text node that contains the value "1 2 3":
```
<b>{1, "2", "3"}</b>
```
- The following expression constructs an element node that has one child, a text node that contains the value "I saw 8 cats.":
```
<fact>I saw 8 cats.</fact>
```
- The following expression constructs an element node that has one child, a text node that contains the value "I saw 8 cats."
```
<fact>I saw {5 + 3} cats.</fact>
```
- The following expression constructs an element node that has three children: a text node that contains "I saw ", a child element node that is named howmany, and a text node that contains " cats." The child element node has a single child, a text node that contains the value "8".
```
<fact>I saw <howmany>{5 + 3}</howmany> cats.</fact>
```