From BaseX Documentation

Jump to: navigation, search

This XQuery Module contains functions and variables related to file system operations, such as listing, reading, or writing files. This module is based on the EXPath File Module.

[edit] 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.

[edit] Read Operations

[edit] 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.

[edit] 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 it as streamable `xs:base64Binary`.
Errors	`FILE0001`: the specified file does not exist. `FILE0004`: the specified path is a directory. `FILE9999`: the operation fails for some other reason.
Examples	`stream:materialize(file:read-binary("config.data"))` returns a materialized representation of the streamable result.

[edit] 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.

[edit] 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.

[edit] Write Operations

[edit] file:create-dir

Signatures	`file:create-dir($dir as xs:string) as empty-sequence()`
Summary	Recursively creates the directories specified by `$dir`.
Errors	`FILE0002`: a file with the same path already exists. `FILE9999`: the operation fails for some other reason.

[edit] 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.

[edit] 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"/>
  ...
</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.

[edit] file:write-binary

Signatures	`file:write-binary($path as xs:string, $value as basex:binary) 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.
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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] file:append-binary

Signatures	`file:append-binary($path as xs:string, $value as basex:binary) 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] File Properties

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] Path Functions

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] System Properties

[edit] file:dir-separator

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

[edit] file:path-separator

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

[edit] file:line-separator

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

[edit] 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.
`FILE9999`	The operation fails for some other reason specific to the operating system.

[edit] Changelog

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.

File Module