File Module

From BaseX Documentation
Revision as of 16:58, 11 July 2013 by Arve (talk | contribs) (→‎file:write: add missing namespace)
Jump to navigation Jump to search

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.

Read Operations

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.

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.

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.

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.

Write Operations

file:create-dir

Signatures file:create-dir($dir as xs:string) as empty-sequence()
Summary Creates the directory specified by $dir, including all non-existing parent directories.
Errors FILE0002: a file with the same path already exists.
FILE9999: the operation fails for some other reason.

file:create-temp-dir

Template:Mark

Signatures 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
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 FILE0003: the specified directory points to a file.
FILE9999: the directory could not be created.

file:create-temp-file

Template:Mark

Signatures 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
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 FILE0003: the specified directory points to a file.
FILE9999: the directory could not be created.

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.

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"/>
  ...
</output: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.

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.

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.

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.

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.

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.

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.

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.


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.

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.

File Properties

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

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 FILE0001: 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 FILE0001: the specified file does not exist.
FILE0004: the specified file points to a directory.

Path Functions

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 FILE9999: 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.

System Properties

file:dir-separator

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

file:path-separator

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

file:line-separator

Signatures file:line-separator() as xs:string
Summary Returns the line separator used by the operating system, such as &#10;, &#13;&#10; or &#13;.

file:temp-dir

Template:Mark

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

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.

Changelog

Version 7.7
Version 7.3
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.
Retrieved from "http://docs.basex.org/index.php?title=File_Module&oldid=9723"