1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2018 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-->
<refentry id="xpf_create_element">
<refmeta>
<refentrytitle>create-element</refentrytitle>
<refmiscinfo>XPATH</refmiscinfo>
</refmeta>
<refnamediv>
<refname>create-element</refname>
<refpurpose>Creates an element with specified name, attributes and children</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="xpf_syn_create_element">
<funcprototype id="xpf_proto_create_element">
<funcdef>node <function>create-element</function></funcdef>
<paramdef><parameter>head</parameter> sequence</paramdef>
<paramdef><parameter>child1</parameter> any</paramdef>
<paramdef><parameter>child2</parameter> any</paramdef>
<paramdef><parameter>...</parameter></paramdef>
<paramdef><parameter>childN</parameter> any</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="xpf_desc_create_element"><title>Description</title>
<para>
This is an internal XQUERY function and you will probably never need to
call it explicitly. It is not a part of library of standard XQUERY 1.0
functions.
</para>
<para>
This function creates a new "XML Tree" element whose name is a string-value of the first
item of <parameter>head</parameter> sequence, with attributes and children
specified by the rest of <parameter>head</parameter> sequence and by the list of
arguments <parameter>child1</parameter>, <parameter>child2</parameter>, ...
<parameter>childN</parameter>.
</para>
First of all, a new element will be created, without attributes or children.
The name of element will be taken from the first item of the
<parameter>head</parameter> sequence.
Then attributes will be created from the second and third items of <parameter>head</parameter>,
from fourth and fifth and so on. In every pair of items will specify name and
value of some attribute. Non-string items will be converted to strings first.
It is an error to specify the same attribute name twice in
<parameter>head</parameter> sequence.
<para>
</para>
When the "opening tag" of the element is prepared, children are
added, in the same order as they are specified by
arguments <parameter>child1</parameter>, <parameter>child2</parameter>, ...
<parameter>childN</parameter>.
If the value of some argument is a sequences (e.g. a node-set),
items of the sequence are added as separate children in the same order as
they are in the sequence.
Nodes are added "as-is", numbers, strings and
other "scalar" values are converted to strings first and these strings
are converted into PCDATA (text) children.
<para>
</para>
"Attribute descriptor" objects are not converted to children elements;
if descriptor item is found, one attribute in the opening tag of the
created element is added or changed and the descriptor is removed from
the list of children.
<para>
</para>
When all children are prepared, some normalization is performed.
If there are two or more adjacent PCDATA (text) children, they are replaced
with one PCDATA children whose text is a concatenation of
texts of all that children.
<para>
</para>
</refsect1>
<refsect1 id="xpf_params_create_element"><title>Parameters</title>
<refsect2><title>head</title>
<para>Name of the element or a sequence of name and attributes of the element.</para></refsect2>
<refsect2><title>childI</title>
<para>Children node or sequence of children node.</para></refsect2>
</refsect1>
<refsect1 id="xpf_ret_create_element"><title>Return Types</title><para>Node</para></refsect1>
<refsect1 id="xpf_errors_create_element"><title>Errors</title>
<table><title>Errors signalled by</title>
<tgroup cols="4">
<thead><row><entry>SQLState</entry><entry>Error Code</entry><entry>Error Text</entry><entry>Description</entry></row></thead>
<tbody>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPFC0</errorcode></entry>
<entry><errorname>At least one argument (name of element to be created) must be passed to create-element XPATH function.</errorname></entry>
<entry>create-element is called without arguments.</entry>
</row>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPFC1</errorcode></entry>
<entry><errorname>No name of element in the first argument of create-element XPATH function.</errorname></entry>
<entry>The <parameter>head</parameter> sequence is empty.</entry>
</row>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPFC2</errorcode></entry>
<entry><errorname>Last attribute has no value specified in the first argument of create-element XPATH function.</errorname></entry>
<entry>The <parameter>head</parameter> sequence is of even length.</entry>
</row>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPFC3</errorcode></entry>
<entry><errorname>Unsupported type of element of the first argument of create-element XPATH function.</errorname></entry>
<entry>Current version may create name and attributes of elements only from strings, entities and numbers.</entry>
</row>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPFC4</errorcode></entry>
<entry><errorname>Duplicate attribute names in first argument of create-element XPATH function.</errorname></entry>
<entry>Duplicate attribute names may appear in attribute descriptors but not in the <parameter>head</parameter> argument.</entry>
</row>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPFC5</errorcode></entry>
<entry><errorname>First argument of create-element XPATH function must be string, symbol or sequence of them.</errorname></entry>
<entry>The function was unable to prepare name of element.</entry>
</row>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPFC6</errorcode></entry>
<entry><errorname>Error in XPATH user extension function or internal error: sequence argument is not flat in create-element XPATH function.</errorname></entry>
<entry>A value of XQUERY "sequence" type should not contain other sequences as its items, i.e. it must be "flat".</entry>
</row>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPFC7</errorcode></entry>
<entry><errorname>Invalid special entity found in argument of create-element XPATH function.</errorname></entry>
<entry>An invalid object (probably built by XPATH extension function) is specified as child entity.</entry>
</row>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPFCA</errorcode></entry>
<entry><errorname>Persistent XML entities are not fully supported by create-element XPATH function.</errorname></entry>
<entry>The function creates "XML Tree" element, "Persistent XML" entity can not become a children of "XML Tree".</entry>
</row>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPFCB</errorcode></entry>
<entry><errorname>Unsupported type of argument in create-element XPATH function.</errorname></entry>
<entry>Some argument or some item of an argument may not be converted to a string or a node, so a children may not be created.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1 id="xpf_examples_create_element"><title>Examples</title>
<example id="xpf_ex_create_element"><title></title>
<para>Two following XQUERY expressions are equivalent:</para>
<screen><![CDATA[
<H1>{'Hello, '}<B>{'world'}</B></H1>
create-element('H1', 'Hello, ', create-element('B', 'world'))
]]></screen>
</example>
</refsect1>
<refsect1 id="xpf_seealso_create_element"><title>See Also</title>
<para><link linkend="xpf_create_attribute">create-attribute()</link></para>
<para><link linkend="xpf_create_comment">create-comment()</link></para>
<para><link linkend="xpf_create_pi">create-pi()</link></para>
</refsect1>
</refentry>
|
