← Back to branch summary

~zorba-coders/zorba/bug1151967

« back to all changes in this revision

Viewing changes to modules/zorba-query/zorba-query.xq

  • Committer: Paul J. Lucas
  • Date: 2013-08-15 00:14:17 UTC
  • mfrom: (11597 lp_zorba)
  • mto: This revision was merged to the branch mainline in revision 11598.
  • Revision ID: paul@lucasmail.org-20130815001417-g22x9plxc8fv73zd
Merge from trunk.

Show diffs side-by-side

added added

removed removed

Lines of Context:
modules/zorba-query/zorba-query.xq
16
16
:)
17
17
 
18
18
(:~
19
 
 : This module contains functions to compile and evaluate XQuery
20
 
 : programs. Also, it contains function that allow to parameterize
21
 
 : the static or dynamic evaluation phase.
 
19
 : This module contains functions to compile and evaluate queries
 
20
 : written in either JSONiq or XQuery. Also, it contains function that
 
21
 : allow to parameterize the static or dynamic evaluation phase.
22
22
 :
23
23
 : @author Juan Zacarias
24
 
 : @project Zorba/Programming Languages/XQXQ
 
24
 : @project Zorba/Programming Languages/ZQ
25
25
 :)
26
 
module namespace xqxq = 'http://www.zorba-xquery.com/modules/xqxq';
 
26
module namespace zq = 'http://zorba.io/modules/zorba-query';
27
27
 
28
28
declare namespace an = "http://zorba.io/annotations";
29
29
declare namespace ver = "http://zorba.io/options/versioning";
30
30
declare namespace op = "http://zorba.io/options/features";
31
31
declare namespace f = "http://zorba.io/features";
32
32
 
33
 
declare option ver:module-version "2.0";
 
33
declare option ver:module-version "1.0";
34
34
 
35
35
(:~
36
 
 : The function prepares a given XQuery program for execution.
37
 
 : If the program was successfully compiled, the function returns an
 
36
 : <p>The function prepares a given a query for execution.</p>
 
37
 : <p>If the query was successfully compiled, the function returns an
38
38
 : identifier as xs:anyURI. This URI can be passed to other functions
39
 
 : of this module (e.g. to actually evaluate the program). The URI
40
 
 : is opaque and its lilfetime is bound by the lifetime of the XQuery
41
 
 : program that invoked this function. Further reference or uses
42
 
 : of the identifier lead to unexpected results.
43
 
 :
44
 
 : Successfully prepared queries need to be deleted by passing the resulting
45
 
 : identifier to the xqxq:delete-query function of this module.
46
 
 :
47
 
 : @param $main-module-text the XQuery program that should be prepared.
48
 
 :   The program needs to be a XQuery main module.
49
 
 :
50
 
 : @return an identifier for the compiled program that can be passed
 
39
 : of this module (e.g. to actually evaluate the query). The URI
 
40
 : is opaque and its lifetime is bound by the lifetime of the query
 
41
 : that invoked this function. Further reference or uses
 
42
 : of the identifier lead to unexpected results.</p>
 
43
 : <p/>
 
44
 : <p>Successfully prepared queries need to be deleted by passing the resulting
 
45
 : identifier to the zq:delete-query function of this module.</p>
 
46
 :
 
47
 : @param $main-module-text the query that should be prepared.
 
48
 :   The query needs to be a XQuery or JSONiq main module.
 
49
 :
 
50
 : @return an identifier for the compiled query that can be passed
51
51
 :   as arguments to other functions of this module.
52
52
 :
53
53
 : @error any (static or type) error that may be raised during the compilation
54
 
 : of the query. For example, err:XPST0003 if the given XQuery program could
 
54
 : of the query. For example, err:XPST0003 if the given query could
55
55
 : not be parsed.
56
56
 :)
57
 
declare %an:sequential function xqxq:prepare-main-module($main-module-text as xs:string) as 
 
57
declare %an:sequential function zq:prepare-main-module($main-module-text as xs:string) as 
58
58
  xs:anyURI external;
59
59
 
