File Module

From BaseX Documentation
Revision as of 17:59, 21 January 2011 by CG (talk | contribs)
Jump to navigation Jump to search

The file module contains XQuery Functions to perform file system related operations, such as listing, reading, or writing files. All functions are preceded by the file: prefix. Some changes might happen to this module, as it is currently aligned with the upcoming EXPath specification.

file:exists

Signatures file:exists($path as xs:string) as xs:boolean
Summary Checks if a path exist.
Rules This function returns an xs:boolean indicating whether a file or directory specified by $path exists in the file system.

file:is-directory

Signatures file:is-directory($path as xs:string) as xs:boolean
Summary Checks if a path points to a directory.
Rules This function 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 Checks if a path points to a file.
Rules This function returns an xs:boolean indicating whether the argument $path points to an existing file.

file:is-readable

Signatures file:is-readable($path as xs:string) as xs:boolean
Summary Checks if a file is readable.
Rules This function returns an xs:boolean indicating whether the file specified by $path exists and is readable.

file:is-writable

Signatures file:is-writable($path as xs:string) as xs:boolean
Summary Checks if a file is writable.
Rules This function returns an xs:boolean indicating whether the file specified by $path exists and is writable.

file:last-modified

Signatures file:last-modified($path as xs:string) as xs:dateTime
Summary Returns the timestamp of a path.
Rules This function retrieves the timestamp of the last modification of the file or directory specified by $path.
Errors [FOFL0001] is raised if the specified path does not exist.

file:size

Signatures file:size($path as xs:string) as xs:integer
Summary Returns the size of a file.
Rules This function returns the size, in bytes, of the file specified by $path. The return value is unspecified if the argument points to a directory.
Errors [FOFL0001] is raised if the specified path does not exist.

file:list

Signatures file:list($path as xs:string) as xs:string*
file:list($path as xs:string, $recursive as xs:boolean) as xs:string*
file:list($path as xs:string, $recursive as xs:boolean, $pattern as xs:string) as xs:string*
Summary Lists the contents of a directory.
Rules This function lists all files and directories found in the directory that is specified by $path. The returned paths are relative to the provided path.
The optional parameter $recursive specifies whether the sub-directories are to be recursed as well.
The optional parameter $pattern defines a file name pattern. If present, only those files and directories are returned that correspond to the pattern. A pattern may contain asterisks (*) to match zero or more characters, and question marks (?) to match single characters. Several patterns can be separated with a comma (,).
Errors [FOFL0001] is raised if the specified path does not exist.
[FOFL0003] is raised if the specified path does not point to a directory.
[FOFL0008] is raised if the operation fails for some other reason.

file:create-directory

Signatures file:create-directory($path as xs:string) as empty-sequence()
Summary Creates a new directory path.
Rules This function recursively creates the directories specified by $path.
Errors [FOFL0002] is raised if a file with the same path already exists.
[FOFL0006] is raised if the specified path is invalid (e.g., contains invalid characters).
[FOFL0008] is raised if the operation fails for some other reason.

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 Deletes a file or directory.
Rules This function deletes a file or directory specified by $path. No operation will be performed if the specified path does not exist.
If the optional parameter $recursive is provided, the operation is performed recursively for all sub-directories of the given path.
Errors [FOFL0005] is raised if $recursive is not specified or set to false, and if the specified path points to a non-empty directory.
[FOFL0008] is raised if the operation fails for some other reason.

file:read

Signatures file:read($path as xs:string) as xs:string
file:read($path as xs:string, $encoding as xs:string) as xs:string
Summary Reads the contents a file.
Rules This function reads the textual contents of the file specified by $path and returns it as a xs:string.
The optional parameter $encoding defines the encoding of the file.
Errors [FOFL0001] is raised if the specified file does not exist.
[FOFL0004] is raised if the specified path is a directory.
[FOFL0007] is raised if the specified encoding is not supported, or unknown.
[FOFL0008] is raised if 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 contents of a file.
Rules This function reads the binary content of the file specified by $path and returns as a xs:base64Binary.
Errors [FOFL0001] is raised if the specified file does not exist.
[FOFL0004] is raised if the specified path is a directory.
[FOFL0008] is raised if the operation fails for some other reason.

file:write

Signatures file:write($path as xs:string, $items as xs:item()*) as empty-sequence()
file:write($path as xs:string, $items as xs:item()*, $params as xs:node()*) as empty-sequence()
file:write($path as xs:string, $items as xs:item()*, $params as xs:node()*, $append as xs:boolean) as empty-sequence()
Summary Writes a sequence of items to a file.
Rules This function writes a sequence, specified by $items, to a file specified by $path. If the specified file already exists, it will be overwritten.
The optional argument $params is used to set the serialization parameters, as defined in XSLT 2.0 and XQuery 1.0 Serialization.
If the $append flag is set to true, the serialized items are appended to the original file. If the file does not exist, a new one is created.
Errors [FOFL0004] is raised if the specified path is a directory.
[FOFL0008] is raised if the operation fails for some other reason.

file:write-binary

Signatures file:write-binary($path as xs:string, $item as xs:base64Binary) as empty-sequence()
file:write-binary($path as xs:string, $item as xs:base64Binary, $append as xs:boolean) as empty-sequence()
Summary Writes a sequence of items to a file.
Rules This function writes a xs:basex64Binary item specified by $item to a file specified by $path. If the specified file already exists, it will be overwritten.
If the $append flag is set to true, the serialized item is appended to the original file. If the file does not exist, a new one is created.
Errors [FOFL0004] is raised if the specified path is a directory.
[FOFL0008] is raised if 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.
Rules This function copies a file specified by $source to the file or directory specified by $target. If the target represents an existing file, it will be overwritten. No operation will be performed if the source and target path are equal.
Errors [FOFL0001] is raised if the specified source does not exist.
[FOFL0004] is raised if the specified source is a directory.
[FOFL0006] is raised if the specified target path points to a file in a non-existing directory.
[FOFL0008] is raised if 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 a file.
Rules This function moves, or renames, the file or directory specified by $source to the path specified by $target. No operation will be performed if the source and target path are equal.
Errors [FOFL0001] is raised if the specified source does not exist.
[FOFL0006] is raised if the specified target path points to a file in a non-existing directory.
[FOFL0008] is raised if the operation fails for some other reason.

file:path-separator

Signatures file:path-separator() as xs:string
Summary Returns the path separator.
Rules This function returns the path separator used by the operating system.

file:path-to-full-path

Signatures file:path-to-full-path($path as xs:string) as xs:string
Summary Returns a full path representation.
Rules This function transforms the path specified by $path into a full operating system path.

file:path-to-uri

Signatures file:path-to-uri($path as xs:string) as xs:string
Summary Returns a URI representation.
Rules This function transforms the path specified by $path into a URI with the file:// scheme.