← Back to branch summary

~zorba-coders/zorba/web-try.zorba-xquery.com

« back to all changes in this revision

Viewing changes to try.zorba-xquery.com/public/xqdoc/modules/www.zorba-xquery.com_modules_store_dynamic_collections_dml.xq

  • Committer: Cezar Andrei
  • Date: 2012-01-25 18:11:39 UTC
  • Revision ID: cezar.lp@cezarandrei.com-20120125181139-0734dukmgca39dwg
Initial try.zorba-xquery.com ruby app.

Show diffs side-by-side

added added

removed removed

Lines of Context:
try.zorba-xquery.com/public/xqdoc/modules/www.zorba-xquery.com_modules_store_dynamic_collections_dml.xq
 
1
xquery version "3.0";
 
2
 
 
3
(:
 
4
 : Copyright 2006-2009 The FLWOR Foundation.
 
5
 :
 
6
 : Licensed under the Apache License, Version 2.0 (the "License");
 
7
 : you may not use this file except in compliance with the License.
 
8
 : You may obtain a copy of the License at
 
9
 :
 
10
 : http://www.apache.org/licenses/LICENSE-2.0
 
11
 :
 
12
 : Unless required by applicable law or agreed to in writing, software
 
13
 : distributed under the License is distributed on an "AS IS" BASIS,
 
14
 : WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 
15
 : See the License for the specific language governing permissions and
 
16
 : limitations under the License.
 
17
:)
 
18
 
 
19
(:~
 
20
 : This modules provides a set of functions to modify a collection and retrieve the nodes
 
21
 : contained in a particular collection.
 
22
 :
 
23
 : Such collections are identified by QNames and come into existence (i.e. be made available)
 
24
 : by calling one of the two create-collection functions of the 
 
25
 : <tt>http://www.zorba-xquery.com/modules/store/dynamic/collections/ddl</tt>
 
26
 : module.
 
27
 :
 
28
 : The variable $content passed to any of the insert functions is evaluated
 
29
 : as though it were an enclosed expression in an element constructor.
 
30
 : The result of this step is a sequence of nodes to be inserted into the collection.
 
31
 :
 
32
 : In contrast to the functions in the module
 
33
 : <tt>http://www.zorba-xquery.com/modules/store/static/collections/dml</tt>
 
34
 : the function in this module operate on collections which do not have to
 
35
 : be statically declared in the prolog.
 
36
 :
 
37
 : @see http://www.zorba-xquery.com/modules/store/dynamic/collections/ddl
 
38
 : @see http://www.zorba-xquery.com/modules/store/static/collections/ddl
 
39
 :
 
40
 : @author Matthias Brantner, David Graf, Till Westmann, Markos Zaharioudakis
 
41
 : @project store/collections/dynamic
 
42
 :
 
43
 : @project store/collections/dynamic
 
44
 :)
 
45
module namespace dml = "http://www.zorba-xquery.com/modules/store/dynamic/collections/dml";
 
46
 
 
47
declare namespace ann = "http://www.zorba-xquery.com/annotations";
 
48
 
 
49
declare namespace ver = "http://www.zorba-xquery.com/options/versioning";
 
50
declare option ver:module-version "2.0";
 
51
 
 
52
(:~
 
53
 : The insert-nodes-first function is an updating function that inserts copies of the
 
54
 : given nodes at the beginning of the collection.
 
55
 :
 
56
 : @param $name The name of the collection to which the nodes should be added.
 
57
 : @param $content The sequences of nodes whose copies should be added to the collection.
 
58
 :
 
59
 : @return The result of the function is an empty XDM instance and a pending update list
 
60
 :         which, once applied, inserts the nodes into the collection.
 
61
 :
 
62
 : @error XDDY0003 if the collection identified by $name is not available.
 
63
 :
 
64
 :)
 
65
declare updating function dml:insert-nodes-first(
 
66
  $name as xs:QName,
 
67
  $content as node()*) external;
 
68
 
 
69
(:~
 
70
 : The insert-nodes-last function is an updating function that inserts copies of the
 
71
 : given nodes at the end of the collection.
 
72
 :
 
73
 : @param $name The name of the collection to which the nodes should  be added.
 
74
 : @param $content The sequences of nodes whose copies should be added to the collection.
 
75
 :
 
76
 : @return The result of the function is an empty XDM instance and a pending update list
 
77
 :         which, once applied, inserts the nodes into the collection.
 
78
 :
 
79
 : @error XDDY0003 if the collection identified by $name is not available.
 
80
 :
 
81
 :)
 
82
declare updating function dml:insert-nodes-last(
 
83
  $name as xs:QName,
 
84
  $content as node()*) external;
 
85
 
 
86
(:~
 
87
 : The insert-nodes-before function is an updating function that inserts
 
88
 : copies of the given nodes into a collection at the position directly preceding the
 
89
 : given target node.
 
90
 :
 
91
 : @param $name The name of the collection to which the nodes should  be added.
 
92
 : @param $target The node in the collection before which the $content
 
93
 :        sequence should be inserted.
 
94
 : @param $content The sequences of nodes whose copies should be added to the collection.
 
95
 :
 
96
 : @return The result of the function is an empty XDM instance and a pending update list
 
97
 :         which, once applied, inserts the nodes into the collection.
 
98
 :
 
99
 : @error XDDY0003 if the collection identified by $name is not available.
 
100
 : @error XDDY0011 if the target node is not contained in the collection.
 
101
 :
 
102
 :)
 