60
60
(:~
61
 
 : The function prepares a given XQuery program for execution.
62
 
 : If the program was successfully compiled, the function returns an
 
61
 : <p>The function prepares a given query for execution.</p>
 
62
 : <p>If the query was successfully compiled, the function returns an
63
63
 : identifier as xs:anyURI. This URI can be passed to other functions
64
 
 : of this module (e.g. to actually evaluate the program). The URI
65
 
 : is opaque and its lilfetime is bound by the lifetime of the XQuery
66
 
 : program that invoked this function. Further reference or uses
67
 
 : of the identifier lead to unexpected results.
68
 
 : 
69
 
 : Important notes regarding the second and third parameters of the function:
70
 
 : --------------------------------------------------------------------------
71
 
 :
72
 
 : These parameters allow you to specify a URL resolver and a URI mapper
 
64
 : of this module (e.g. to actually evaluate the query). The URI
 
65
 : is opaque and its lifetime is bound by the lifetime of the query
 
66
 : that invoked this function. Further reference or uses
 
67
 : of the identifier lead to unexpected results.</p>
 
68
 : <p/>
 
69
 : <p>Important notes regarding the second and third parameters of the function:</p>
 
70
 : <p>--------------------------------------------------------------------------</p>
 
71
 : <p/>
 
72
 : <p>These parameters allow you to specify a URL resolver and a URI mapper
73
73
 : for Zorba to use when executing this query. See
74
 
 : http://www.zorba-xquery.com/html/documentation/2.7.0/zorba/uriresolvers
75
 
 :
76
 
 : The second parameter is a function item for a URL
 
74
 : <a href="http://www.zorba-xquery.com/html/documentation/2.7.0/zorba/uriresolvers">here</a></p>
 
75
 : <p/>
 
76
 : <ul>The second parameter is a function item for a URL
77
77
 : resolver. The URL resolver function must recive 2 parameters:
78
 
 :   A $namespace as xs:string that will contain the url to be resolved.
79
 
 :   A $entity as xs:string that will contain the type of resolving needed;
80
 
 :   this can be 2 values "module" and "schema".
81
 
 : The function must return an empty sequence when the specified $namespace
82
 
 : or $entity are not the ones to be resolved.
83
 
 :
84
 
 : Example:
85
 
 :   
86
 
 : declare function mymod:url-resolver($namespace as xs:string, $entity as xs:string)
 
78
 : <li>A $namespace as xs:string that will contain the url to be resolved.</li>
 
79
 : <li>A $entity as xs:string that will contain the type of resolving needed.
 
80
 :   This can be one of two values: "module" or "schema".</li>
 
81
 : </ul>
 
82
 : <p>The function must return the empty sequence when the specified $namespace
 
83
 : or $entity are not the ones to be resolved.</p>
 
84
 : <p/>
 
85
 : <p>Example:</p>
 
86
 : <p/>  
 
87
 : <code>declare function mymod:url-resolver($namespace as xs:string, $entity as xs:string) as item()?
87
88
 : {
88
89
 :  if($namespace = 'http://test.xq')
89
90
 :  then "module namespace test = 'http://test'; declare function test:foo(){'foo'};"
90
91
 :  else ()
91
 
 : };
92
 
 :
93
 
 : The URL resolver function's namespace, name, and parameter naming are
94
 
 : not restricted by XQXQ.
95
 
 :
96
 
 : The URL resolver function's return type is not restricted, it could be a string, a sequence,
97
 
 : a node, etc. All the outputs types are to be serialized as a string.
98
 
 :
99
 
 : The third parameter is a function item for a URI mapper.
100
 
 : The URI mapper function, just like the URL resolver, receives 2 parameters:
101
 
 :   A $namespace as xs:string that will contain the URI to be mapped.
102
 
 :   A $entity as xs:string that will contain the type of resolving needed;
103
 
 :   this can be 2 values "module" and "schema".
104
 
 : The URI mapper must return an empty sequence when the specified $namesapce or $entity
105
 
 : are not to be mapped. Unlike the URL resolver this function must return a sequence of strings.
106
 
 :
107
 
 : Example:
108
 
 :
109
 
 : declare function mymod:uri-mapper($namespace as xs:string, $entity as xs:string)
 
92
 : };</code>
 
