File Module

http://expath.org/ns/file

This module is statically bound to the prefix "file".

Description
Functions to perform file system related operations such as listing, reading, or writing files or directories.
Specified: http://expath.org/spec/file
Functions

file:exists

Signature
file:exists($path as xs:string) as xs:boolean
Description

Tests if the file or directory pointed by $path exists.

This function is ·nondeterministic·.

back to top

file:is-dir

Signature
file:is-dir($path as xs:string) as xs:boolean
Description

Tests if $path points to a directory. On UNIX-based systems the root and the volume roots are considered directories.

This function is ·nondeterministic·.

back to top

file:is-file

Signature
file:is-file($path as xs:string) as xs:boolean
Description

Tests if $path points to a file.

This function is ·nondeterministic·.

back to top

file:last-modified

Signature
file:last-modified($path as xs:string) as xs:dateTime
Description

Returns the last modification time of a file or directory.

This function is ·nondeterministic·.

back to top

file:size

Signature
file:size($file as xs:string) as xs:integer
Description

Returns the byte size of a file, or the value 0 for directories.

This function is ·nondeterministic·.

back to top

file:append

Signature
file:append($file as xs:string, $items as item()*) as empty-sequence()
file:append($file as xs:string, $items as item()*, $params as item()) as empty-sequence()
Description

Appends 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. This consists of an output:serialization-parameters element or map. 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.

This function is ·nondeterministic·.

back to top

file:append-binary

Signature
file:append-binary($file as xs:string, $value as xs:base64Binary) as empty-sequence()
Description

Appends 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.

This function is ·nondeterministic·.

back to top

file:append-text

Signature
file:append-text($file as xs:string, $value as xs:string) as empty-sequence()
file:append-text($file as xs:string, $value as xs:string, $encoding as xs:string) as empty-sequence()
Description

Appends 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.

This function is ·nondeterministic·.

back to top

file:append-text-lines

Signature
file:append-text-lines($file as xs:string, $values as xs:string*) as empty-sequence()
file:append-text-lines($file as xs:string, $lines as xs:string*, $encoding as xs:string) as empty-sequence()
Description

Appends 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.

This function is ·nondeterministic·.

back to top

file:children

Signature
file:children($path as xs:string) as xs:string*
Description

Returns the paths of all files and directories that are located in the given directory. The order of the items in the resulting sequence is not defined. The "." and ".." items are never returned.

The inverse function is file:parent; a related function is file:list.

This function is ·nondeterministic·.

back to top

file:copy

Signature
file:copy($source as xs:string, $target as xs:string) as empty-sequence()
Description

Copies a file or a directory given a source and a target path/URI. The following cases may occur if $source points to a file:

  1. if $target does not exist, it will be created.
  2. if $target is a file, it will be overwritten.
  3. 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:

  1. 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.
  2. if $target is a directory, the source directory with all its files will be copied into the target directory. At each level, if a file already exists in the target with the same name as in the source, it is overwritten. If a directory already exists in the target with the same name as in the source, it is not removed, it is recursed in place (if it does not exist, it is created before recursing).

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

This function is ·nondeterministic·.

back to top

file:create-dir

Signature
file:create-dir($dir as xs:string) as empty-sequence()
Description

Creates 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.

This function is ·nondeterministic·.

back to top

file:create-temp-dir

Signature
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
Description

Creates a temporary directory and all non-existing parent directories and returns the full path to the created directory.

The temporary directory will not be automatically deleted after query execution. It is guaranteed to not already exist when the function is called.

If $dir is not given, the directory will be created inside the system-dependent default temporary-file directory.

This function is ·nondeterministic·.

back to top

file:create-temp-file

Signature
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
Description

Creates a temporary file and all non-existing parent directories and returns the full path to the created file.

The temporary file will not be automatically deleted after query execution. It is guaranteed to not already exist when the function is called.

If $dir is not given, the directory will be created inside the system-dependent default temporary-file directory.

This function is ·nondeterministic·.

back to top

file:delete

Signature
file:delete($path as xs:string) as empty-sequence()
file:delete($path as xs:string, $recursive as xs:boolean) as empty-sequence()
Description

Deletes 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.

This function is ·nondeterministic·.

back to top

file:list

Signature
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*
Description

Lists 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.

A related function is file:children.

This function is ·nondeterministic·.

back to top

file:move

Signature
file:move($source as xs:string, $target as xs:string) as empty-sequence()
Description

Moves a file or a directory given a source and a target path/URI. The following cases may occur if $source points to a file:

  1. if $target does not exist, it will be created.
  2. if $target is a file, it will be overwritten.
  3. 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:

  1. 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.
  2. if $target is a directory, the source directory with all its files will be moved into the target directory. If the target directory contains a directory with the same name as the source, the error [file:is-dir]is raised.

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

This function is ·nondeterministic·.

back to top

file:path-to-uri

Signature
file:path-to-uri($path as xs:string) as xs:anyURI
Description

Transforms 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.

