fn:load-xquery-module

Provides access to the public functions and global variables of a dynamically-loaded XQuery library module.

Signatures

fn:load-xquery-module($module-uri as xs:string) as map(*)

fn:load-xquery-module(
    $module-uri as xs:string, 
    $options as map(*)
) as map(*)

Properties

This function is deterministic, context-dependent, focus-independent, and higher-order.

Rules

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.

Key	Meaning
`xquery-version`	The minimum level of the XQuery language that the processor must support. Type: `xs:decimal` Default: `The version given in the prolog of the library module; or implementation-defined if this is absent.`
`location-hints`	A sequence of URIs (in the form of `xs:string` values) which may be used or ignored in an implementation-defined way. Type: `xs:string*` Default: `Empty sequence`
`context-item`	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. Type: `item()?` Default: `Absent`
`variables`	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. Type: `map(xs:QName, item()*)` Default: `An empty map`
`vendor-options`	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. Type: `map(xs:QName, item()*)` Default: `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.

Error Conditions

If $module-uri is a zero length string, a dynamic error is raised [ERRFOQM0001].

If the implementation is not able to find a library module with the specified target namespace, an error is raised [ERRFOQM0002].

If a static error (including a statically-detected type error) is encountered when processing the library module, a dynamic error is raised [ERRFOQM0003].

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 [ERRFOQM0005].

If no suitable XQuery processor is available, a dynamic error is raised [ERRFOQM0006]. 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 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.

Notes

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.