93
 : <p/>
 
94
 : <p>The URL resolver function's namespace, name, and parameter naming are
 
95
 : not restricted by ZQ.</p>
 
96
 : <p/>
 
97
 : <p>The URL resolver function's return type is not restricted, it could be a string, a sequence,
 
98
 : a node, etc. All the outputs types are to be serialized as a string.</p>
 
99
 : <p/>
 
100
 : <p>The third parameter is a function item for a URI mapper.</p>
 
101
 : <ul>The URI mapper function, just like the URL resolver, receives 2 parameters:
 
102
 : <li>A $namespace as xs:string that will contain the URI to be mapped.</li>
 
103
 : <li>A $entity as xs:string that will contain the type of resolving needed.
 
104
 :   This can be one of two values: "module" or "schema".</li>
 
105
 : </ul>
 
106
 : <p>The URI mapper must return an empty sequence when the specified $namesapce or $entity
 
107
 : are not to be mapped. Unlike the URL resolver this function must return a sequence of strings.</p>
 
108
 : <p/>
 
109
 : <p>Example:</p>
 
110
 : <p/>
 
111
 : <code>declare function mymod:uri-mapper($namespace as xs:string, $entity as xs:string)
110
112
 : {
111
113
 :  if($namespace = 'http://test')
112
 
 :  then ("http://www.zorba-xquery.com/test", "http://foo.com/schema/test")
 
114
 :  then ("http://zorba.io/test", "http://foo.com/schema/test")
113
115
 :  else ()
114
 
 : };
115
 
 :
116
 
 : The URI mapper function's namespace, name, and parameter naming are
117
 
 : not restricted by XQXQ.
118
 
 :
119
 
 : In order to pass the above URL resolver and URI mapper to this function,
120
 
 : use the following syntax:
121
 
 :
122
 
 :   variable $queryID := xqxq:prepare-main-module("..query text..",
123
 
 :      mymod:url-resolver#2, mymod:uri-mapper#2);
124
 
 :
125
 
 : That is, the QName of the function followed by "#2". This is XQuery
 
116
 : };</code>
 
117
 : <p/>
 
118
 : <p>The URI mapper function's namespace, name, and parameter naming are
 
119
 : not restricted by ZQ.</p>
 
120
 : <p/>
 
121
 : <p>In order to pass the above URL resolver and URI mapper to this function,
 
122
 : use the following syntax:</p>
 
123
 : <p/>
 
124
 :   <code>variable $queryID := zq:prepare-main-module("..query text..",
 
125
 :      mymod:url-resolver#2, mymod:uri-mapper#2);</code>
 
126
 : <p/>
 
127
 : <p>That is, the QName of the function followed by "#2". This is XQuery
126
128
 : "higher-order function" syntax, meaning the function with the specified
127
129
 : QName which takes two arguments. Since URL resolvers and URI mappers
128
 
 : must take two arguments, both will always be specified with "#2".
129
 
 :
130
 
 : Note that parameters 2 and 3 should be declared as follows:
131
 
 :    as function($url as xs:string, $entity as xs:string) as item()
132
 
 :    as function($uri as xs:string, $entity as xs:string) as xs:string*
133
 
 : However Zorba's implementation of higher-order functions (HOF) is not
134
 
 : yet complete enough to allow for this. When Zorba's HOF implementation
135
 
 : is complete this function signature will be changed.
136
 
 :
137
 
 : Both the URL resolver and URI mapper functions are optional, meaning you
138
 
 : may pass the empty-sequence () for either.
139
 
 :
140
 
 : Successfully prepared queries need to be deleted by passing the resulting
141
 
 : identifier to the xqxq:delete-query function of this module.
142
 
 :
143
 
 : @param $main-module-text the XQuery program that should be prepared.
144
 
 :   The program needs to be a XQuery main module.
 
130
 : must take two arguments, both will always be specified with "#2".</p>
 
131
 : <p/>
 
132
 : <p>Both the URL resolver and URI mapper functions are optional, meaning you
 
133
 : may pass the empty-sequence () for either.</p>
 
134
 : <p/>
 
135
 : <p>Successfully prepared queries need to be deleted by passing the resulting
 
136
 : identifier to the zq:delete-query function of this module.</p>
 
137
 :
 
138
 : @param $main-module-text the query that should be prepared.
 
139
 :   The query needs to be a XQuery or JSONiq main module.
145
140
 :
146
141
 : @param $resolver the URL resolver function.
147
142
 : 
148
143
 : @param $mapper the URI mapper function.
149
144
 :
150
 
 : @return an identifier for the compiled program that can be passed
 
145
 : @return an identifier for the compiled query that can be passed
151
146
 :   as arguments to other functions of this module.
152
147
 :
153
148
 : @error any (static or type) error that may be raised during the compilation
154
 
 : of the query. For example, err:XPST0003 if the given XQuery program could
 
149
 : of the query. For example, err:XPST0003 if the given query could
155
150
 : not be parsed.
156
151
 :)
