3
: Copyright 2011 The FLWOR Foundation.
5
: Licensed under the Apache License, Version 2.0 (the "License");
6
: you may not use this file except in compliance with the License.
7
: You may obtain a copy of the License at
9
: http://www.apache.org/licenses/LICENSE-2.0
11
: Unless required by applicable law or agreed to in writing, software
12
: distributed under the License is distributed on an "AS IS" BASIS,
13
: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
: See the License for the specific language governing permissions and
15
: limitations under the License.
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.
23
: @author Juan Zacarias
24
: @project Zorba/Programming Languages/XQuery
26
module namespace xqxq = 'http://www.zorba-xquery.com/modules/xqxq';
28
declare namespace an = "http://www.zorba-xquery.com/annotations";
29
declare namespace ver = "http://www.zorba-xquery.com/options/versioning";
30
declare namespace op = "http://www.zorba-xquery.com/options/features";
31
declare namespace f = "http://www.zorba-xquery.com/features";
33
declare option ver:module-version "1.0";
34
declare option op:enable "f:hof";
37
: The function prepares a given XQuery program for execution.
38
: If the program was successfully compiled, the function returns an
39
: identifier as xs:anyURI. This URI can be passed to other functions
40
: of this module (e.g. to actually evaluate the program). The URI
41
: is opaque and its lilfetime is bound by the lifetime of the XQuery
42
: program that invoked this function. Further reference or uses
43
: of the identifier lead to unexpected results.
45
: Successfully prepared queries need to be deleted by passing the resulting
46
: identifier to the xqxq:delete-query function of this module.
48
: @param $main-module-text the XQuery program that should be prepared.
49
: The program needs to be a XQuery main module.
51
: @return an identifier for the compiled program that can be passed
52
: as arguments to other functions of this module.
54
: @error any (static or type) error that may be raised during the compilation
55
: of the query. For example, err:XPST0003 if the given XQuery program could
58
declare %an:sequential function xqxq:prepare-main-module($main-module-text as xs:string) as
62
: The function prepares a given XQuery program for execution.
63
: If the program was successfully compiled, the function returns an
64
: identifier as xs:anyURI. This URI can be passed to other functions
65
: of this module (e.g. to actually evaluate the program). The URI
66
: is opaque and its lilfetime is bound by the lifetime of the XQuery
67
: program that invoked this function. Further reference or uses
68
: of the identifier lead to unexpected results.
70
: Important notes regarding the second and third parameters of the function:
71
: --------------------------------------------------------------------------
73
: These parameters allow you to specify a URL resolver and a URI mapper
74
: for Zorba to use when executing this query. See
75
: http://www.zorba-xquery.com/html/documentation/2.7.0/zorba/uriresolvers
77
: The second parameter is a function item for a URL
78
: resolver. The URL resolver function must recive 2 parameters:
79
: A $namespace as xs:string that will contain the url to be resolved.
80
: A $entity as xs:string that will contain the type of resolving needed;
81
: this can be 2 values "module" and "schema".
82
: The function must return an empty sequence when the specified $namespace
83
: or $entity are not the ones to be resolved.
87
: declare function mymod:url-resolver($namespace as xs:string, $entity as xs:string)
89
: if($namespace = 'http://test.xq')
90
: then "module namespace test = 'http://test'; declare function test:foo(){'foo'};"
94
: The URL resolver function's namespace, name, and parameter naming are
95
: not restricted by XQXQ.
97
: 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.
100
: The third parameter is a function item for a URI mapper.
101
: The URI mapper function, just like the URL resolver, receives 2 parameters:
102
: A $namespace as xs:string that will contain the URI to be mapped.
103
: A $entity as xs:string that will contain the type of resolving needed;
104
: this can be 2 values "module" and "schema".
105
: The URI mapper must return an empty sequence when the specified $namesapce or $entity
106
: are not to be mapped. Unlike the URL resolver this function must return a sequence of strings.
110
: declare function mymod:uri-mapper($namespace as xs:string, $entity as xs:string)
112
: if($namespace = 'http://test')
113
: then ("http://www.zorba-xquery.com/test", "http://foo.com/schema/test")
117
: The URI mapper function's namespace, name, and parameter naming are
118
: not restricted by XQXQ.
120
: In order to pass the above URL resolver and URI mapper to this function,
121
: use the following syntax:
123
: variable $queryID := xqxq:prepare-main-module("..query text..",
124
: mymod:url-resolver#2, mymod:uri-mapper#2);
126
: That is, the QName of the function followed by "#2". This is XQuery
127
: "higher-order function" syntax, meaning the function with the specified
128
: QName which takes two arguments. Since URL resolvers and URI mappers
129
: must take two arguments, both will always be specified with "#2".
131
: Note that parameters 2 and 3 should be declared as follows:
132
: as function($url as xs:string, $entity as xs:string) as item()
133
: as function($uri as xs:string, $entity as xs:string) as xs:string*
134
: However Zorba's implementation of higher-order functions (HOF) is not
135
: yet complete enough to allow for this. When Zorba's HOF implementation
136
: is complete this function signature will be changed.
138
: Both the URL resolver and URI mapper functions are optional, meaning you
139
: may pass the empty-sequence () for either.
141
: Successfully prepared queries need to be deleted by passing the resulting
142
: identifier to the xqxq:delete-query function of this module.
144
: @param $main-module-text the XQuery program that should be prepared.
145
: The program needs to be a XQuery main module.
147
: @param $resolver the URL resolver function.
149
: @param $mapper the URI mapper function.
151
: @return an identifier for the compiled program that can be passed
152
: as arguments to other functions of this module.
154
: @error any (static or type) error that may be raised during the compilation
155
: of the query. For example, err:XPST0003 if the given XQuery program could
158
declare %an:sequential function xqxq:prepare-main-module($main-module-text as xs:string, $resolver as item()?, $mapper as item()?) as
162
: This function compiles a given XQuery library module. It can be used
163
: to compile-check a module.
165
: @param $library-module-text the XQuery library module that should
168
: @return the function is declared as sequential.It returns the
171
: @error any (static or type) error that may be raised during the compilation
172
: of the library module. For example, err:XPST0003 if the given XQuery library
173
: module could not be parsed.
175
declare %an:sequential function xqxq:prepare-library-module($library-module-text as xs:string) as
176
empty-sequence() external ;
179
: The function tests if the context-item is bound for the
180
: execution of the query referred to by the given query identifier.
182
: @param $query-key the identifier for a compiled query
184
: @return true if the context-item is bound, false otherwise.
186
: @error xqxq:NoQueryMatch if no query with the given identifier
189
declare function xqxq:is-bound-context-item($query-key as xs:anyURI)
190
as xs:boolean external;
194
: The function tests if the given variable is bound for the
195
: execution of the query referred to by the given query identifier.
197
: @param $query-key the identifier for a compiled query
198
: @param $var-name the name of the variable
200
: @return true if the variable is bound, false otherwise.
202
: @error xqxq:NoQueryMatch if no query with the given identifier
204
: @error xqxq:UndeclaredVariable if the given variable is not declared
207
declare function xqxq:is-bound-variable($query-key as xs:anyURI, $var-name as
208
xs:QName) as xs:boolean external;
211
: The function returns the names of the external variables that
212
: are declared in the given query (either in the main module or
213
: in any of the imported library modules).
215
: @param $query-key the identifier for a compiled query
217
: @return the sequence of names of the said external variables.
219
: @error xqxq:NoQueryMatch if no query with the given identifier
222
declare function xqxq:external-variables($query-key as xs:anyURI) as
226
: The function tests if the query identified by the given key
227
: is an updating query.
229
: @param $query-key the identifier for a compiled query
231
: @return true if the query is an updating query, false otherwise.
233
: @error xqxq:NoQueryMatch if no query with the given identifier
236
declare function xqxq:is-updating($query-key as xs:anyURI) as
240
: The function tests if the query identified by the given key
241
: is sequential query.
243
: @param $query-key the identifier for a compiled query
245
: @return true if the query is a sequential, false otherwise.
247
: @error xqxq:NoQueryMatch if no query with the given identifier
250
declare function xqxq:is-sequential($query-key as xs:anyURI) as
254
: This function binds the context-item of the prepared query
255
: identified by the given key to the $dot argument.
257
: @param $query-key the identifier for a compiled query
258
: @param $dot the context item to bind
260
: @return the function has side effects and returns the empty
263
: @error xqxq:NoQueryMatch if no query with the given identifier
266
declare %an:sequential function xqxq:bind-context-item($query-key as xs:anyURI,
267
$dot as item()) as empty-sequence() external ;
270
: This function binds the variable with name $name of
271
: the prepared query identified by $query-key to the given sequence.
273
: @param $query-key the identifier for a compiled query
274
: @param $name the name of the external variable to bind
275
: @param $value the sequence to which the external variable $name
278
: @return the function has side effects and returns the empty
281
: @error xqxq:NoQueryMatch if no query with the given identifier
283
: @error xqxq:UndeclaredVariable if the given variable is not declared
286
declare %an:sequential function xqxq:bind-variable($query-key as xs:anyURI,
287
$var as xs:QName, $value as item()*) as empty-sequence() external ;
291
: Evaluates the given prepared query and returns the result
292
: of the evaluation. The query must not be sequential or
295
: @param $query-key the identifier for a compiled query
297
: @return the result of evaluating the given query
299
: @error xqxq:NoQueryMatch if no query with the given identifier
302
: @error xqxq:QueryIsUpdating if the query is an updating query.
304
: @error xqxq:QueryIsSequential if the query is sequential.
306
: @error any dynamic error that is raised by evaluating the
310
declare function xqxq:evaluate($query-key as xs:anyURI) as item()* external;
313
: Evaluates the given prepared query and applies the updates
314
: computed by this query. The query must be an updating query.
316
: @param $query-key the identifier for a compiled query
318
: @return the function has side effects because it applies
319
: the updates of the query. It returns the empty sequence.
321
: @error xqxq:NoQueryMatch if no query with the given identifier
324
: @error xqxq:QueryNotUpdating if the query is not an updating query.
326
: @error xqxq:QueryIsSequential if the query is sequential.
328
: @error any dynamic error that is raised by evaluating the
329
: given query or applying its updates.
332
declare updating function xqxq:evaluate-updating($query-key as xs:anyURI) external;
335
: Evaluates the given prepared query and returns the result
336
: of the evaluation. The query must be sequential.
338
: @param $query-key the identifier for a compiled query
340
: @return the result of evaluating the query.
342
: @error xqxq:NoQueryMatch if no query with the given identifier
345
: @error xqxq:QueryNotSequential if the query is not sequential.
347
: @error xqxq:QueryIsUpdating if the query is an updating query.
349
: @error any dynamic error that is raised by evaluating the
353
declare %an:sequential function xqxq:evaluate-sequential($query-key as
354
xs:string) as item()* external;
357
: Deletes the prepared query associated with the given identifier.
358
: After the query is deleted, the corresponding identifier should
359
: not be used as argument to any of the functions of this module.
361
: @param $query-key the identifier for a compiled query
363
: @return the function has side effects and returns the empty sequence.
365
: @error xqxq:NoQueryMatch if no query with the given identifier
369
declare %an:sequential function xqxq:delete-query($query-key as xs:anyURI) as
370
empty-sequence() external;
374
: Internal helper function. Only necessary because of incomplete HOF
377
declare %private function xqxq:hof-invoker($hof as item(),
378
$ns as xs:string, $entity as xs:string) as item()*
added
removed
modules/xqxq/xqxq.xq