103
declare updating function dml:insert-nodes-before(
 
104
  $name as xs:QName,
 
105
  $target as node(),
 
106
  $content as node()*) external;
 
107
 
 
108
(:~
 
109
 : The insert-nodes-after function is an updating function that inserts
 
110
 : copies of the given nodes into a collection at the position directly following the
 
111
 : given target node.
 
112
 :
 
113
 : @param $name The name of the collection to which the nodes should be added.
 
114
 : @param $target The node in the collection after which the $content
 
115
 :        sequence should be inserted.
 
116
 : @param $content The sequences of nodes whose copies should be added to the collection.
 
117
 :
 
118
 : @return The result of the function is an empty XDM instance and a pending update list
 
119
 :         which, once applied, inserts the nodes into the collection.
 
120
 :
 
121
 : @error XDDY0003 if the collection identified by $name is not available.
 
122
 : @error XDDY0011 if the target node is not contained in the collection.
 
123
 :
 
124
 :)
 
125
declare updating function dml:insert-nodes-after(
 
126
  $name as xs:QName,
 
127
  $pos as node(),
 
128
  $content as node()*) external;
 
129
 
 
130
(:~
 
131
 : This function does the same as the insert-nodes function except
 
132
 : it immediately applies the resulting pending updates and returns the
 
133
 : nodes that have been inserted.
 
134
 :
 
135
 : @param $name The name of the collection to which the nodes should be added.
 
136
 : @param $content The sequences of nodes whose copies should be added to the collection.
 
137
 :
 
138
 : @return The result of the function is the sequence of nodes that have been
 
139
 :         inserted into the collection.
 
140
 :
 
141
 : @error XDDY0003 if the collection identified by $name is not available.
 
142
 :
 
143
 : @see dml:insert-nodes-first
 
144
 :
 
145
 :)
 
146
declare %ann:sequential function dml:apply-insert-nodes-first(
 
147
  $name as xs:QName,
 
148
  $content as node()*) as node()* external;
 
149
 
 
150
(:~
 
151
 : This function does the same as the insert-nodes-last function except
 
152
 : it immediately applies the resulting pending updates and returns the
 
153
 : nodes that have been inserted.
 
154
 :
 
155
 : @param $name The name of the collection to which the nodes should be added.
 
156
 : @param $content The sequences of nodes whose copies should be added to the collection.
 
157
 :
 
158
 : @return The result of the function is the sequence of nodes that have been
 
159
 :         inserted into the collection.
 
160
 :
 
161
 : @error XDDY0003 if the collection identified by $name is not available.
 
162
 :
 
163
 : @see dml:insert-nodes-last
 
164
 :
 
165
 :)
 
166
declare %ann:sequential function dml:apply-insert-nodes-last(
 
167
  $name as xs:QName,
 
168
  $content as node()*) as node()* external;
 
169
 
 
170
(:~
 
171
 : This function does the same as the insert-nodes-before function except
 
172
 : it immediately applies the resulting pending updates and returns the
 
173
 : nodes that have been inserted.
 
174
 :
 
175
 : @param $name The name of the collection to which the nodes should be added.
 
176
 : @param $target The node in the collection before which the $content
 
177
 :        sequence should be inserted.
 
178
 : @param $content The sequences of nodes whose copies should be added to the collection.
 
179
 :
 
180
 : @return The result of the function is the sequence of nodes that have been
 
181
 :         inserted into the collection.
 
182
 :
 
183
 : @error XDDY0003 if the collection identified by $name is not available.
 
184
 :
 
185
 : @see dml:insert-nodes-before
 
186
 :
 
187
 :)
 
188
declare %ann:sequential function dml:apply-insert-nodes-before(
 
189
  $name as xs:QName,
 
190
  $target as node(),
 
191
  $content as node()*) as node()* external;
 
192
 
 
193
(:~
 
194
 : This function does the same as the insert-nodes-after function except
 
195
 : it immediately applies the resulting pending updates and returns the
 
196
 : nodes that have been inserted.
 
197
 :
 
198
 : @param $name The name of the collection to which the nodes should be added.
 
199
 : @param $target The node in the collection after which the $content
 
200
 :        sequence should be inserted.
 
201
 : @param $content The sequences of nodes whose copies should be added to the collection.
 
202
 :
 
203
 : @return The result of the function is the sequence of nodes that have been
 
204
 :         inserted into the collection.
 
205
 :
 
206
 : @error XDDY0003 if the collection identified by $name is not available.
 
207
 :
 
208
 : @see dml:insert-nodes-after
 
209
 :
 
210
 :)
 
211
declare %ann:sequential function dml:apply-insert-nodes-after(
 
212
  $name as xs:QName,
 
213
  $pos as node(),
 
214
  $content as node()*) as node()* external;
 