157
 
declare %an:sequential function xqxq:prepare-main-module($main-module-text as xs:string, $resolver as item()?, $mapper as item()?) as 
158
 
  xs:anyURI external;
 
152
declare %an:sequential function zq:prepare-main-module(
 
153
  $main-module-text as xs:string,
 
154
  $resolver as ( function(xs:string, xs:string) as item()? )?,
 
155
  $mapper as ( function(xs:string, xs:string) as xs:string* )? ) as 
 
156
    xs:anyURI external;
159
157
 
160
158
(:~
161
 
 : This function compiles a given XQuery library module. It can be used
162
 
 : to compile-check a module. 
 
159
 : <p>This function compiles a given XQuery or JSONiq library module.
 
160
 : It can be used to compile-check a module.</p> 
163
161
 :
164
 
 : @param $library-module-text the XQuery library module that should
 
162
 : @param $library-module-text the library module that should
165
163
 :  be prepared. 
166
164
 :
167
 
 : @return the function is declared as sequential.It returns the
168
 
 :  empty-sequence.
 
165
 : @return the empty-sequence.
169
166
 :
170
167
 : @error any (static or type) error that may be raised during the compilation
171
 
 : of the library module. For example, err:XPST0003 if the given XQuery library
 
168
 : of the library module. For example, err:XPST0003 if the given library
172
169
 : module could not be parsed.
173
170
 :)
174
 
declare %an:sequential function xqxq:prepare-library-module($library-module-text as xs:string) as 
 
171
declare %an:sequential function zq:prepare-library-module($library-module-text as xs:string) as 
175
172
  empty-sequence() external ;
176
173
 
177
174
(:~
178
 
 : The function tests if the context-item is bound for the
179
 
 : execution of the query referred to by the given query identifier.
 
175
 : <p>The function tests if the context-item is bound for the
 
176
 : execution of the query referred to by the given query identifier.</p>
180
177
 :
181
178
 : @param $query-key the identifier for a compiled query
182
179
 :
183
180
 : @return true if the context-item is bound, false otherwise.
184
181
 :
185
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
182
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
186
183
 :   was prepared.
187
184
 :)
188
 
declare function xqxq:is-bound-context-item($query-key as xs:anyURI) 
 
185
declare function zq:is-bound-context-item($query-key as xs:anyURI) 
189
186
  as xs:boolean  external;
190
187
  
191
188
 
192
189
(:~
193
 
 : The function tests if the given variable is bound for the
194
 
 : execution of the query referred to by the given query identifier.
 
190
 : <p>The function tests if the given variable is bound for the
 
191
 : execution of the query referred to by the given query identifier.</p>
195
192
 :
196
193
 : @param $query-key the identifier for a compiled query
197
194
 : @param $var-name the name of the variable
198
195
 :
199
196
 : @return true if the variable is bound, false otherwise.
200
197
 :
201
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
198
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
202
199
 :   was prepared.
203
 
 : @error xqxq:UndeclaredVariable if the given variable is not declared
 
200
 : @error zq:UNDECLARED_VARIABLE if the given variable is not declared
204
201
 :   in the query.
205
202
 :)
206
 
