File Module

From BaseX Documentation
Revision as of 17:03, 9 December 2010 by Michael (talk | contribs)
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 <a href="http://expath.org/spec/file">EXPath</a> 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 as a string.
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.

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 <a href="http://www.w3.org/TR/xslt-xquery-serialization/">XSLT 2.0 and XQuery 1.0 Serialization</a>.
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 newwdirectory.
     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 a URI representation.
     Rules 
This function transforms a file system path into a URI with the file:// scheme.