File Module

From BaseX Documentation
Revision as of 18:24, 13 December 2010 by CG (talk | contribs) (moved File to File Functions: consistent naming)
Jump to navigation Jump to search

The file module contains extension 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 checks if a path is already used in the file system. The function returns true if the file or directory pointed by the $path parameter already exists. Otherwise it returns false.

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 checks if a path points to a directory. The function returns true if the path points to a directory. Otherwise, it returns false.

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 checks if a path points to a file. The function returns true if the path points to a file. Otherwise, it returns false.

file:is-readable

Signatures file:is-readable($path as xs:string) as xs:boolean
Summary Checks if a file is readable.
Rules This function checks if the file pointed by $path is readable. The function returns true if the file is readable. Otherwise it returns false.

file:is-writable

Signatures file:is-writable($path as xs:string) as xs:boolean
Summary Checks if a file is writeable.
Rules This function checks if the file pointed by $path is writeable. The function returns true if the file is writeable. Otherwise it returns false.

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 item pointed by the path provided by the parameter$path.

file:files

Signatures file:files($path as xs:string) as xs:string*
file:files($path as xs:string, $recursive as xs:boolean) as xs:string*
file:files($path as xs:string, $recursive as xs:boolean, $pattern as xs:string) as xs:string*
Summary Lists files of a directory.
Rules This function lists all files in a given directory. The special files "." and ".." are never returned.
The optional parameter $recursive indicates whether the search shall recurse in the subdirectories.
The optional parameter $pattern defines a pattern and if it is present, only the files, which names match the given pattern, will be returned.
Errors [FOFL0003] is raised if files in the given directory cannot be returned.
[FOFL0004] is raised for an invalid file pattern.

file:read

Signatures file:read($path as xs:string) as xs:string
Summary Reads a file.
Rules This function reads the content of the file pointed by $path and returns it as a string.
The optional parameter $encoding defines the encoding type of the file.
Errors [FOFL0017] is raised if the provided encoding is not supported.

file:read-binary

Signatures file:read-binary($path as xs:string) as xs:base64Binary
Summary Reads a binary file.
Rules This function reads the content of the file pointed by $path and returns it in Base64 representation.
Errors [FOFL0001] is raised if the file cannot be read.

file:size

Signatures file:size($path as xs:string) as xs:integer
Summary Returns the file size.
Rules This function returns the size, in bytes, of the file pointed by $path.
Errors [FOFL0001] is raised if the file cannot be read.

file:write

Signatures 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 of items to a file. It either creates a new file, or appends the serialized content to the file pointed by $path.
The $params parameter is used to set the serialization parameters as defined in XSLT 2.0 and XQuery 1.0 Serialization.
If the $append flag is true and the file does not exist, a new one is created.
Errors [FOFL0002] is raised if the file cannot be written.
[FOFL0008] is raised if the $append flag is false and a file with the same path already exists.

file:write-binary

Signatures file:write-binary($path as xs:string, $items as xs:base64Binary) as empty-sequence()
file:write-binary($path as xs:string, $items as xs:base64Binary, $append as xs:boolean) as empty-sequence()
Summary Writes a sequence of items to a file.
Rules This function writes binary data into a file. It either creates a new file or appends the content to the file pointed by $path.
If the $append flag is true and the file does not exist, a new one is created.
Errors [FOFL0002] is raised if the file cannot be written.
[FOFL0008] is raised if the $append flag is false and a file with the same path already exists.

file:mkdir

Signatures file:mkdir($path as xs:string, $recursive as xs:boolean) as empty-sequence()
Summary Creates a new directory.
Rules This function creates a directory.
The optional parameter $recursive indicates whether parent directories are to be created recursively.
Errors [FOFL0008] is raised if a file with the same path already exists in the file system.
[FOFL0011] is raised if the directory in which the new sub-directory is to be created is write protected.
[FOFL0012] is raised if the directory cannot be created 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.
Rules This function deletes a file or directory from the file system.
If the optional parameter $recursive is provided, the operation is performed recursively for all sub-directories of the given directory.
Errors [FOFL0005] is raised if the file/directory pointed by $path is write-protected and cannot be deleted.
[FOFL0006] is raised if the file/directory pointed by $path does not exist.
[FOFL0013] is raised if the file/directory pointed by $path cannot be deleted for some other reason.

file:copy

Signatures file:copy($source as xs:string, $target as xs:string) as empty-sequence()
file:copy($source as xs:string, $target as xs:string, $overwrite as xs:boolean) as empty-sequence()
Summary Copies a file.
Rules This function copies a file specified by $source to $target.
If the optional parameter $overwrite is provided and evaluates to true, the target file, if it exists, will be overwritten.
Errors [FOFL0006] is raised if the file pointed by $source does not exist.
[FOFL0008] is raised if the file to be copied already exists in the specified target and the $overwrite parameter is missing or evaluates to false.
[FOFL0016] is raised if the source file cannot be copied because of 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/renames the file pointed by $source to $target.
Errors [FOFL0006] is raised if the file pointed by $source does not exist.
[FOFL0008] is raised if a file/directory with the same name already exists in the given target.
[FOFL0009] is raised if the item pointed by $source is a directory.
[FOFL0010] is raised if the file pointed by $source is write-protected and cannot be moved.
[FOFL0014] is raised if the file cannot be moved 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 a 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 an URI representation.
Rules This function transforms a file system path into an URI with the file:// scheme.