declare function xqxq:is-bound-variable($query-key as xs:anyURI, $var-name as 
 
203
declare function zq:is-bound-variable($query-key as xs:anyURI, $var-name as 
207
204
  xs:QName) as xs:boolean  external;
208
205
 
209
206
(:~
210
 
 : The function returns the names of the external variables that
 
207
 : <p>The function returns the names of the external variables that
211
208
 : are declared in the given query (either in the main module or
212
 
 : in any of the imported library modules).
 
209
 : in any of the imported library modules).</p>
213
210
 :
214
211
 : @param $query-key the identifier for a compiled query
215
212
 :
216
213
 : @return the sequence of names of the said external variables.
217
214
 :
218
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
215
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
219
216
 :   was prepared.
220
217
 :)
221
 
declare function xqxq:external-variables($query-key as xs:anyURI) as
 
218
declare function zq:external-variables($query-key as xs:anyURI) as
222
219
  xs:QName* external ;
223
220
  
224
221
(:~
225
 
 : The function tests if the query identified by the given key
226
 
 : is an updating query.
 
222
 : <p>The function tests if the query identified by the given key
 
223
 : is an updating query.</p>
227
224
 :
228
225
 : @param $query-key the identifier for a compiled query
229
226
 :
230
227
 : @return true if the query is an updating query, false otherwise.
231
228
 :
232
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
229
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
233
230
 :   was prepared.
234
231
 :)
235
 
declare function xqxq:is-updating($query-key as xs:anyURI) as
 
232
declare function zq:is-updating($query-key as xs:anyURI) as
236
233
  xs:boolean external;  
237
234
 
238
235
(:~
239
 
 : The function tests if the query identified by the given key
240
 
 : is sequential query.
 
236
 : <p>The function tests if the query identified by the given key
 
237
 : is sequential query.</p>
241
238
 :
242
239
 : @param $query-key the identifier for a compiled query
243
240
 :
244
241
 : @return true if the query is a sequential, false otherwise.
245
242
 :
246
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
243
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
247
244
 :   was prepared.
248
245
 :)
249
 
declare function xqxq:is-sequential($query-key as xs:anyURI) as
 
246
declare function zq:is-sequential($query-key as xs:anyURI) as
250
247
  xs:boolean external;
251
248
  
252
249
(:~
253
 
 : This function binds the context-item of the prepared query
254
 
 : identified by the given key to the $dot argument.
 
250
 : <p>This function binds the context-item of the prepared query
 
251
 : identified by the given key to the $dot argument.</p>
255
252
 :
256
253
 : @param $query-key the identifier for a compiled query
257
254
 : @param $dot the context item to bind
259
256
 : @return the function has side effects and returns the empty
260
257
 :   sequence.
261
258
 :
262
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
259
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
263
260
 :   was prepared.
264
261
 :)
265
 
