File Module

This XQuery Module contains functions related to file system operations, such as listing, reading, or writing files.

This module is based on the EXPath File Module.

Conventions

All functions in this module are assigned to the http://expath.org/ns/file namespace, which is statically bound to the file prefix.
All errors are assigned to the http://expath.org/ns/error namespace, which is statically bound to the experr prefix.

All returned strings that refer to existing directories will be suffixed with a directory separator.

Read Operations

file:list

Signatures	file:list($dir as xs:string) as xs:string* file:list($dir as xs:string, $recursive as xs:boolean) as xs:string* file:list($dir as xs:string, $recursive as xs:boolean, $pattern as xs:string) as xs:string*
Summary	Lists all files and directories found in the specified $dir. The returned paths are relative to the provided path. The optional parameter $recursive specifies whether sub-directories will be traversed, too. The optional parameter $pattern defines a file name pattern in the glob syntax. If present, only those files and directories are returned that correspond to the pattern. Several patterns can be separated with a comma (,).
Errors	FILE0003: the specified path does not point to a directory. FILE9999: the operation fails for some other reason.

file:read-binary

Template:Mark arguments $offset and $length added.

Signatures	file:read-binary($path as xs:string) as xs:base64Binary file:read-binary($path as xs:string, $offset as xs:integer) as xs:base64Binary file:read-binary($path as xs:string, $offset as xs:integer, $length as xs:integer) as xs:base64Binary
Summary	Reads the binary content of the file specified by $path and returns it as streamable xs:base64Binary. The optional parameters $offset and $length can be used to read chunks of a file.
Errors	FILE0001: the specified file does not exist. FILE0004: the specified path is a directory.FILE0006: the offset or length is negative, or the chosen values would exceed the file bounds. FILE9999: the operation fails for some other reason.
Examples	stream:materialize(file:read-binary("config.data")) returns a materialized representation of the streamable result.

file:read-text

Signatures	file:read-text($path as xs:string) as xs:string file:read-text($path as xs:string, $encoding as xs:string) as xs:string
Summary	Reads the textual contents of the file specified by $path and returns it as streamable xs:string. The optional parameter $encoding defines the encoding of the file.
Errors	FILE0001: the specified file does not exist. FILE0004: the specified path is a directory. FILE0005: the specified encoding is not supported, or unknown. FILE9999: the operation fails for some other reason. Invalid XML characters will be ignored if the CHECKSTRINGS option is turned off.
Examples	stream:materialize(file:read-text("config.txt")) returns a materialized representation of the streamable result.

file:read-text-lines

Signatures	file:read-text-lines($path as xs:string) as xs:string file:read-text-lines($path as xs:string, $encoding as xs:string) as xs:string*
Summary	Reads the textual contents of the file specified by $path and returns it as a sequence of xs:string items. The optional parameter $encoding defines the encoding of the file.
Errors	FILE0001: the specified file does not exist. FILE0004: the specified path is a directory. FILE0005: the specified encoding is not supported, or unknown. FILE9999: the operation fails for some other reason.

Write Operations

file:create-dir

Signatures	file:create-dir($dir as xs:string) as empty-sequence()
Summary	Creates the directory specified by $dir, including all non-existing parent directories.
Errors	FILE0002: a file with the same path already exists. FILE9999: the operation fails for some other reason.

file:create-temp-dir

Signatures	file:create-temp-dir($prefix as xs:string, $suffix as xs:string) as xs:string file:create-temp-dir($prefix as xs:string, $suffix as xs:string, $dir as xs:string) as xs:string
Summary	Creates a new temporary directory that did not exist before this function was called, and returns its full file path. The directory name begins and ends with the specified $prefix and $suffix. If no directory is specified via $dir, the directory will be placed in the system’s default temporary directory. The operation will create all non-existing parent directories.
Errors	FILE0003: the specified directory points to a file. FILE9999: the directory could not be created.

file:create-temp-file

Signatures	file:create-temp-file($prefix as xs:string, $suffix as xs:string) as xs:string file:create-temp-file($prefix as xs:string, $suffix as xs:string, $dir as xs:string) as xs:string
Summary	Creates a new temporary file that did not exist before this function was called, and returns its full file path. The file name begins and ends with the specified $prefix and $suffix. If no directory is specified via $dir, the file will be placed in the system’s default temporary directory. The operation will create all non-existing parent directories.
Errors	FILE0003: the specified directory points to a file. FILE9999: the directory could not be created.

file:delete

Signatures	file:delete($path as xs:string) as empty-sequence() file:delete($path as xs:string, $recursive as xs:boolean) as empty-sequence()
Summary	Recursively deletes a file or directory specified by $path. The optional parameter $recursive specifies whether sub-directories will be deleted, too.
Errors	FILE0001: the specified path does not exist. FILE9999: the operation fails for some other reason.

