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*
SummaryLists 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-errorThe operation fails for some other reason specific to the operating system.
no-dirThe specified path does not point to a directory.
not-foundA 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*
SummaryReturns 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-errorThe operation fails for some other reason specific to the operating system.
no-dirThe specified path does not point to a directory.
not-foundA 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*
SummaryReturns 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-errorThe operation fails for some other reason specific to the operating system.
no-dirThe specified path does not point to a directory.
not-foundA 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*
SummaryReturns 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
SummaryReads 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-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
not-foundA specified path does not exist.
out-of-rangeThe 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
SummaryReads 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-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
not-foundA specified path does not exist.
unknown-encodingThe 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*
SummaryReads 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-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
not-foundA specified path does not exist.
unknown-encodingThe specified encoding is not supported, or unknown.

Write Operations

file:create-dir

Signature
file:create-dir(
  $dir  as xs:string
) as empty-sequence()
SummaryCreates the directory specified by $dir if it does not already exist. Non-existing parent directories will be created as well.
Errors
existsA file with the same path already exists.
io-errorThe 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
SummaryCreates 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-errorThe operation fails for some other reason specific to the operating system.
no-dirThe 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
SummaryCreates 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-errorThe operation fails for some other reason specific to the operating system.
no-dirThe 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()
SummaryRecursively deletes a file or directory specified by $path. The optional parameter $recursive specifies whether subdirectories will be deleted, too.
Errors
io-errorThe operation fails for some other reason specific to the operating system.
not-foundA 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()
SummarySerializes $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-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
no-dirThe 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()
SummaryWrites 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-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
no-dirThe specified path does not point to a directory.
out-of-rangeThe 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()
SummaryWrites 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-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
no-dirThe specified path does not point to a directory.
unknown-encodingThe 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()
SummaryWrites 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-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
no-dirThe specified path does not point to a directory.
unknown-encodingThe 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()
SummarySerializes $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-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
no-dirThe 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()
SummaryAppends a binary $value to the file located at $path. If the file does not exists, a new one is created.
Errors
io-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
no-dirThe 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()
SummaryAppends 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-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
no-dirThe specified path does not point to a directory.
unknown-encodingThe 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()
SummaryAppends 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-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
no-dirThe specified path does not point to a directory.
unknown-encodingThe specified encoding is not supported, or unknown.

file:copy

Signature
file:copy(
  $source  as xs:string,
  $target  as xs:string
) as empty-sequence()
SummaryCopies 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
existsA file with the same path already exists.
io-errorThe operation fails for some other reason specific to the operating system.
no-dirThe specified path does not point to a directory.
not-foundA specified path does not exist.

file:move

Signature
file:move(
  $source  as xs:string,
  $target  as xs:string
) as empty-sequence()
SummaryMoves 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
existsA file with the same path already exists.
io-errorThe operation fails for some other reason specific to the operating system.
no-dirThe specified path does not point to a directory.
not-foundA 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
SummaryReturns 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
SummaryReturns 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
SummaryReturns 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
SummaryReturns 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
SummaryRetrieves the timestamp of the last modification of the file or directory specified by $path.
Errors
not-foundA specified path does not exist.

file:size

Signature
file:size(
  $path  as xs:string
) as xs:integer
SummaryReturns the size, in bytes, of the file specified by $path, or 0 for directories.
Errors
not-foundA specified path does not exist.

Path Functions

file:name

Signature
file:name(
  $path  as xs:string
) as xs:string
SummaryReturns 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?
SummaryReturns 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
SummaryTransforms the $path argument to its native representation on the operating system.
Errors
io-errorThe operation fails for some other reason specific to the operating system.
not-foundA specified path does not exist.

file:resolve-path

Signature
file:resolve-path(
  $path  as xs:string,
  $base  as xs:string  := ()
) as xs:string
SummaryTransforms 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-relativeThe 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
SummaryTransforms the path specified by $path into a URI with the file:// scheme.

System Properties

file:dir-separator

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

file:path-separator

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

file:line-separator

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

file:temp-dir

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

file:current-dir

Signature
file:current-dir() as xs:string
SummaryReturns 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?
SummaryReturns 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

CodeDescription
existsA file with the same path already exists.
invalid-pathA specified path is invalid.
io-errorThe operation fails for some other reason specific to the operating system.
is-dirThe specified path is a directory.
is-relativeThe specified path is relative (and must be absolute).
no-dirThe specified path does not point to a directory.
not-foundA specified path does not exist.
out-of-rangeThe specified offset or length is negative, or the chosen values would exceed the file bounds.
unknown-encodingThe specified encoding is not supported, or unknown.

Changelog

Version 11.0Version 9.3Version 9.0Version 8.5Version 8.2Version 8.0Version 7.8Version 7.7Version 7.3Version 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