This proposal provides a file system API for XPath. It defines extension functions to perform file system related operations such as listing, reading, or writing files or directories. It has been designed to be compatible with XQuery 1.0 and XSLT 2.0, as well as any other XPath 2.0 usage.
The module defined by this document defines the functions and variables in the
namespace http://expath.org/ns/file. In this document, the
file prefix, when used, is bound to this namespace URI.
Error codes are defined in the namespace http://expath.org/ns/error. In
this document, the err prefix, when used, is bound to this namespace
URI.
All file paths are specified as strings, and are resolved against the current working directory. An implementation must accept absolute and relative UNIX/Linux and Windows paths as well as absolute file URIs. Some examples:
C:\Test Dir\my file.xml: An absolute path on Windows
platforms.
/Test Dir/my file.xml: An absolute path on UNIX-based
platforms.
C:\\\Test Dir//\\my file.xml: An absolute path on Windows
platforms that tolerates an arbitrary number of slashes and backslashes.
my file.xml: A relative path, pointing to a file in the current
working directory.
file:///C:/Test%20Dir/my%20file.xml: An absolute file URI on
Windows platforms.
file:///Test%20Dir/my%20file.xml: An absolute path on UNIX-based
platforms.
Before further processing, all paths must first be normalized to an implementation-defined representation (which usually is the representation of the underlying operating system).
Functions on File Properties (Section 2) and Input/Output (Section 3) are ·nondeterministic·, which means they are not guaranteed to perform the same actions and produce identical results from repeated calls. As such, a processor must ensure that these functions are not relocated or pre-evaluated and that its results are not cached when compiling and evaluating the query and serializing its results.
Error conditions are identified by a code (a QName). When such an error
condition is reached during the execution of the function, a dynamic error is thrown,
with the corresponding error code (as if the standard XPath function
error had been called).
Error codes are defined through the specification. If file operations raise additional, errors, which may be specific to the underlying platform or programming language, the generic error [=err:FILE9999=] with an appropriate message is raised.
For a list of specific errors see the "Summary of Error Conditions" section of this document.
file:existsTests if a path/URI is already used in the file system.
The function returns true() if a file or a directory exists at the
location pointed by $path.
file:is-dirTests if $path points to a directory. On UNIX-based systems the root and
the volume roots are considered directories.
file:is-fileTests if $path points to a file.
file:last-modifiedReturns xs:dateTime representing the last modification time.
[=err:FILE0001=] is raised if $path does not
exist.
[=err:FILE9999=] is raised if any other error occurs.
file:sizeReturns the byte size of a file as integer.
[=err:FILE0001=] is raised if $path does not
exist.
[=err:FILE0004=] is raised if $path points to a
directory.
[=err:FILE9999=] is raised if any other error occurs.
file:appendAppends a sequence of items to a file. If the file pointed by $file does
not exist, a new file will be created.
$params controls the way the $items items are serialized.
The semantics of $params is the same as for the
fn:serialize function in [[xpath-functions-30]]. This consists of an
output:serialization-parameters element whose format is defined in
[[xslt-xquery-serialization-30]]. In contrast to fn:serialize, the encoding stage will not be
skipped by this function.
The function returns the empty sequence if the operation is successful.
[=err:FILE0003=] is raised if the parent directory of
$file does not exist.
[=err:FILE0004=] is raised if $file points to a
directory.
[=err:FILE9999=] is raised if any other error occurs.
file:append-textAppends a string to a file. If the file pointed by $file does not exist,
a new file will be created.
The optional parameter $encoding, if not provided, is considered to be
UTF-8.
The function returns the empty sequence if the operation is successful.
[=err:FILE0003=] is raised if the parent directory of
$file does not exist.
[=err:FILE0004=] is raised if $file points to a
directory.
[=err:FILE0005=] is raised if $encoding is invalid or
not supported by the implementation.
[=err:FILE9999=] is raised if any other error occurs.
file:append-text-linesAppends a sequence of strings to a file, each followed by the system-dependent
newline character. If the file pointed by $file does not exist, a new
file will be created.
The optional parameter $encoding, if not provided, is considered to be
UTF-8.
The function returns the empty sequence if the operation is successful.
[=err:FILE0003=] is raised if the parent directory of
$file does not exist.
[=err:FILE0004=] is raised if $file points to a
directory.
[=err:FILE0005=] is raised if $encoding is invalid or
not supported by the implementation.
[=err:FILE9999=] is raised if any other error occurs.
file:append-binaryAppends a Base64 item as binary to a file. If the file pointed by $file
does not exist, a new file will be created.
The function returns the empty sequence if the operation is successful.
[=err:FILE0003=] is raised if the parent directory of
$file does not exist.
[=err:FILE0004=] is raised if $file points to a
directory.
[=err:FILE9999=] is raised if any other error occurs.
file:copyCopies a file or a directory given a source and a target path/URI. The following
cases may occur if $source points to a file:
if $target does not exist, it will be created.
if $target is a file, it will be overwritten.
if $target is a directory, the file will be created in that
directory with the name of the source file. If a file already exists, it will be
overwritten.
The following cases may occur if $source points to a directory:
if $target does not exist, it will be created as directory, and all
files of the source directory are copied to this directory with their existing
local names.
if $target is a directory, all files are copied from the source
into the target directory. If a file already exists, it will be overwritten.
Other cases will raise one of the errors listed below.
The function returns the empty sequence if the operation is successful. If an error occurs during the operation, no rollback to the original state will be possible
[=err:FILE0001=] is raised if the $source path does not
exist.
[=err:FILE0002=] is raised if $source points to a
directory and $target points to an existing file.
[=err:FILE0003=] is raised if the parent directory of
$source does not exist.
[=err:FILE0004=] is raised if $source points to a file
and $target points to a directory, in which a subdirectory exists
with the name of the source file.
[=err:FILE9999=] is raised if any other error occurs.
file:create-dirCreates a directory, or does nothing if the directory already exists. The operation will create all non-existing parent directories.
The function returns the empty sequence if the operation is successful.
[=err:FILE0002=] is raised if the specified path, or any of its parent directories, points to an existing file.
[=err:FILE9999=] is raised if any other error occurs.
file:deleteDeletes a file or a directory from the file system.
If the optional parameter $recursive is set to true(),
sub-directories will be deleted as well.
The function returns the empty sequence if the operation is successful.
[=err:FILE0001=] is raised if $path does not
exist.
[=err:FILE0004=] is raised if $file points to a
non-empty directory.
[=err:FILE9999=] is raised if any other error occurs.
file:listLists all files and directories in a given directory. The order of the items in the
resulting sequence is not defined. The "." and ".." items are never returned. The
returned paths are relative to the provided directory $dir.
If the optional parameter $recursive is set to true(), all
directories and files will be returned that are found while recursively traversing
the given directory.
The optional $pattern parameter defines a name pattern in the glob
syntax. If this is provided, only the paths of the files and directories whose names
are matching the pattern will be returned.
An implementation must support at least the following glob syntax for the pattern:
* for matching any number of unknown characters and
? for matching one unknown character.
[=err:FILE0003=] is raised $dir does not point to an
existing directory.
[=err:FILE9999=] is raised if any other error occurs.
file:moveMoves a file or a directory given a source and a target path/URI. The following cases
may occur if $source points to a file:
if $target does not exist, it will be created.
if $target is a file, it will be overwritten.
if $target is a directory, the file will be created in that
directory with the name of the source file. If a file already exists, it will be
overwritten.
The following cases may occur if $source points to a directory:
if $target does not exist, it will be created as directory, and all
files of the source directory are moved to this directory with their existing
local names.
if $target is a directory, all files are moved from the source into
the target directory. If a file already exists, it will be overwritten.
Other cases will raise one of the errors listed below.
The function returns the empty sequence if the operation is successful. If an error occurs during the operation, no rollback to the original state will be possible
[=err:FILE0001=] is raised if the $source path does not
exist.
[=err:FILE0002=] is raised if $source points to a
directory and $target points to an existing file.
[=err:FILE0003=] is raised if the parent directory of
$source does not exist.
[=err:FILE0004=] is raised if $source points to a file
and $target points to a directory, in which a subdirectory exists
with the name of the source file.
[=err:FILE9999=] is raised if any other error occurs.
file:read-binaryReturns the content of a file in its Base64 representation.
[=err:FILE0001=] is raised if $file does not
exist.
[=err:FILE0004=] is raised if $file points to a
directory.
[=err:FILE9999=] is raised if any other error occurs.
file:read-textReturns the content of a file in its string representation.
The optional parameter $encoding, if not provided, is considered to be
UTF-8.
[=err:FILE0001=] is raised if $file does not
exist.
[=err:FILE0004=] is raised if $file points to a
directory.
[=err:FILE0005=] is raised if $encoding is invalid or
not supported by the implementation.
[=err:FILE9999=] is raised if any other error occurs.
file:read-text-linesReturns the contents of a file as a sequence of strings, separated at newline boundaries.
The optional parameter $encoding, if not provided, is considered to be
UTF-8.
The newline handling is the same as for the fn:unparsed-text-lines
function in [[xpath-functions-30]].
[=err:FILE0001=] is raised if $file does not
exist.
[=err:FILE0004=] is raised if $file points to a
directory.
[=err:FILE0005=] is raised if $encoding is invalid or
not supported by the implementation.
[=err:FILE9999=] is raised if any other error occurs.
file:writeWrites a sequence of items to a file.
If $file already exists, it will be overwritten.
$params controls the way the $items items are serialized.
The semantics of $params is the same as for the
fn:serialize function in [[xpath-functions-30]]. This consists of an
output:serialization-parameters element whose format is defined in
[[xslt-xquery-serialization-30]]. In contrast to fn:serialize, the encoding stage will not be
skipped by this function.
The function returns the empty sequence if the operation is successful.
[=err:FILE0003=] is raised if the parent directory of
$file does not exist.
[=err:FILE0004=] is raised if $file points to a
directory.
[=err:FILE9999=] is raised if any other error occurs.
file:write-textWrites a strings to a file. If $file already exists, it will be
overwritten.
The optional parameter $encoding, if not provided, is considered to be
UTF-8.
The function returns the empty sequence if the operation is successful.
[=err:FILE0003=] is raised if the parent directory of
$file does not exist.
[=err:FILE0004=] is raised if $file points to a
directory.
[=err:FILE0005=] is raised if $encoding is invalid or
not supported by the implementation.
[=err:FILE9999=] is raised if any other error occurs.
file:write-text-linesWrites a sequence of strings to a file, each followed by the system-dependent newline
character. If $file already exists, it will be overwritten.
The optional parameter $encoding, if not provided, is considered to be
UTF-8.
The function returns the empty sequence if the operation is successful.
[=err:FILE0003=] is raised if the parent directory of
$file does not exist.
[=err:FILE0004=] is raised if $file points to a
directory.
[=err:FILE0005=] is raised if $encoding is invalid or
not supported by the implementation.
[=err:FILE9999=] is raised if any other error occurs.
file:write-binaryWrites a Base64 items as binary to a file. If $file already exists, it
will be overwritten.
The function returns the empty sequence if the operation is successful.
[=err:FILE0003=] is raised if the parent directory of
$file does not exist.
[=err:FILE0004=] is raised if $file points to a
directory.
[=err:FILE9999=] is raised if any other error occurs.
None of the functions in this section performs any check regarding the existence of the received or returned paths.
file:base-nameReturns the last component from $path, deleting any trailing directory
separators. If $path consists entirely of directory separator, the empty
string is returned. If $path is the empty string, the string
"." is returned, signifying the current working directory.
If $suffix is present, it will be trimmed from the end of the result.
This can be used to eliminate file extensions.
No path existence check is made.
file:dir-nameThis function returns a string denoting the parent directory of $path.
Any trailing directory separators are not counted as part of the directory name. If
the specified string is empty or contains no directory separators, "."
is returned, signifying the current directory.
No path existence check is made.
file:path-to-nativeTransforms a URI, an absolute path, or relative path to a canonical, system-dependent path representation. A canonical path is both absolute and unique and thus contains no redirections such as references to parent directories or symbolic links.
No path existence check is made.
[=err:FILE9999=] is raised if an error occurs while trying to obtain the native path.
file:path-to-uriTransforms a file system path into a URI with the file:// scheme. If the
path is relative, it is first resolved against the current working directory.
No path existence check is made.
file:resolve-pathTransforms a relative path into an absolute operating system path by resolving it against the current working directory.
No path existence check is made.
file:dir-separatorReturns the value of the operating system specific directory separator, which usually
is / on UNIX-based systems and \ on Windows systems.
file:path-separatorReturns the value of the operating system specific path separator, which usually is
: on UNIX-based systems and ; on Windows systems.
file:line-separatorReturns the value of the operating system specific line separator, which usually is
on UNIX-based systems, on
Windows systems and on Mac systems.