Provides access to the public functions and global variables of a dynamically-loaded XQuery library module.
fn:load-xquery-module( $module-uri as xs:stringmap(*)fn:load-xquery-module( $module-uri as xs:string,$options as map(*)map(*)The function loads an implementation-defined set of modules having the target namespace $module-uri.
Calling the one-argument version of the function has the same effect as calling the two-argument version with an empty map as the second argument.
The $options argument can be used to control the way in which the function operates.
The option parameter conventions apply.
xs:string values) which may be used or ignored in an
implementation-defined way.
xs:string*
Empty sequence
The item to be used as the initial context item when evaluating global variables in the library module. Supplying
an empty sequence is equivalent to omitting the entry from the map, and indicates the absence of a context item.
If the library module specifies a required type for the context item, then the supplied value must conform to
this type, without conversion.
item()?
Absent
Values for external variables defined in the library module. Values must be supplied
for external variables that have no default value, and may be supplied for external variables
that do have a default value. The supplied value must conform to the required type of the variable, without conversion.
The map contains one entry for each external variable: the key is the variable's name, and the associated value is
the variable's value. The option parameter conventions do not apply
to this contained map.
map(xs:QName, item()*)
An empty map
Values for vendor-defined configuration options for the XQuery processor used to process the request. The key is the
name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled
by the vendor of the XQuery processor. The meaning of the associated value is implementation-defined.
Implementations should ignore options whose names are in an unrecognized namespace.
The option parameter conventions do not apply
to this contained map.
map(xs:QName, item()*)
An empty map
The result of the function is a map R with two entries:
There is an entry whose key is the xs:string value "variables" and whose associated value
is a map V. This map (V) contains one entry for each public global variable declared in the library module.
The key of the
entry is the name of the variable, as an xs:QName value; the associated value is the value of the variable.
There is an entry whose key is the xs:string value "functions" and whose associated value
is a map F. This map (F) contains one entry for each public function declared in the library module, except that when two functions
have the same name (but different arity), they share the same entry. The key of the
entry is the name of the function(s), as an xs:QName value; the associated value is a map A.
This map (A) contains one entry for each function with the given name; its key is the arity of the function,
as an xs:integer value, and its associated value is the function itself, as a function item. The function
can be invoked using the rules for dynamic function invocation.
The static and dynamic context of the library module are established according to the rules in .
It is implementation-defined whether constructs in the library module are evaluated in the same execution scope as the calling module.
The library module that is loaded may import other modules using an import module declaration. The result of
fn:load-xquery-module does not include global variables or functions declared in such a transitively-imported module.
However, the options map supplied in the function call may
(and if no default is defined, must)
supply values for external variables declared in transitively-loaded library modules.
The library module that is loaded may import schema declarations using an import schema declaration. It is
implementation-defined whether schema components in the in-scope
schema definitions of the calling module
are automatically added to the in-scope schema definitions of the dynamically loaded module. The in-scope schema definitions
of the calling and called modules must be consistent, according to the rules defined in
.
Where nodes are passed to or from the dynamically loaded module, for example as an argument or result of a function, they should if possible retain their node identity, their base URI, their type annotations, and their relationships to all other nodes in the containing tree (including ancestors and siblings). If this is not possible, for example because the only way of passing nodes to the chosen XQuery implementation is by serializing and re-parsing, then a node may be passed in the form of a deep copy, which may lose information about the identity of the node, about its ancestors and siblings, about its base URI, about its type annotations, and about its relationships to other nodes passed across the interface.
If $module-uri is a zero length string, a dynamic error is raised .
If the implementation is not able to find a library module with the specified target namespace, an error is raised .
If a static error (including a statically-detected type error) is encountered when processing the library module, a dynamic error is raised .
If the imported module requires a value for the initial context item or for an external variable, and no value is supplied, an error is raised [FOQM0004]
If a value is supplied for the initial context item or for an external variable and the value does not conform to the required type declared in the dynamically loaded module, a dynamic error is raised .
If no suitable XQuery processor is available, a dynamic error is raised . This includes (but is not limited to) the following cases:
No XQuery processor is available;
Use of the function has been disabled;
No XQuery processor supporting the requested version of XQuery is available;
No XQuery processor supporting the optional Module Feature is available.
If the supplied options are invalid according to the rules of the , a dynamic error is raised [FOQM0007].
If a dynamic error (including a dynamically-detected type error) is encountered when processing the module (for example, when evaluating its global variables), the dynamic error is returned as is.
As with all other functions in this specification, conformance requirements depend on the host language. For example, a host language might specify that provision of this function is optional, or that it is excluded entirely, or that implementations are required to support XQuery modules using a specified version of XQuery.
Even where support for this function is mandatory, it is recommended for security reasons that implementations should provide a user option to disable its use, or to disable aspects of its functionality.