file:write

Signatures	file:write($path as xs:string, $items as item()*) as empty-sequence() file:write($path as xs:string, $items as item()*, $params as item()) as empty-sequence()
Summary	Writes a serialized sequence of items to the specified file. If the file already exists, it will be overwritten. The $params argument contains serialization parameters (see Serialization for more details), which can either be specified as children of an <output:serialization-parameters/> element, as defined for the fn:serialize() function; e.g.: <output:serialization-parameters> <output:method value='xml'/> <output:cdata-section-elements value="div"/> ... </output:serialization-parameters> as map, which contains all key/value pairs: map { "method" := "xml", "cdata-section-elements" := "div", ... }
Errors	FILE0003: the parent of specified path is no directory. FILE0004: the specified path is a directory. FILE9999: the operation fails for some other reason.

file:write-binary

Template:Mark argument $offset added.

Signatures	file:write-binary($path as xs:string, $value as xs:anyAtomicType) as empty-sequence() file:write-binary($path as xs:string, $value as xs:anyAtomicType, $offset as xs:integer) as empty-sequence()
Summary	Writes a binary item (xs:base64Binary, xs:hexBinary) to the specified file. If the file already exists, it will be overwritten. If $offset is specified, data will be written to this file position. An existing file may be resized by that operation.
Errors	FILE0003: the parent of specified path is no directory. FILE0004: the specified path is a directory. FILE0006: the offset is negative, or it exceeds the current file size. FILE9999: the operation fails for some other reason.

file:write-text

Signatures	file:write-text($path as xs:string, $value as xs:string) as empty-sequence() file:write-text($path as xs:string, $value as xs:string, $encoding as xs:string) as empty-sequence()
Summary	Writes a string to the specified file. If the file already exists, it will be overwritten. The optional parameter $encoding defines the output encoding (default: UTF-8).
Errors	FILE0003: the parent of specified path is no directory. FILE0004: the specified path is a directory. FILE0005: the specified encoding is not supported, or unknown. FILE9999: the operation fails for some other reason.

file:write-text-lines

Signatures	file:write-text-lines($path as xs:string, $values as xs:string*) as empty-sequence() file:write-text-lines($path as xs:string, $values as xs:string*, $encoding as xs:string) as empty-sequence()
Summary	Writes a sequence of strings to the specified file, each followed by the system specific newline character. If the file already exists, it will be overwritten. The optional parameter $encoding defines the output encoding (default: UTF-8).
Errors	FILE0003: the parent of specified path is no directory. FILE0004: the specified path is a directory. FILE0005: the specified encoding is not supported, or unknown. FILE9999: the operation fails for some other reason.

file:append

Signatures	file:append($path as xs:string, $items as item()*) as empty-sequence() file:append($path as xs:string, $items as item()*, $params as item()) as empty-sequence()
Summary	Appends a serialized sequence of items to the specified file. If the file does not exists, a new file is created.
Errors	FILE0003: the parent of specified path is no directory. FILE0004: the specified path is a directory. FILE9999: the operation fails for some other reason.

file:append-binary

Signatures	file:append-binary($path as xs:string, $value as xs:anyAtomicType) as empty-sequence()
Summary	Appends a binary item (xs:base64Binary, xs:hexBinary) to the specified file. If the file does not exists, a new one is created.
Errors	FILE0003: the parent of specified path is no directory. FILE0004: the specified path is a directory. FILE9999: the operation fails for some other reason.

file:append-text

Signatures	file:append-text($path as xs:string, $value as xs:string) as empty-sequence() file:append-text($path as xs:string, $value as xs:string, $encoding as xs:string) as empty-sequence()
Summary	Appends a string to a file specified by $path. If the specified file does not exists, a new file is created. The optional parameter $encoding defines the output encoding (default: UTF-8).
Errors	FILE0003: the parent of specified path is no directory. FILE0004: the specified path is a directory. FILE0005: the specified encoding is not supported, or unknown. FILE9999: the operation fails for some other reason.

file:append-text-lines

Signatures	file:append-text-lines($path as xs:string, $values as xs:string*) as empty-sequence() file:append-text-lines($path as xs:string, $values as xs:string*, $encoding as xs:string) as empty-sequence()
Summary	Appends a sequence of strings to the specified file, each followed by the system specific newline character. If the specified file does not exists, a new file is created. The optional parameter $encoding defines the output encoding (default: UTF-8).
Errors	FILE0003: the parent of specified path is no directory. FILE0004: the specified path is a directory. FILE0005: the specified encoding is not supported, or unknown. FILE9999: the operation fails for some other reason.

