Main Page » XQuery » Functions » File Functions

File Functions

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

This module is based on the EXPath File Module. The following enhancements have not been added to the specification yet:

Function	Description
`file:descendants`	new function
`file:is-absolute`	new function
`file:list-roots`	new function
`file:read-text`, `file:read-text-lines`	`$fallback` argument added
`file:read-text-lines`	`$offset` and `$length` arguments added
`file:resolve-path`	`$base` argument added

Conventions

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

For serialization parameters, the http://www.w3.org/2010/xslt-xquery-serialization namespace is used, which is statically bound to the output prefix.

The error invalid-path is raised if a path is invalid.

File Paths

All file paths are resolved against the current working directory (the directory from which BaseX or, more generally, the Java Virtual Machine, was started). This directory can be retrieved via file:base-dir.
A path can be specified as local filesystem path or as file URI.
Returned strings that refer to existing directories are suffixed with a directory separator.

Read Operations

`file:list`

Signature

file:list(
  $dir        as xs:string,
  $recursive  as xs:boolean?  := false(),
  $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. If $recursive is set to true, subdirectories will be traversed. 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

`io-error`	The operation fails for some other reason specific to the operating system.
`no-dir`	The specified path does not point to a directory.
`not-found`	A specified path does not exist.

Examples

let $root := 'path/to/files/'
for $file in file:list($root, true(), '*.txt')
let $path := $root || $file
where file:size($path) > 1000000
return file:read-text($path)

Return the contents of large .txt files located in a specific directory and its subdirectories.

`file:children`

Signature

file:children(
  $dir  as xs:string
) as xs:string*

Summary Returns the full paths to all files and directories found in the specified $dir. The inverse function is file:parent. The returned paths start with the specified directory. The related function file:list returns relative file paths.

Errors

`io-error`	The operation fails for some other reason specific to the operating system.
`no-dir`	The specified path does not point to a directory.
`not-found`	A specified path does not exist.

Examples

for $file in file:children('path/to/files/')
where matches($file, '.txt', 'i') and file:size($file) > 1000000
return file:read-text($file)

Return the contents of large .txt files located in a specific directory.

`file:descendants`

Signature

file:descendants(
  $dir  as xs:string
) as xs:string*

Summary Returns the full paths to all files and directories found in the specified $dir and its subdirectories. . The returned paths start with the specified directory. The related function file:list creates relative file paths.

Errors

`io-error`	The operation fails for some other reason specific to the operating system.
`no-dir`	The specified path does not point to a directory.
`not-found`	A specified path does not exist.

Examples

for $file in file:descendants('path/to/files/')
where matches($file, '.txt', 'i') and file:size($file) > 1000000
return file:read-text($file)

Return the contents of all .txt files located in a specific directory and its subdirectories.

`file:list-roots`

Signature	file:list-roots() as xs:string*
Summary	Returns all root directories of the file system. On a UNIX-based system, the result is usually a single slash, denoting the root directory `/`.

`file:read-binary`

Signature

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 lazy xs:base64Binary item. The optional parameters $offset and $length can be used to read chunks of a file.

Errors

`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`not-found`	A specified path does not exist.
`out-of-range`	The specified offset or length is negative, or the chosen values would exceed the file bounds.

Examples

lazy:cache(file:read-binary("config.data"))

Enforces the file access (otherwise, it will be delayed until requested first).

`file:read-text`

Signature

file:read-text(
  $path      as xs:string,
  $encoding  as xs:string?   := (),
  $fallback  as xs:boolean?  := false()
) as xs:string

Summary

Reads the textual contents of the file specified by $path and returns it as lazy xs:string item:

The UTF-8 default encoding can be overwritten with the optional $encoding argument.
By default, invalid XML characters will be rejected. If $fallback is enabled, the characters will be replaced with the Unicode replacement character FFFD (�).

Errors

`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`not-found`	A specified path does not exist.
`unknown-encoding`	The specified encoding is not supported, or unknown.

Examples

lazy:cache(file:read-text("ids.txt"))

Enforces the file access (otherwise, it will be delayed until requested first).

`file:read-text-lines`

Signature

file:read-text-lines(
  $path      as xs:string,
  $encoding  as xs:string?   := (),
  $fallback  as xs:boolean?  := false(),
  $offset    as xs:integer?  := (),,
  $length    as xs:integer?  := ()
) 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 UTF-8 default encoding can be overwritten with the optional $encoding argument.
By default, invalid characters will be rejected. If $fallback is set to true, these characters will be replaced with the Unicode replacement character FFFD (�).

The lines to be read can be restricted with the optional parameters $offset and $length.

Errors

`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`not-found`	A specified path does not exist.
`unknown-encoding`	The specified encoding is not supported, or unknown.

Write Operations

`file:create-dir`

Signature

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

Summary Creates the directory specified by $dir if it does not already exist. Non-existing parent directories will be created as well.

Errors

`exists`	A file with the same path already exists.
`io-error`	The operation fails for some other reason specific to the operating system.

`file:create-temp-dir`

Signature

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

`io-error`	The operation fails for some other reason specific to the operating system.
`no-dir`	The specified path does not point to a directory.

`file:create-temp-file`

Signature

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

`io-error`	The operation fails for some other reason specific to the operating system.
`no-dir`	The specified path does not point to a directory.

`file:delete`

Signature

file:delete(
  $path       as xs:string,
  $recursive  as xs:boolean?  := false()
) as empty-sequence()

Summary Recursively deletes a file or directory specified by $path. The optional parameter $recursive specifies whether subdirectories will be deleted, too.

Errors

`io-error`	The operation fails for some other reason specific to the operating system.
`not-found`	A specified path does not exist.

`file:write`

Signature

file:write(
  $path     as xs:string,
  $input    as item()*,
  $options  as (element(output:serialization-parameters) | map(*))?  := ()
) as empty-sequence()

Summary Serializes $input and writes the result to the file located at $path. If the file already exists, it will be overwritten. The $options argument contains serialization parameters (see fn:serialize).

Errors

`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`no-dir`	The specified path does not point to a directory.

Examples

file:write('data.bin', xs:hexBinary('414243'))

Writes a hex representation to the specified file.

file:write('data.bin', xs:hexBinary('414243'), { 'method': 'basex' })

Writes binary data to the specified file (see Serialization for more details).

`file:write-binary`

Signature

file:write-binary(
  $path    as xs:string,
  $value   as (xs:base64Binary|xs:hexBinary),
  $offset  as xs:integer                      := ()
) as empty-sequence()

Summary Writes a binary $value to the file located at $path. If the file already exists, it will be overwritten. If $offset is specified, data will be written at this file position. An existing file may be resized by that operation.

Errors

`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`no-dir`	The specified path does not point to a directory.
`out-of-range`	The specified offset or length is negative, or the chosen values would exceed the file bounds.

`file:write-text`

Signature

file:write-text(
  $path      as xs:string,
  $value     as xs:string,
  $encoding  as xs:string?  := ()
) as empty-sequence()

Summary Writes a string $value to the file located at $path. If the file already exists, it will be overwritten. The optional parameter $encoding defines the output encoding (default: UTF-8).

Errors

`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`no-dir`	The specified path does not point to a directory.
`unknown-encoding`	The specified encoding is not supported, or unknown.

`file:write-text-lines`

Signature

file:write-text-lines(
  $path      as xs:string,
  $values    as xs:string*,
  $encoding  as xs:string?  := ()
) as empty-sequence()

Summary Writes a sequence of string $values to the file located at $path, 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

`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`no-dir`	The specified path does not point to a directory.
`unknown-encoding`	The specified encoding is not supported, or unknown.

`file:append`

Signature

file:append(
  $path     as xs:string,
  $input    as item()*,
  $options  as map(*)?    := {}
) as empty-sequence()

Summary Serializes $input and appends the result to the file located at $path, with the supplied $options as serialization parameters. If the file does not exist, a new file is created.

Errors

`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`no-dir`	The specified path does not point to a directory.

`file:append-binary`

Signature

file:append-binary(
  $path   as xs:string,
  $value  as (xs:base64Binary|xs:hexBinary)
) as empty-sequence()

Summary Appends a binary $value to the file located at $path. If the file does not exists, a new one is created.

Errors

`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`no-dir`	The specified path does not point to a directory.

`file:append-text`

Signature

file:append-text(
  $path      as xs:string,
  $value     as xs:string,
  $encoding  as xs:string?  := ()
) as empty-sequence()

Summary Appends a string $value to the file located at $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

`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`no-dir`	The specified path does not point to a directory.
`unknown-encoding`	The specified encoding is not supported, or unknown.

`file:append-text-lines`

Signature

file:append-text-lines(
  $path      as xs:string,
  $values    as xs:string*,
  $encoding  as xs:string?  := ()
) as empty-sequence()

Summary Appends a sequence of string $values to the file located at $path, 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

`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`no-dir`	The specified path does not point to a directory.
`unknown-encoding`	The specified encoding is not supported, or unknown.

`file:copy`

Signature

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

Summary Copies a file or directory 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

`exists`	A file with the same path already exists.
`io-error`	The operation fails for some other reason specific to the operating system.
`no-dir`	The specified path does not point to a directory.
`not-found`	A specified path does not exist.

`file:move`

Signature

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

`exists`	A file with the same path already exists.
`io-error`	The operation fails for some other reason specific to the operating system.
`no-dir`	The specified path does not point to a directory.
`not-found`	A specified path does not exist.

Examples

file:move('/projects/new/octopus', '/projects/new/septimus'),
$path ! file:move(., file:parent(.) || $newName)

When renaming a file, remember that relative file paths are resolved against the current working directory. Files can be renamed as follows.

File Properties

`file:exists`

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

Signature	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-absolute`

Signature	file:is-absolute( $path as xs:string ) as xs:boolean
Summary	Returns an `xs:boolean` indicating whether the argument `$path` is absolute. The behavior of this function depends on the operating system: On Windows, an absolute path starts with the drive letter and a colon, whereas on Unix-based systems it starts with a slash.

`file:is-file`

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

Signature

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

not-found A specified path does not exist.

`file:size`

Signature

file:size(
  $path  as xs:string
) as xs:integer

Summary Returns the size, in bytes, of the file specified by $path, or 0 for directories.

Errors

not-found A specified path does not exist.

Path Functions

`file:name`

Signature	file:name( $path as xs:string ) as xs:string
Summary	Returns the name of a file or directory specified by `$path`. An empty string is returned if the path points to the root directory.

`file:parent`

Signature	file:parent( $path as xs:string ) as xs:string?
Summary	Returns the absolute path to the parent directory of a file or directory specified by `$path`. An empty sequence is returned if the path points to a root directory. The inverse function is `file:children`.
Examples	`file:parent(static-base-uri())` Returns the directory of the current XQuery module.

`file:path-to-native`

Signature

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

`io-error`	The operation fails for some other reason specific to the operating system.
`not-found`	A specified path does not exist.

`file:resolve-path`

Signature

file:resolve-path(
  $path  as xs:string,
  $base  as xs:string  := ()
) as xs:string

Summary Transforms the $path argument to an absolute operating system path. If the path is relative, and if an absolute $base path is specified, it will be resolved against this path.

Errors

is-relative The specified path is relative (and must be absolute).

Examples

file:resolve-path('file.txt', 'C:/Temp/')

Returns C:/Temp/file.txt (on a Windows system).

file:resolve-path('file.txt', 'C:/Temp')

Returns C:/file.txt (on a Windows system).

file:resolve-path('file.txt', 'Temp')

Raises an error.

`file:path-to-uri`

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

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

`file:path-separator`

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

`file:line-separator`

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

`file:temp-dir`

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

`file:current-dir`

Signature	file:current-dir() as xs:string
Summary	Returns the current working directory, i.e., the directory from which the query processor was started. This function returns the same result as the function call `file:resolve-path("")`.

`file:base-dir`

Signature	file:base-dir() as xs:string?
Summary	Returns the parent directory of the static base URI. If the static base URI is undefined or does not point to a local resource, it returns the empty sequence. Otherwise, it returns the same result as `file:parent(static-base-uri())`.

Errors

Code	Description
`exists`	A file with the same path already exists.
`invalid-path`	A specified path is invalid.
`io-error`	The operation fails for some other reason specific to the operating system.
`is-dir`	The specified path is a directory.
`is-relative`	The specified path is relative (and must be absolute).
`no-dir`	The specified path does not point to a directory.
`not-found`	A specified path does not exist.
`out-of-range`	The specified offset or length is negative, or the chosen values would exceed the file bounds.
`unknown-encoding`	The specified encoding is not supported, or unknown.

Changelog

Version 11.0

Added: file:list-roots

Version 9.3

Added: file:descendants

Version 9.0

Updated: file:read-text-lines: $offset and $length arguments added.

Version 8.5

Updated: file:read-text, file:read-text-lines: $fallback argument added.

Version 8.2

Added: file:is-absolute
Updated: file:resolve-path: base argument added

Version 8.0

Added: file:current-dir, file:base-dir, file:children

Version 7.8

Added: file:parent, file:name
Updated: error codes; file:read-binary, file:write-binary: $offset and $length arguments added.
Deleted: file:base-name, file:dir-name

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
Updated: file:write-binary, file:append-binary: output limited to a single value
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

Version 7.2.1

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

⚡Generated with XQuery