declare %an:sequential function xqxq:bind-context-item($query-key as xs:anyURI,
 
262
declare %an:sequential function zq:bind-context-item($query-key as xs:anyURI,
266
263
  $dot as item()) as empty-sequence() external ;
267
264
 
268
265
(:~
269
 
 : This function binds the variable with name $name of
270
 
 : the prepared query identified by $query-key to the given sequence.
 
266
 : <p>This function binds the variable with name $name of
 
267
 : the prepared query identified by $query-key to the given sequence.</p>
271
268
 :
272
269
 : @param $query-key the identifier for a compiled query
273
270
 : @param $name the name of the external variable to bind
277
274
 : @return the function has side effects and returns the empty
278
275
 :   sequence.
279
276
 :
280
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
277
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
281
278
 :   was prepared.
282
 
 : @error xqxq:UndeclaredVariable if the given variable is not declared
 
279
 : @error zq:UNDECLARED_VARIABLE if the given variable is not declared
283
280
 :   in the query.
284
281
 :)
285
 
declare %an:sequential function xqxq:bind-variable($query-key as xs:anyURI,
 
282
declare %an:sequential function zq:bind-variable($query-key as xs:anyURI,
286
283
  $var as xs:QName, $value as item()*) as empty-sequence() external ;
287
284
 
288
285
 
289
286
(:~
290
 
 : Evaluates the given prepared query and returns the result
 
287
 : <p>Evaluates the given prepared query and returns the result
291
288
 : of the evaluation. The query must not be sequential or
292
 
 : updating.
 
289
 : updating.</p>
293
290
 :
294
291
 : @param $query-key the identifier for a compiled query
295
292
 :
296
293
 : @return the result of evaluating the given query
297
294
 :
298
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
295
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
299
296
 :   was prepared.
300
297
 :
301
 
 : @error xqxq:QueryIsUpdating if the query is an updating query.
 
298
 : @error zq:QUERY_IS_UPDATING if the query is an updating query.
302
299
 :
303
 
 : @error xqxq:QueryIsSequential if the query is sequential.
 
300
 : @error zq:QUERY_IS_SEQUENTIAL if the query is sequential.
304
301
 :
305
302
 : @error any dynamic error that is raised by evaluating the
306
303
 :   given query.
307
304
 :
308
305
 :)
309
 
declare function xqxq:evaluate($query-key as xs:anyURI) as item()* external;
 
306
declare function zq:evaluate($query-key as xs:anyURI) as item()* external;
310
307
 
311
308
(:~
312
 
 : Evaluates the given prepared query and applies the updates
313
 
 : computed by this query. The query must be an updating query.
 
309
 : <p>Evaluates the given prepared query and applies the updates
 
310
 : computed by this query. The query must be an updating query.</p>
314
311
 :
315
312
 : @param $query-key the identifier for a compiled query
316
313
 :
317
314
 : @return the function has side effects because it applies
318
315
 :  the updates of the query. It returns the empty sequence.
319
316
 :
320
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
317
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
321
318
 :   was prepared.
322
319
 :
323
 
 : @error xqxq:QueryNotUpdating if the query is not an updating query.
 
320
 : @error zq:QUERY_NOT_UPDATING if the query is not an updating query.
324
321
 :
325
 
 : @error xqxq:QueryIsSequential if the query is sequential.
 
322
 : @error zq:QUERY_IS_SEQUENTIAL if the query is sequential.
326
323
 :
327
324
 : @error any dynamic error that is raised by evaluating the
328
325
 :   given query or applying its updates.
329
326
 :
330
327
 :)
331
 
declare updating function xqxq:evaluate-updating($query-key as xs:anyURI) external;
 
328
declare updating function zq:evaluate-updating($query-key as xs:anyURI) external;
332
329
 
333
330
(:~ 
334
 
 : Evaluates the given prepared query and returns the result
335
 
 : of the evaluation. The query must be sequential.
 
331
 : <p>Evaluates the given prepared query and returns the result
 
332
 : of the evaluation. The query must be sequential.</p>
336
333
 :
337
334
 : @param $query-key the identifier for a compiled query
338
335
 :
339
336
 : @return the result of evaluating the query.
340
337
 :
341
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
338
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
342
339
 :   was prepared.
343
340
 :
344
 
 : @error xqxq:QueryNotSequential if the query is not sequential.
 
341
 : @error zq:QUERY_NOT_SEQUENTIAL if the query is not sequential.
345
342
 :
346
 
 : @error xqxq:QueryIsUpdating if the query is an updating query.
 
343
 : @error zq:QUERY_IS_UPDATING if the query is an updating query.
347
344
 :
348
345
 : @error any dynamic error that is raised by evaluating the
349
346
 :   given query.
350
347
 :
351
348
 :)
352
 
declare %an:sequential function xqxq:evaluate-sequential($query-key as
 
349
declare %an:sequential function zq:evaluate-sequential($query-key as
353
350
  xs:string) as item()* external;
354
351
  
355
352
(:~ 
356
 
 : Deletes the prepared query associated with the given identifier.
357
 
 : After the query is deleted, the corresponding identifier should
358
 
 : not be used as argument to any of the functions of this module.
 
353
 : <p>Deletes the prepared query associated with the given identifier.</p>
 
354
 : <p>After the query is deleted, the corresponding identifier should
 
355
 : not be used as argument to any of the functions of this module.</p>
359
356
 :
360
357
 : @param $query-key the identifier for a compiled query
361
358
 :
362
359
 : @return the function has side effects and returns the empty sequence.
363
360
 :
364
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
361
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
365
362
 :   was prepared.
366
363
 :
367
364
 :)
368
 
declare %an:sequential function xqxq:delete-query($query-key as xs:anyURI) as
 
365
declare %an:sequential function zq:delete-query($query-key as xs:anyURI) as
369
366
  empty-sequence() external;
370
367
 
371
368
(:~
372
 
 : This function returns the value of a variable that is bound in the
373
 
 : given query.
 
369
 : <p>This function returns the value of a variable that is bound in the
 
370
 : given query.</p>
374
371
 :
375
372
 : @param $query-key the identifier of a compiled query.
376
373
 : @param $var-name the name of the variable whose value should be returned.
377
374
 :
378
375
 : @return the value bound to the given variable.
379
376
 :
380
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
377
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
381
378
 :   was prepared.
382
 
 : @error xqxq:UndeclaredVariable if the given variable is not declared
 
379
 : @error zq:UNDECLARED_VARIABLE if the given variable is not declared
383
380
 :   in the query.
384
 
 : @error xqxq:UnboundVariable if the given variable doesn't have a value.
 
381
 : @error zq:UNBOUND_VARIABLE if the given variable doesn't have a value.
385
382
 :)
386
 
declare function xqxq:variable-value($query-key as xs:anyURI, $var-name as 
 
383
declare function zq:variable-value($query-key as xs:anyURI, $var-name as 
387
384
  xs:QName) as item()* external;
388
385
 
389
386
(:~
390
 
 : Returns the compiled query identified by the given query-key 
391
 
 : as binary data.
 
387
 : <p>Returns the compiled query identified by the given query-key 
 
388
 : as binary data.</p>
392
389
 :
393
390
 : @param $query-key the identifier of a compiled query.
394
391
 :
395
392
 : @return the query as xs:base64Binary.
396
393
 :
397
 
 : @error xqxq:NoQueryMatch if no query with the given identifier
 
394
 : @error zq:NO_QUERY_MATCH if no query with the given identifier
398
395
 :   was prepared.
399
 
 : @error xqxq:QueryPlanError if there is an error serializing the query.
 
396
 : @error zq:NO_QUERY_PLAN if there is an error serializing the query.
400
397
 :)
401
 
declare function xqxq:query-plan($query-key as xs:anyURI) 
 
398
declare function zq:query-plan($query-key as xs:anyURI) 
402
399
  as xs:base64Binary external;
403
400
  
404
401
  
405
402
(:~
406
 
 : The function loads a given XQuery program for execution from a 
407
 
 : xs:base64Binary query plan, obtained through the xqxq:query-plan function.
408
 
 : If the program was successfully loaded, the function returns an
 
403
 : <p>The function loads a given query for execution from a 
 
404
 : xs:base64Binary query plan, obtained through the zq:query-plan function.</p>
 
405
 : <p>If the query was successfully loaded, the function returns an
409
406
 : identifier as xs:anyURI. This URI can be passed to other functions
410
 
 : of this module (e.g. to actually evaluate the program). The URI
411
 
 : is opaque and its lifetime is bound by the lifetime of the XQuery
412
 
 : program that invoked this function. Further reference or uses
413
 
 : of the identifier lead to unexpected results.
414
 
 :
415
 
 : Successfully prepared queries need to be deleted by passing the resulting
416
 
 : identifier to the xqxq:delete-query function of this module.
417
 
 :
418
 
 : @param $main-module-text the XQuery program that should be prepared.
419
 
 :   The program needs to be a XQuery main module.
420
 
 :
421
 
 : @return an identifier for the compiled program that can be passed
 
407
 : of this module (e.g. to actually evaluate the query). The URI
 
408
 : is opaque and its lifetime is bound by the lifetime of the query
 
409
 : that invoked this function. Further reference or uses
 
410
 : of the identifier lead to unexpected results.</p>
 
411
 : <p/>
 
412
 : <p>Successfully prepared queries need to be deleted by passing the resulting
 
413
 : identifier to the zq:delete-query function of this module.</p>
 
414
 :
 
415
 : @param $plan the binary query plan.
 
416
 :
 
417
 : @return an identifier for the compiled query that can be passed
422
418
 :   as arguments to other functions of this module.
423
419
 :
424
420
 : @error any (static or type) error that may be raised during the compilation
425
 
 : of the query. For example, err:XPST0003 if the given XQuery program could
 
421
 : of the query. For example, err:XPST0003 if the given query could
426
422
 : not be parsed.
427
423
 :)    
428
 
declare function xqxq:load-from-query-plan($plan as xs:base64Binary)
 
424
declare function zq:load-from-query-plan($plan as xs:base64Binary)
429
425
  as xs:anyURI external;
430
426
 
431
427
(:~
432
 
 : The function loads a given XQuery program for execution from a 
433
 
 : xs:base64Binary query plan, obtained through the xqxq:query-plan function.
434
 
 : If the program was successfully loaded, the function returns an
 
428
 : <p>The function loads a given query for execution from a 
 
429
 : xs:base64Binary query plan, obtained through the zq:query-plan function.</p>
 
430
 : <p>If the query was successfully loaded, the function returns an
435
431
 : identifier as xs:anyURI. This URI can be passed to other functions
436
 
 : of this module (e.g. to actually evaluate the program). The URI
437
 
 : is opaque and its lilfetime is bound by the lifetime of the XQuery
438
 
 : program that invoked this function. Further reference or uses
439
 
 : of the identifier lead to unexpected results.
440
 
 : 
441
 
 : For important notes regarding the second and third parameters of the 
442
 
 : function, review the comments in xqxq:prepare-main-module#3.
443
 
 :
444
 
 : Successfully prepared queries need to be deleted by passing the resulting
445
 
 : identifier to the xqxq:delete-query function of this module.
446
 
 :
447
 
 : @param $main-module-text the XQuery program that should be prepared.
448
 
 :   The program needs to be a XQuery main module.
 
432
 : of this module (e.g. to actually evaluate the query). The URI
 
433
 : is opaque and its lilfetime is bound by the lifetime of the query
 
434
 : that invoked this function. Further reference or uses
 
435
 : of the identifier lead to unexpected results.</p>                 
 
436
 : <p/>
 
437
 : <p>For important notes regarding the second and third parameters of the 
 
438
 : function, review the comments in zq:prepare-main-module#3.</p>
 
439
 : <p/>
 
440
 : <p>Successfully prepared queries need to be deleted by passing the resulting
 
441
 : identifier to the zq:delete-query function of this module.</p>
 
442
 :
 
443
 : @param $plan the binary query plan.
449
444
 :
450
445
 : @param $resolver the URL resolver function.
451
446
 : 
452
447
 : @param $mapper the URI mapper function.
453
448
 :
454
 
 : @return an identifier for the compiled program that can be passed
 
449
 : @return an identifier for the compiled query that can be passed
455
450
 :   as arguments to other functions of this module.
456
451
 :
457
452
 : @error any (static or type) error that may be raised during the compilation
458
 
 : of the query. For example, err:XPST0003 if the given XQuery program could
 
453
 : of the query. For example, err:XPST0003 if the given query could
459
454
 : not be parsed.
460
455
 :)  
461
 
declare function xqxq:load-from-query-plan($plan as xs:base64Binary,
 
456
declare function zq:load-from-query-plan($plan as xs:base64Binary,
462
457
  $resolver as item()?, $mapper as item()?) as xs:anyURI external;
463
458
 
464
459
(:~
465
 
 : Internal helper function. Only necessary because of incomplete HOF
466
 
 : support in Zorba.
 
460
 : <p>Internal helper function. Only necessary because of incomplete HOF
 
461
 : support in Zorba.</p>
467
462
 :)
468
 
declare %private function xqxq:hof-invoker($hof as item(),
 
463
declare %private function zq:hof-invoker($hof as item(),
469
464
  $ns as xs:string, $entity as xs:string) as item()*
470
465
{
471
466
   $hof($ns, $entity)