View as source file or XML.

Using Modules in Zorba

Importing Modules

To make use of a particular module in your query, you must first import the module. XQuery provides standard syntax for doing this:
import module namespace file = "http://expath.org/ns/file";
This will load all the functions and variables declared by the named module into your query, and associate the specified prefix (in this case "file") with the URI of the module. You can then utilize these functions in your query:
import module namespace file = "http://expath.org/ns/file";

if (file:is-file("foo.txt"))
then file:delete("foo.txt")
else ()
You may import as many modules as you wish, so long as each is at a unique URI and is associated with a unique prefix.Please check here for more information about importing Non-core Modules.Note: the URI specified to import module will be resolved by Zorba's URI resolution mechanism; often this will result in the module being loaded from the local filesystem, even though most module URIs are in the http: scheme. For more information on this mechanism, see URI Resolvers.Alternately, you can load a specific file as a module as follows:
import module namespace file = "http://expath.org/ns/file" at "file.xq";
As discussed in URI Resolvers, this technique is usually best avoided in larger applications; however, it is useful for quick testing and debugging.

Versioning Modules

Zorba extends XQuery with the concept of versioned modules. A given module may be made available in several versions over time, and a given installation of Zorba may have multiple versions available.Version numbers for modules in Zorba are of the form major.minor[.patch]. For example: "1.0", "2.5", and "2.5.1" are all legal version numbers.You import a particular version of a module by specifying the version number as a fragment at the end of the module's namespace URI. For instance, to import version 2.0 of the file module:
import module namespace file = "http://expath.org/ns/file#2.2";

Implications of Version Numbers

Zorba presumes that a given minor version is backwards-compatible with any earlier minor version, but that later minor versions introduce additional API features that are not available in earlier versions. It will therefore allow a later minor version to be imported than is specified in the import module statement. For example, if version 2.4 of the file module is available, the above import statement will load it, even though the import statement specifies 2.2. On the other hand, if only version 2.0 of the file module available, the above import statement will not load it, because it is assumed that the query depends on features which were not introduced until version 2.2.Zorba presumes that a given major version may have incompatible changes to its API compared to a lower major version. It will therefore not allow a later major version to be imported than is specified in the import module statement. For example, if only version 3.3 of the file module is available, the above import statement will not load it, because it is assumed that version 3.x has API differences that are incompatible with version 2.x.Zorba treats patch versions (if present) in the same way as minor versions: they effectively occur "between" minor versions, and it is presumed that they may introduce new APIs which are not available in lower versions. So, given:
import module namespace file = "http://expath.org/ns/file#2.5.2";
Zorba will, for example, import version 2.5.3, 2.6, or 2.6.1 if one of them is available. It will not import version 2.5.1 or 2.5.

Specifying Version Ranges

You may import a range of version numbers, in which case Zorba will import the latest available version which matches the range. For example, if you know that any 2.x or 3.x version of the file module provides the APIs your query requires, you can use:
import module namespace file = "http://expath.org/ns/file#2.0-3.0";
Zorba will import the latest 3.x version available; or, if there are no 3.x versions, then it will import the latest 2.x version.If you know you depend on functionality that was introduced in version 2.2, but that 3.x also will work, you can use:
import module namespace file = "http://expath.org/ns/file#2.2-3.0";
In this case, Zorba will import the latest 3.x version available; or, if there are no 3.x versions, then it will import the latest 2.x version so long as it is at least 2.2.

Invalid Version Ranges

Zorba presumes that all minor version increments are backwards-compatible. Therefore, the second version specified in a version range is actually "open-ended", because any higher minor (or patch) version may also be imported by Zorba. Because of this, the following version ranges are not valid:
(: Invalid import specification :)
import module namespace file = "http://expath.org/ns/file#2.2-3.8";
(: Invalid import specification :)
import module namespace file = "http://expath.org/ns/file#2.2-2.4";
In fact, to ensure that there is no confusion about this, Zorba requires that the second version in a version range be of the form "X.0" - that is, the minor version must be "0", and there must be no patch version.

Explicit Version Import

Zorba does allow one override of its assumptions about API compatibility. If you wish to import version 2.4 and no other version (even a higher minor version), use:
import module namespace file = "http://expath.org/ns/file#2.4!";
with an exclamation point (!) after the version.This should only be used in cases where the module author did not follow Zorba's conventions, and introduced backwards-incompatible changes in version 2.5. This feature is intentionally very limited, as it is not recommended practice. In particular, you cannot use ! in conjunction with version ranges.

Importing with No Version Fragment

If you import a module without specifying a version fragment, then Zorba will import the highest available version of the module, regardless of major number.This is necessary to support modules from other sources that do not use Zorba's versioning mechanism. However, it is not recommended that you use this kind of import for a module that is versioned, because you cannot control which major version of the module you will get. This could lead to your query breaking in future when an updated, backwards-incompatible version of the module is released.