215
 
 
216
(:~
 
217
 : The delete-nodes function is an updating function that deletes zero of more
 
218
 : nodes from a collection. 
 
219
 :
 
220
 : @param $target the nodes in the collection that should be deleted.
 
221
 :
 
222
 : @return The result of this function is an empty XDM instance and a pending update
 
223
 :         list which, once applied, deletes the nodes from their collections.
 
224
 :
 
225
 : @error XDDY0011 if any nodes in the $target sequence is not a member of a collection
 
226
 :        or not all nodes of the $target sequence belong to the same collection.
 
227
 :
 
228
 :)
 
229
declare updating function dml:delete-nodes($target as node()*) external;
 
230
 
 
231
(:~
 
232
 : The delete-node-first function is an updating function that deletes the
 
233
 : first node from a collection.
 
234
 :
 
235
 : @param $name The name of the collection from which the first node should be deleted.
 
236
 :
 
237
 : @return The result of this function is an empty XDM instance and a pending update
 
238
 :         list which, once applied, deletes the first node from the collection.
 
239
 :
 
240
 : @error XDDY0011 if the collection doesn't contain any node.
 
241
 :
 
242
 :)
 
243
declare updating function dml:delete-node-first($name as xs:QName) external;
 
244
 
 
245
(:~
 
246
 : The delete-nodes-first function is an updating function that deletes the
 
247
 : first n nodes from a collection.
 
248
 :
 
249
 : @param $name The name of the collection from which the first node should be deleted.
 
250
 : @param $number The number of nodes that should be removed from the beginning of
 
251
 :        the collection.
 
252
 :
 
253
 : @return The result of this function is an empty XDM instance and a pending update
 
254
 :         list which, once applied, deletes the nodes from the collection.
 
255
 :
 
256
 : @error XDDY0011 if the collection doesn't contain the given number of nodes.
 
257
 :
 
258
 :)
 
259
declare updating function dml:delete-nodes-first(
 
260
  $name as xs:QName,
 
261
  $number as xs:integer) external;
 
262
 
 
263
(:~
 
264
 : The delete-node-last function is an updating function that deletes the
 
265
 : last node from a collection.
 
266
 :
 
267
 : @param $name The name of the collection from which the first node should be deleted.
 
268
 :
 
269
 : @return The result of this function is an empty XDM instance and a pending update
 
270
 :         list which, once applied, deletes the last node from the collection.
 
271
 :
 
272
 : @error XDDY0009 If available collections does not provide a mapping
 
273
 :        for the expanded QName $name.
 
274
 : @error XDDY0011 if the collection doesn't contain any node.
 
275
 :
 
276
 :)
 
277
declare updating function dml:delete-node-last($name as xs:QName) external;
 
278
 
 
279
 
 
280
(:~
 
281
 : The delete-nodes-last function is an updating function that deletes the
 
282
 : last n nodes from an ordered collection.
 
283
 :
 
284
 : @param $name The name of the collection from which the first node should be deleted.
 
285
 : @param $number The number of nodes to delete.
 
286
 :
 
287
 : @return The result of this function is an empty XDM instance and a pending update
 
288
 :         list which, once applied, deletes the last n nodes.
 
289
 :
 
290
 : @error XDDY0009 If available collections does not provide a mapping
 
291
 :        for the expanded QName $name.
 
292
 : @error XDDY0011 if the collection doesn't contain the given number of nodes.
 
293
 :
 
294
 :)
 
295
declare updating function dml:delete-nodes-last(
 
296
  $name as xs:QName,
 
297
  $number as xs:integer) external;
 
298
 
 
299
(:~
 
300
 : The index-of function return the index of the given node in the collection.
 
301
 :
 
302
 : @param $node The node to retrieve the index from.
 
303
 :
 
304
 : @return Returns the position as xs:integer of the given node in the collection.
 
305
 :
 
306
 : @error XDDY0011 if node is not contained in any collection.
 
307
 :
 
308
 :)
 
309
declare function dml:index-of($node as node()) as xs:integer external;
 
310
 
 
311
(:~
 
312
 : The collection function returns the sequence of nodes of the collection
 
313
 : identified by the given name.
 
314
 :
 
315
 : @param $name The name of the collection.
 
316
 :
 
317
 : @return The sequence contained in the given collection.
 
318
 :
 
319
 : @error XDDY0009 If available collections does not provide a mapping
 
320
 :        for the expanded QName $name.
 
321
 :
 
322
 :)
 
323
declare function dml:collection($name as xs:QName) as node()* external;
 
324
 
 
325
(:~
 
326
 : This function returns the name of the collection the given node belongs
 
327
 : to.
 
328
 :
 
329
 : @param $node The node for which to get the name of the collection
 
330
 : @return The result of this function is a QName which identifies the collection
 
331
 :         to which the given node belongs to.
 
332
 :
 
333
 : @error XDDY0011 if the given node does not belong to a collection.
 
334
 :
 
335
 :)
 
336
declare function dml:collection-name($node as node()) as xs:QName external;