file:copy

Signatures	file:copy($source as xs:string, $target as xs:string) as empty-sequence()
Summary	Copies a file specified by $source to the file or directory specified by $target. If the target file already exists, it will be overwritten. No operation will be performed if the source and target path are equal.
Errors	FILE0001: the specified source does not exist. FILE0002: the specified source is a directory and the target is a file. FILE0003: the parent of the specified target is no directory. FILE9999: the operation fails for some other reason.

file:move

Signatures	file:move($source as xs:string, $target as xs:string) as empty-sequence()
Summary	Moves or renames the file or directory specified by $source to the path specified by $target. If the target file already exists, it will be overwritten. No operation will be performed if the source and target path are equal.
Errors	FILE0001: the specified source does not exist. FILE0002: the specified source is a directory and the target is a file. FILE0003: the parent of the specified target is no directory. FILE9999: the operation fails for some other reason.

File Properties

file:exists

Signatures	file:exists($path as xs:string) as xs:boolean
Summary	Returns an xs:boolean indicating whether a file or directory specified by $path exists in the file system.

file:is-dir

Signatures	file:is-dir($path as xs:string) as xs:boolean
Summary	Returns an xs:boolean indicating whether the argument $path points to an existing directory.

file:is-file

Signatures	file:is-file($path as xs:string) as xs:boolean
Summary	Returns an xs:boolean indicating whether the argument $path points to an existing file.

file:last-modified

Signatures	file:last-modified($path as xs:string) as xs:dateTime
Summary	Retrieves the timestamp of the last modification of the file or directory specified by $path.
Errors	FILE0001: the specified path does not exist.

file:size

Signatures	file:size($file as xs:string) as xs:integer
Summary	Returns the size, in bytes, of the file specified by $path.
Errors	FILE0001: the specified file does not exist. FILE0004: the specified file points to a directory.

Path Functions

file:base-name

Signatures	file:base-name($path as xs:string) as xs:string file:base-name($path as xs:string, $suffix as xs:string) as xs:string
Summary	Returns the base-name of the path specified by $path, which is the component after the last directory separator. If $suffix is specified, it will be trimmed from the end of the result.

file:dir-name

Signatures	file:dir-name($path as xs:string) as xs:string
Summary	Returns the parent directory of the path specified by $path, which is the component before the last directory separator.
Examples	file:dir-name(static-base-uri()) returns the directory of the current XQuery module.

file:path-to-native

Signatures	file:path-to-native($path as xs:string) as xs:string
Summary	Transforms the $path argument to its native representation on the operating system.
Errors	FILE9999: the specified path cannot be transformed to its native representation.

file:resolve-path

Signatures	file:resolve-path($path as xs:string) as xs:string
Summary	Transforms the $path argument to an absolute operating system path.

file:path-to-uri

Signatures	file:path-to-uri($path as xs:string) as xs:string
Summary	Transforms the path specified by $path into a URI with the file:// scheme.

System Properties

file:dir-separator

Signatures	file:dir-separator() as xs:string
Summary	Returns the directory separator used by the operating system, such as / or \.

file:path-separator

Signatures	file:path-separator() as xs:string
Summary	Returns the path separator used by the operating system, such as ; or :.

file:line-separator

Signatures	file:line-separator() as xs:string
Summary	Returns the line separator used by the operating system, such as 
, 
 or 
.

file:temp-dir

Signatures	file:temp-dir() as xs:string
Summary	Returns the system’s default temporary-file directory.

Errors

Code	Description
FILE0001	A specified path does not exist.
FILE0002	A file with the same path already exists.
FILE0003	The specified path does not point to a directory.
FILE0004	The specified path is a directory.
FILE0005	The specified encoding is not supported, or unknown.
FILE0006	The specified offset or length is negative, or the chosen values would exceed the file bounds.
FILE9999	The operation fails for some other reason specific to the operating system.

Changelog

Version 7.8

• Updated: file:read-binary, file:write-binary: $offset and $length arguments added.

Version 7.7

• Added: file:create-temp-dir, file:create-temp-file, file:temp-dir
• Updated: all returned strings that refer to existing directories will be suffixed with a directory separator.

Version 7.3

• Added: file:append-text, file:write-text, file:append-text-lines, file:write-text-lines, file:line-separator
• Aligned with latest specification: $file:directory-separator → file:dir-separator, $file:path-separator → file:path-separator, file:is-directory → file:is-dir, file:create-directory → file:create-dir
• Updated: file:write-binary, file:append-binary: output limited to a single value

Version 7.2.1

• Updated: file:delete: $recursive parameter added to prevent sub-directories from being accidentally deleted.
• Fixed: file:list now returns relative instead of absolute paths.