EXPath extensions

EXPath is a more recent initiative to define a standardized set of extension functions and extension elements that can be used across different XSLT and XQuery processors.

Saxon supports the EXPath file module since release 9.5. Since 9.6 the binary and archive modules are supported too. Note that the zip module was withdrawn at 9.5.1 and is now replaced by archive and that some of the functions of file changed between 9.5 and 9.6 as result of specification changes.

Details of the functions supported (with some additional information about the Saxon implementation) can be found in the main Function library.

The EXPath file module

The file module provides a set of functions to examine and manipulate the local file system. For the specification of the file module see EXPath File Module.

All functions in the file module are implemented.

Note that many of the functions in this module have side-effects, and therefore need to be used with care to ensure that they are called the right number of times, and in the right order. The best way of achieving this is to imagine that a function like file:write() produces an invisible result, and that this invisible result needs to be inserted into the final result of the query or stylesheet. So, for example, if <body>...</body> is an element being written to the result tree, then the function call <body>{file:write(...)}</body> will always be evaluated exactly once. By contrast, a call appearing as the initializer of a variable (for example in let $x := file:write(...) return ...) might be evaluated multiple times or not at all, depending on how the variable is actually used.

A good way to invoke functions with side-effects is to use the saxon:do extension instruction: for example <saxon:do action="file:create-dir('temp')"/>. This is because instructions within a sequence constructor are always evaluated sequentially, in the order written.

Functions in the EXPath file module use file paths that are specified as being relative to the "current working directory". If the Java system property expath.base.directory is present, this is taken as the current working directory. In other cases, Saxon interprets the file name using the rules of the Java method File.getCanonicalFile().

Note that the UNIX concept of "current working directory" does not translate directly to Microsoft Windows. On Windows, systems, there is in effect a current drive and an active directory in each drive. A simple relative file name like a.xml is interpreted relative to the active directory of the current drive. A file name of the form E:a.xml is interpreted relative to the active directory of the named drive (E:). A file name in the form \p\q\a.xml is interpreted relative to the root directory of the current drive. More specifically, file names are interpreted using the rules of the Java method File.getCanonicalFile().

On Windows, a file name starting "//" or "\\" is interpreted as a UNC file name. In particular, the function file:path-to-uri(name) converts //server/p/q/a.xml to file://server/p/q/a.xml - that is, the server part of the UNC name becomes the authority part of the URI.

The EXPath binary module

The binary module defines a library of functions for manipulating binary data and converting between binary data and string and numeric forms. For the specification of the binary module see EXPath Binary Module. The specification has been stabilised at a Version 1.0 status so the functions can be considered stable.

All functions in the binary module are implemented and tested. Note that this module does not provide binary file i/o - functions from the EXPath file module should be used for such operations.

The EXPath archive module

The archive module defines facilities for reading, creating and manipulating content arranged into archive (ZIP, JAR) collections. For the specification of the archive module see EXPath Archive Module.

Most functions in the archive module are implemented and tested. Note that this module does not provide file i/o of archives directly - functions from the EXPath file module should be used for such operations, or are used indirectly by the archive-file system conversion functions.

Two groups of the archive module functions exist - one using element structures, the other using maps - for details see Using map types to describe entries and options. Note that mechanisms for describing options and properties through elements and attributes are not yet finalised. If you are using XPath 3.0 then we suggest strongly that you use the map-based function forms (which have names ending in -map), as their specification is much more likely to be stable, and the functions are easier to use.

Other EXPath modules

Implementations of other EXPath modules may be available from third parties.