This function is ·deterministic· (no path existence check is made).

back to top

file:read-binary

Signature
file:read-binary($file as xs:string) as xs:base64Binary
file:read-binary($file as xs:string, $offset as xs:integer) as xs:base64Binary
file:read-binary($file as xs:string, $offset as xs:integer, $length as xs:integer) as xs:base64Binary
Description

Returns the content of a file in its Base64 representation.

The optional parameters $offset and $length can be used to read chunks of a file.

This function is ·nondeterministic·.

back to top

file:read-text

Signature
file:read-text($file as xs:string) as xs:string
file:read-text($file as xs:string, $encoding as xs:string) as xs:string
Description

Returns the content of a file in its string representation.

The optional parameter $encoding, if not provided, is considered to be UTF-8.

This function is ·nondeterministic·.

back to top

file:read-text-lines

Signature
file:read-text-lines($file as xs:string) as xs:string*
file:read-text-lines($file as xs:string, $encoding as xs:string) as xs:string*
Description

Returns 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.

This function is ·nondeterministic·.

back to top

file:write

Signature
file:write($file as xs:string, $items as item()*) as empty-sequence()
file:write($file as xs:string, $items as item()*, $params as item()) as empty-sequence()
Description

Writes a sequence of items to a file. If $file already exists, it will be overwritten; otherwise, it 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. This consists of an output:serialization-parameters element or map. 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.

This function is ·nondeterministic·.

back to top

file:write-binary

Signature
file:write-binary($file as xs:string, $value as xs:base64Binary) as empty-sequence()
file:write-binary($file as xs:string, $value as xs:base64Binary, $offset as xs:integer) as empty-sequence()
Description

Writes a Base64 item as binary to a file. If $file already exists, it will be overwritten; otherwise, it will be created.

If the optional parameter $offset is specified, data will be written to this file position. An existing file may be resized by that operation.

The function returns the empty sequence if the operation is successful.

This function is ·nondeterministic·.

back to top

file:write-text

Signature
file:write-text($file as xs:string, $value as xs:string) as empty-sequence()
file:write-text($file as xs:string, $value as xs:string, $encoding as xs:string) as empty-sequence()
Description

Writes 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.

This function is ·nondeterministic·.

back to top

file:write-text-lines

Signature
file:write-text-lines($file as xs:string, $values as xs:string*) as empty-sequence()
file:write-text-lines($file as xs:string, $values as xs:string*, $encoding as xs:string) as empty-sequence()
Description

Writes a sequence of strings to a file, each followed by the system-dependent newline character. If $file already exists, it will be overwritten; otherwise, it 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.

This function is ·nondeterministic·.

back to top

file:name

Signature
file:name($path as xs:string) as xs:string
Description

Returns the name of a file or directory.

An empty string is returned if the path points to the root directory, or if it contains no directory separators.

This function is ·deterministic· (no path existence check is made).

back to top

file:parent

Signature
file:parent($path as xs:string) as xs:string?
Description

Transforms the given path into an absolute path, as specified by file:resolve-path, and returns the parent directory.

The inverse function is file:children.

An empty sequence is returned if the path points to a root directory.

This function is ·nondeterministic·.

back to top

file:path-to-native

Signature
file:path-to-native($path as xs:string) as xs:string
Description

Transforms 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.

If the resulting path points to a directory, it will be suffixed with the system-specific directory separator.

This function is ·nondeterministic·.

back to top

file:resolve-path

Signature
file:resolve-path($path as xs:string) as xs:string
Description

Transforms a relative path into an absolute operating system path by resolving it against the current working directory.

If the resulting path points to a directory, it will be suffixed with the system-specific directory separator.

This function is ·nondeterministic·.

back to top

file:dir-separator

Signature
file:dir-separator() as xs:string
Description

Returns the value of the operating system-specific directory separator, which usually is / on UNIX-based systems and \ on Windows systems.

This function is ·nondeterministic·.

back to top

file:path-separator

Signature
file:path-separator() as xs:string
Description

Returns the value of the operating system-specific path separator, which usually is : on UNIX-based systems and ; on Windows systems.

This function is ·nondeterministic·.

back to top

file:line-separator

Signature
file:line-separator() as xs:string
Description

Returns the value of the operating system-specific line separator, which usually is 
 on UNIX-based systems, 
 on Windows systems and 
 on Mac systems.

This function is ·nondeterministic·.

back to top

file:temp-dir

Signature
file:temp-dir() as xs:string
Description

Returns the path to the default temporary-file directory of an operating system.

This function is ·nondeterministic·.

back to top

file:current-dir

Signature
file:current-dir() as xs:string
Description

Returns the current working directory. - This function returns the same result as the function call file:resolve-path('.').

back to top

file:base-dir

Signature
file:base-dir() as xs:string?
Description

Returns the parent directory of the static base URI. If the Base URI property is undefined, the empty sequence is returned. - If a static base URI exists, and it points to a local file path, this function returns the same result as the expression file:parent(static-base-uri()).

back to top