File Module

This XQuery Module contains functions and variables related to file system operations, such as listing, reading, or writing files. All functions are preceded by the file: prefix, which is linked to the statically declared http://expath.org/ns/file namespace. This module has been aligned with the latest EXPath File Module draft from 2011 (expected to be online soon).

$file:directory-separator

Signatures	$file:directory-separator as xs:string
Summary	This variable returns the directory separator used by the operating system, such as "/" or "\".

$file:path-separator

Signatures	$file:path-separator as xs:string
Summary	This variable returns the path separator used by the operating system, such as ";" or ":".

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-directory

Signatures	file:is-directory($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	FOFL0001 is raised if 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	FOFL0001 is raised if the specified file does not exist. FOFL0004 is raised if the specified file points to a directory.

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.

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	FOFL0000 is raised if 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.

file:list

Signatures	file:list($directory as xs:string) as xs:string* file:list($directory as xs:string, $recursive as xs:boolean) as xs:string* file:list($directory as xs:string, $recursive as xs:boolean, $pattern as xs:string) as xs:string*
Summary	Lists all files and directories found in the specified $directory. 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	FOFL0003 is raised if the specified path does not point to a directory. FOFL0000 is raised if the operation fails for some other reason.

file:create-directory

Signatures	file:create-directory($directory as xs:string) as empty-sequence()
Summary	Recursively creates the directories specified by $directory.
Errors	FOFL0002 is raised if a file with the same path already exists. FOFL0000 is raised if the operation fails for some other reason.

file:delete

Template:Mark $recursive parameter added to prevent sub-directories from being accidentally deleted.

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	FOFL0001 is raised if the specified path does not exist. FOFL0000 is raised if the operation fails for some other reason.

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 a xs:string. The optional parameter $encoding defines the encoding of the file.
Errors	FOFL0001 is raised if the specified file does not exist. FOFL0004 is raised if the specified path is a directory. FOFL0005 is raised if the specified encoding is not supported, or unknown. FOFL0000 is raised if the operation fails for some other reason.

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	FOFL0001 is raised if the specified file does not exist. FOFL0004 is raised if the specified path is a directory. FOFL0005 is raised if the specified encoding is not supported, or unknown. FOFL0000 is raised if the operation fails for some other reason.

file:read-binary

Signatures	file:read-binary($path as xs:string) as xs:base64Binary
Summary	Reads the binary content of the file specified by $path and returns as a xs:base64Binary.
Errors	FOFL0001 is raised if the specified file does not exist. FOFL0004 is raised if the specified path is a directory. FOFL0000 is raised if 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 xs:node()*) as empty-sequence()
Summary	Writes a sequence of $items to a file specified by $path. If the specified file already exists, it will be overwritten. The optional argument $params is used to set the serialization parameters (see Serialization for more details).It can be specified as element(serialization-parameters): <serialization-parameters/> must be used as root element, and the parameters are specified as child nodes, with the element name representing the serialization parameter and the attribute value representing its value: <serialization-parameters xmlns="http://www.w3.org/2010/xslt-xquery-serialization">   <method value='xml'/>   <cdata-section-elements value="div"/>   ... </serialization-parameters> map structure: all parameters can be directly represented as key/value pairs: map { "method" := "xml", "cdata-section-elements" := "div", ... }
Errors	FOFL0004 is raised if the specified path is a directory. FOFL0000 is raised if the operation fails for some other reason.

file:write-binary

Signatures	file:write-binary($path as xs:string, $items as xs:base64Binary*) as empty-sequence()
Summary	Writes a sequence of xs:basex64Binary $items to a file specified by $path. If the specified file already exists, it will be overwritten.
Errors	FOFL0004 is raised if the specified path is a directory. FOFL0000 is raised if 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 xs:node()*) as empty-sequence()
Summary	Appends a sequence of $items to a file specified by $path. If the specified file does not exists, a new file is created.
Errors	FOFL0004 is raised if the specified path is a directory. FOFL0000 is raised if the operation fails for some other reason.

file:append-binary

Signatures	file:append-binary($path as xs:string, $items as xs:base64Binary*) as empty-sequence()
Summary	Appends a sequence of xs:basex64Binary $items to a file specified by $path. If the specified file does not exists, a new file is created.
Errors	FOFL0004 is raised if the specified path is a directory. FOFL0000 is raised if 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 represents an existing file, it will be overwritten. No operation will be performed if the source and target path are equal.
Errors	FOFL0001 is raised if the specified source does not exist. FOFL0002 is raised if the specified source is a directory and the target is a file. FOFL0003 is raised if the parent of the specified target is no directory. FOFL0000 is raised if 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. No operation will be performed if the source and target path are equal.
Errors	FOFL0001 is raised if the specified source does not exist. FOFL0002 is raised if the specified source is a directory and the target is a file. FOFL0003 is raised if the parent of the specified target is no directory. FOFL0000 is raised if the operation fails for some other reason.

Changelog

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.