Difference between revisions of "File Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Fix syntax of wiki template usage so the content renders properly)
 
(241 intermediate revisions by 9 users not shown)
Line 1: Line 1:
<p>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 <code>file:</code> prefix. Some changes might happen to this module, as it is currently aligned with the upcoming [http://expath.org/spec/file EXPath] specification.</p>
+
This [[Module Library|XQuery Module]] contains functions related to file system operations, such as listing, reading, or writing files.
  
==file:exists==
+
This module is based on the [http://expath.org/spec/file EXPath File Module]. The following enhancements have not been added to the specification yet:
 +
 
 +
{| class="wikitable"
 +
|- valign="top"
 +
! Function
 +
! Description
 +
|- valign="top"
 +
| {{Function||file:descendants}}
 +
| new function
 +
|- valign="top"
 +
| {{Function||file:is-absolute}}
 +
| new function
 +
|- valign="top"
 +
| {{Function||file:read-text}}, {{Function||file:read-text-lines}}
 +
| <code>$fallback</code> argument added
 +
|- valign="top"
 +
| {{Function||file:read-text-lines}}
 +
| <code>$offset</code> and <code>$length</code> arguments added
 +
|- valign="top"
 +
| {{Function||file:resolve-path}}
 +
| <code>$base</code> argument added
 +
|}
 +
 
 +
=Conventions=
 +
 
 +
All functions and errors in this module are assigned to the <code><nowiki>http://expath.org/ns/file</nowiki></code> namespace, which is statically bound to the {{Code|file}} prefix.<br/>
 +
 
 +
For serialization parameters, the <code><nowiki>http://www.w3.org/2010/xslt-xquery-serialization</nowiki></code> namespace is used, which is statically bound to the {{Code|output}} prefix.<br/>
 +
 
 +
The error <code>[[#Errors|invalid-path]]</code> is raised if a path is invalid.
 +
 
 +
==File Paths==
 +
 
 +
* All file paths are resolved against the ''current working directory'' (the directory from which BaseX or, more generally, the Java Virtual Machine, was started). This directory can be retrieved via {{Function||file:base-dir}}.
 +
 
 +
* A path can be specified as local filesystem path or as file URI.
 +
 
 +
* Returned strings that refer to existing directories are suffixed with a directory separator.
 +
 
 +
=Read Operations=
 +
 
 +
==file:list==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:list(
 +
  $dir        as xs:string,
 +
  $recursive  as xs:boolean?  := false(),
 +
  $pattern    as xs:string    := ()
 +
) as xs:string*</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Lists all files and directories found in the specified {{Code|$dir}}. The returned paths are relative to the provided path.<br/>If {{Code|$recursive}} is set to true, subdirectories will be traversed.<br/>The optional parameter {{Code|$pattern}} defines a file name pattern in the [[Commands#Glob_Syntax|Glob Syntax]]. If present, only those files and directories are returned that correspond to the pattern. Several patterns can be separated with a comma ({{Code|,}}).<br/>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} the specified file does not exist.<br/>{{Error|no-dir|#Errors}} the specified path does not point to a directory.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 +
|- valign="top"
 +
| '''Examples'''
 +
| Return the contents of large {{Code|.txt}} files located in a specific directory and its subdirectories:
 +
<pre lang='xquery'>
 +
let $root := 'path/to/files/'
 +
for $file in file:list($root, true(), '*.txt')
 +
let $path := $root || $file
 +
where file:size($path) > 1000000
 +
return file:read-text($path)
 +
</pre>
 +
|}
 +
 
 +
==file:children==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:children(
 +
  $dir  as xs:string
 +
) as xs:string*</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the full paths to all files and directories found in the specified {{Code|$dir}}.<br/>The inverse function is {{Function||file:parent}}. The returned paths start with the specified directory. The related function {{Function||file:list}} returns relative file paths.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} the specified file does not exist.<br/>{{Error|no-dir|#Errors}} the specified path does not point to a directory.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 +
|- valign="top"
 +
| '''Examples'''
 +
| Return the contents of large {{Code|.txt}} files located in a specific directory:
 +
<pre lang='xquery'>
 +
for $file in file:children('path/to/files/')
 +
where matches($file, '.txt', 'i') and file:size($file) > 1000000
 +
return file:read-text($$file)
 +
</pre>
 +
|}
 +
 
 +
==file:descendants==
  
{|
+
{| width='100%'
|-
+
|- valign="top"
| width="90" | '''Signatures'''
+
| width='120' | '''Signature'''
|<code>'''file:exists'''($path as xs:string) as xs:boolean</code>
+
|<pre>file:descendants(
|-
+
  $dir  as xs:string
 +
) as xs:string*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
| Checks if a path exist.
+
|Returns the full paths to all files and directories found in the specified {{Code|$dir}} and its subdirectories.<br/>. The returned paths start with the specified directory. The related function {{Function||file:list}} creates relative file paths.
|-
+
|- valign="top"
| '''Rules'''
+
| '''Errors'''
| This function checks if a path is already used in the file system. The function returns <code>true</code> if the file or directory pointed by the <code>$path</code> parameter already exists. Otherwise it returns <code>false</code>.
+
|{{Error|not-found|#Errors}} the specified file does not exist.<br/>{{Error|no-dir|#Errors}} the specified path does not point to a directory.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 +
|- valign="top"
 +
| '''Examples'''
 +
| Return the contents of all {{Code|.txt}} files located in a specific directory and its subdirectories:
 +
<pre lang='xquery'>
 +
for $file in file:descendants('path/to/files/')
 +
where matches($file, '.txt', 'i') and file:size($file) > 1000000
 +
return file:read-text($$file)
 +
</pre>
 
|}
 
|}
  
==file:is-directory==
+
==file:read-binary==
  
{|
+
{| width='100%'
|-
+
|- valign="top"
| width="90" | <b>Signatures</b>
+
| width='120' | '''Signature'''
|<code><b>file:is-directory</b>($path as xs:string) as xs:boolean</code>
+
|<pre>file:read-binary(
|-
+
  $path   as xs:string,
| <b>Summary</b>
+
  $offset  as xs:integer  := (),
| Checks if a path points to a directory.
+
  $length  as xs:integer  := ()
|-
+
) as xs:base64Binary</pre>
| <b>Rules</b>
+
|- valign="top"
| This function checks if a path points to a directory. The function returns <code>true</code> if the path points to a directory. Otherwise, it returns <code>false</code>.<br />  
+
| '''Summary'''
 +
|Reads the binary content of the file specified by {{Code|$path}} and returns it as [[Lazy Module|lazy]] {{Code|xs:base64Binary}} item.<br/>The optional parameters {{Code|$offset}} and {{Code|$length}} can be used to read chunks of a file.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} the specified file does not exist.<br/>{{Error|is-dir|#Errors}} the specified path is a directory.<br/>{{Error|out-of-range|#Errors}} the offset or length is negative, or the chosen values would exceed the file bounds.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* <code><nowiki>lazy:cache(file:read-binary("config.data"))</nowiki></code> enforces the file access (otherwise, it will be delayed until requested first).
 
|}
 
|}
 
==file:is-file==
 
  
{|
+
==file:read-text==
|-
 
| width="90" | <b>Signatures</b>
 
|<code><b>file:is-file</b>($path as xs:string) as xs:boolean</code>
 
|-
 
| <b>Summary</b>
 
| Checks if a path points to a file.
 
|-
 
| <b>Rules</b>
 
| This function checks if a path points to a file. The function returns <code>true</code> if the path points to a file. Otherwise, it returns <code>false</code>.<br />
 
|}
 
 
==file:is-readable==
 
  
{|
+
{| width='100%'
|-
+
|- valign="top"
| width="90" | <b>Signatures</b>
+
| width='120' | '''Signature'''
|<code><b>file:is-readable</b>($path as xs:string) as xs:boolean</code>
+
|<pre>file:read-text(
|-
+
  $path     as xs:string,
| <b>Summary</b>
+
  $encoding  as xs:string   := (),
| Checks if a file is readable.
+
  $fallback  as xs:boolean?  := false()
|-
+
) as xs:string</pre>
| <b>Rules</b>
+
|- valign="top"
| This function checks if the file pointed by <code>$path</code> is readable. The function returns <code>true</code> if the file is readable. Otherwise it returns <code>false</code>.<br />
+
| '''Summary'''
 +
|Reads the textual contents of the file specified by {{Code|$path}} and returns it as [[Lazy Module|lazy]] {{Code|xs:string}} item:
 +
* The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument.
 +
* By default, invalid XML characters will be rejected. If {{Code|$fallback}} is enabled, the characters will be replaced with the Unicode replacement character <code>FFFD</code> (&#xFFFD;).
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} the specified file does not exist.<br/>{{Error|is-dir|#Errors}} the specified path is a directory.<br/>{{Error|unknown-encoding|#Errors}} the specified encoding is not supported, or unknown.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* <code><nowiki>lazy:cache(file:read-text("ids.txt"))</nowiki></code> enforces the file access (otherwise, it will be delayed until requested first).
 
|}
 
|}
 
==file:is-writable==
 
  
{|
+
==file:read-text-lines==
|-
+
 
| width="90" | <b>Signatures</b>
+
{| width='100%'
|<code><b>file:is-writable</b>($path as xs:string) as xs:boolean</code>
+
|- valign="top"
|-
+
| width='120' | '''Signature'''
| <b>Summary</b>
+
|<pre>file:read-text-lines(
| Checks if a file is writeable.
+
  $path     as xs:string,
|-
+
  $encoding  as xs:string   := (),
| <b>Rules</b>
+
  $fallback  as xs:boolean?  := false(),
| This function checks if the file pointed by <code>$path</code> is writeable. The function returns <code>true</code> if the file is writeable. Otherwise it returns <code>false</code>.<br />
+
  $offset    as xs:integer?  := (),
 +
  $length    as xs:integer?  := ()
 +
) as xs:string*</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Reads the textual contents of the file specified by {{Code|$path}} and returns it as a sequence of {{Code|xs:string}} items:
 +
* The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument.
 +
* By default, invalid characters will be rejected. If {{Code|$fallback}} is set to true, these characters will be replaced with the Unicode replacement character <code>FFFD</code> (&#xFFFD;).
 +
The lines to be read can be restricted with the optional parameters {{Code|$offset}} and {{Code|$length}}.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} the specified file does not exist.<br/>{{Error|is-dir|#Errors}} the specified path is a directory.<br/>{{Error|unknown-encoding|#Errors}} the specified encoding is not supported, or unknown.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 
|}
 
|}
 
==file:last-modified==
 
  
{|
+
=Write Operations=
|-
+
 
| width="90" | <b>Signatures</b>
+
==file:create-dir==
|<code><b>file:last-modified</b>($path as xs:string) as xs:dateTime</code>
 
|-
 
| <b>Summary</b>
 
| Returns the timestamp of a path.
 
|-
 
| <b>Rules</b>
 
| This function retrieves the timestamp of the last modification of the item pointed by the path provided by the parameter<code>$path</code>.<br />
 
|}
 
 
==file:files==
 
  
{|
+
{| width='100%'
|-
+
|- valign="top"
| width="90" | <b>Signatures</b>
+
| width='120' | '''Signature'''
|<code><b>file:files</b>($path as xs:string) as xs:string*</code> <br /> <code><b>file:files</b>($path as xs:string, $recursive as xs:boolean) as xs:string*</code> <br /> <code><b>file:files</b>($path as xs:string, $recursive as xs:boolean, $pattern as xs:string) as xs:string*</code>
+
|<pre>file:create-dir(
|-
+
  $dir  as xs:string
| <b>Summary</b>
+
) as empty-sequence()</pre>
| Lists files of a directory.
+
|- valign="top"
|-
+
| '''Summary'''
| <b>Rules</b>
+
|Creates the directory specified by {{Code|$dir}} if it does not already exist. Non-existing parent directories will be created as well.<br/>
| This function lists all files in a given directory. The special files "." and ".." are never returned.<br />The optional parameter <code>$recursive</code> indicates whether the search shall recurse in the subdirectories.<br />The optional parameter <code>$pattern</code> defines a pattern and if it is present, only the files, which names match the given pattern, will be returned.<br />
+
|- valign="top"
|-
+
| '''Errors'''
| <b>Errors</b>
+
|{{Error|exists|#Errors}} the specified target exists, but is no directory.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
| <b>[FOFL0003]</b> is raised if files in the given directory cannot be returned.<br /> <b>[FOFL0004]</b> is raised for an invalid file pattern.<br />  
+
|}
|}
 
 
==file:read==
 
  
{|
+
==file:create-temp-dir==
|-
 
| width="90" | <b>Signatures</b>
 
|<code><b>file:read</b>($path as xs:string) as xs:string</code>
 
|-
 
| <b>Summary</b>
 
| Reads a file.
 
|-
 
| <b>Rules</b>
 
| This function reads the content of the file pointed by <code>$path</code> and returns it as a string.<br />The optional parameter <code>$encoding</code> defines the encoding type of the file.<br />
 
|-
 
| <b>Errors</b>
 
| <b>[FOFL0017]</b> is raised if the provided encoding is not supported.<br />
 
|}
 
 
==file:read-binary==
 
  
{|
+
{| width='100%'
|-
+
|- valign="top"
| width="90" | <b>Signatures</b>
+
| width='120' | '''Signature'''
|<code><b>file:read-binary</b>($path as xs:string) as xs:base64Binary</code>
+
|<pre>file:create-temp-dir(
|-
+
  $prefix  as xs:string,
| <b>Summary</b>
+
  $suffix  as xs:string,
| Reads a binary file.
+
  $dir    as xs:string := ()
|-
+
) as xs:string</pre>
| <b>Rules</b>
+
|- valign="top"
| This function reads the content of the file pointed by <code>$path</code> and returns it in Base64 representation.<br />
+
| '''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 {{Code|$prefix}} and {{Code|$suffix}}. If no directory is specified via {{Code|$dir}}, the directory will be placed in the system’s default temporary directory. The operation will create all non-existing parent directories.
| <b>Errors</b>
+
|- valign="top"
| <b>[FOFL0001]</b> is raised if the file cannot be read.<br />
+
| '''Errors'''
 +
|{{Error|no-dir|#Errors}} the specified directory points to a file.<br/>{{Error|io-error|#Errors}} the directory could not be created.
 
|}
 
|}
 
==file:size==
 
  
{|
+
==file:create-temp-file==
|-
+
 
| width="90" | <b>Signatures</b>
+
{| width='100%'
|<code><b>file:size</b>($path as xs:string) as xs:integer</code>  
+
|- valign="top"
|-
+
| width='120' | '''Signature'''
| <b>Summary</b>
+
|<pre>file:create-temp-file(
| Returns the file size.
+
  $prefix  as xs:string,
|-
+
  $suffix  as xs:string,
| <b>Rules</b>
+
  $dir    as xs:string := ()
| This function returns the size, in bytes, of the file pointed by <code>$path</code>.<br />
+
) as xs:string</pre>
|-
+
|- valign="top"
| <b>Errors</b>
+
| '''Summary'''
| <b>[FOFL0001]</b> is raised if the file cannot be read.<br />
+
|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 {{Code|$prefix}} and {{Code|$suffix}}. If no directory is specified via {{Code|$dir}}, the file will be placed in the system’s default temporary directory. The operation will create all non-existing parent directories.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|no-dir|#Errors}} the specified directory points to a file.<br/>{{Error|io-error|#Errors}} the directory could not be created.
 
|}
 
|}
   
+
 
 +
==file:delete==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:delete(
 +
  $path      as xs:string,
 +
  $recursive as xs:boolean?  := false()
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Recursively deletes a file or directory specified by {{Code|$path}}.<br/>The optional parameter {{Code|$recursive}} specifies whether subdirectories will be deleted, too.<br/>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} the specified path does not exist.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 +
|}
 +
 
 
==file:write==
 
==file:write==
  
{|
+
{| width='100%'
|-
+
|- valign="top"
| width="90" | <b>Signatures</b>
+
| width='120' | '''Signature'''
|<code><b>file:write</b>($path as xs:string, $items as xs:item()*, $params as xs:node()*) as empty-sequence()</code> <br /><code><b>file:write</b>($path as xs:string, $items as xs:item()*, $params as xs:node()*, $append as xs:boolean) as empty-sequence()</code>
+
|<pre>file:write(
|-
+
  $path     as xs:string,
| <b>Summary</b>
+
  $input    as item()*,
| Writes a sequence of items to a file.
+
  $options  as map(*)?    := map { }
|-
+
) as empty-sequence()</pre>
| <b>Rules</b>
+
|- valign="top"
| This function writes a sequence of <code>items</code> to a file. It either creates a new file, or appends the serialized content to the file pointed by <code>$path</code>.<br />The <code>$params</code> parameter is used to set the serialization parameters as defined in [http://www.w3.org/TR/xslt-xquery-serialization XSLT 2.0 and XQuery 1.0 Serialization].<br />If the <code>$append</code> flag is true and the file does not exist, a new one is created.<br />
+
| '''Summary'''
|-
+
|Writes serialized {{Code|$input}} to the specified file. If the file already exists, it will be overwritten.<br/>The {{Code|$options}} argument contains [[Serialization|serialization parameters]]. As with [https://www.w3.org/TR/xpath-functions-31/#func-serialize fn:serialize()], the parameters can be specified<br/>
| <b>Errors</b>
+
* either as children of an {{Code|&lt;output:serialization-parameters/&gt;}} element:
| <b>[FOFL0002]</b> is raised if the file cannot be written.<br /><b>[FOFL0008]</b> is raised if the <code>$append</code> flag is <code>false</code> and a file with the same path already exists.<br />
+
<pre lang="xml">
 +
<output:serialization-parameters>
 +
  <output:method value='xml'/>
 +
  <output:cdata-section-elements value="div"/>
 +
  ...
 +
</output:serialization-parameters>
 +
</pre>
 +
* or as map, which contains all key/value pairs:
 +
<pre lang='xquery'>
 +
map { "method": "xml", "cdata-section-elements": "div", ... }
 +
</pre>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|no-dir|#Errors}} the parent of specified path is no directory.<br/>{{Error|is-dir|#Errors}} the specified path is a directory.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* <code><nowiki>file:write('data.bin', xs:hexBinary('414243'))</nowiki></code> writes a hex representation to the specified file.
 +
* <code><nowiki>file:write('data.bin', xs:hexBinary('414243'), map { 'method': 'basex')</nowiki></code> writes binary data to the specified file (see [[XQuery_Extensions#Serialization|Serialization]] for more details).
 
|}
 
|}
+
 
 
==file:write-binary==
 
==file:write-binary==
  
{|
+
{| width='100%'
|-
+
|- valign="top"
| width="90" | <b>Signatures</b>
+
| width='120' | '''Signature'''
|<code><b>file:write-binary</b>($path as xs:string, $items as xs:base64Binary) as empty-sequence()</code> <br /><code><b>file:write-binary</b>($path as xs:string, $items as xs:base64Binary, $append as xs:boolean) as empty-sequence()</code>  
+
|<pre>file:write-binary(
|-
+
  $path    as xs:string,
| <b>Summary</b>
+
  $value  as xs:anyAtomicType,
| Writes a sequence of items to a file.
+
  $offset  as xs:integer        := ()
|-
+
) as empty-sequence()</pre>
| <b>Rules</b>
+
|- valign="top"
| This function writes binary data into a file. It either creates a new file or appends the content to the file pointed by <code>$path</code>.<br />If the <code>$append</code> flag is true and the file does not exist, a new one is created.<br />  
+
| '''Summary'''
|-
+
|Writes a binary item (xs:base64Binary, xs:hexBinary) to the specified file. If the file already exists, it will be overwritten.<br/>If {{Code|$offset}} is specified, data will be written at this file position. An existing file may be resized by that operation.
| <b>Errors</b>
+
|- valign="top"
| <b>[FOFL0002]</b> is raised if the file cannot be written.<br /><b>[FOFL0008]</b> is raised if the <code>$append</code> flag is <code>false</code> and a file  with the same path already exists.<br />
+
| '''Errors'''
 +
|{{Error|no-dir|#Errors}} the parent of specified path is no directory.<br/>{{Error|is-dir|#Errors}} the specified path is a directory.<br/>{{Error|out-of-range|#Errors}} the offset is negative, or it exceeds the current file size.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 +
|}
 +
 
 +
==file:write-text==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:write-text(
 +
  $path     as xs:string,
 +
  $value    as xs:string,
 +
  $encoding  as xs:string  := ()
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Writes a string to the specified file. If the file already exists, it will be overwritten.<br/>The optional parameter {{Code|$encoding}} defines the output encoding (default: UTF-8).<br/>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|no-dir|#Errors}} the parent of specified path is no directory.<br/>{{Error|is-dir|#Errors}} the specified path is a directory.<br/>{{Error|unknown-encoding|#Errors}} the specified encoding is not supported, or unknown.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 +
|}
 +
 
 +
==file:write-text-lines==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:write-text-lines(
 +
  $path     as xs:string,
 +
  $values    as xs:string*,
 +
  $encoding  as xs:string  := ()
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 +
| '''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.<br/>The optional parameter {{Code|$encoding}} defines the output encoding (default: UTF-8).<br/>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|no-dir|#Errors}} the parent of specified path is no directory.<br/>{{Error|is-dir|#Errors}} the specified path is a directory.<br/>{{Error|unknown-encoding|#Errors}} the specified encoding is not supported, or unknown.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 +
|}
 +
 
 +
==file:append==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:append(
 +
  $path    as xs:string,
 +
  $input    as item()*,
 +
  $options  as map(*)?    := map { }
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Appends a serialized sequence of {{Code|$input}} to the specified file, with the supplied {{Code|$options}} as serialization parameters. If the file does not exist, a new file is created.<br/>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|no-dir|#Errors}} the parent of specified path is no directory.<br/>{{Error|is-dir|#Errors}} the specified path is a directory.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 
|}
 
|}
 
==file:mkdir==
 
  
{|
+
==file:append-binary==
|-
+
 
| width="90" | <b>Signatures</b>
+
{| width='100%'
|<code><b>file:mkdir</b>($path as xs:string, $recursive as xs:boolean) as empty-sequence()</code>  
+
|- valign="top"
|-
+
| width='120' | '''Signature'''
| <b>Summary</b>
+
|<pre>file:append-binary(
| Creates a new directory.
+
  $path   as xs:string,
|-
+
  $value  as xs:anyAtomicType
| <b>Rules</b>
+
) as empty-sequence()</pre>
| This function creates a directory.<br />The optional parameter <code>$recursive</code> indicates whether parent directories are to be created recursively.<br />  
+
|- valign="top"
|-
+
| '''Summary'''
| <b>Errors</b>
+
|Appends a binary item (xs:base64Binary, xs:hexBinary) to the specified file. If the file does not exists, a new one is created.<br/>
| <b>[FOFL0008]</b> is raised if a file with the same path already exists in the file system.<br /><b>[FOFL0011]</b> is raised if the directory in which the new sub-directory is to be created is write protected.<br /> <b>[FOFL0012]</b> is raised if the directory cannot be created for some other reason.<br />
+
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|no-dir|#Errors}} the parent of specified path is no directory.<br/>{{Error|is-dir|#Errors}} the specified path is a directory.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 
|}
 
|}
 
==file:delete==
 
  
{|
+
==file:append-text==
|-
+
 
| width="90" | <b>Signatures</b>
+
{| width='100%'
|<code><b>file:delete</b>($path as xs:string) as empty-sequence()</code><br /><code><b>file:delete</b>($path as xs:string, $recursive as xs:boolean) as empty-sequence()</code>  
+
|- valign="top"
|-
+
| width='120' | '''Signature'''
| <b>Summary</b>
+
|<pre>file:append-text(
| Deletes a file.
+
  $path     as xs:string,
|-
+
  $value    as xs:string,
| <b>Rules</b>
+
  $encoding  as xs:string  := ()
| This function deletes a file or directory from the file system.<br />If the optional parameter <code>$recursive</code> is provided, the operation is performed recursively for all sub-directories of the given directory.<br />  
+
) as empty-sequence()</pre>
|-
+
|- valign="top"
| <b>Errors</b>
+
| '''Summary'''
| <b>[FOFL0005]</b> is raised if the file/directory pointed by <code>$path</code> is write-protected and cannot be deleted.<br /> <b>[FOFL0006]</b> is raised if the file/directory pointed by <code>$path</code> does not exist.<br /> <b>[FOFL0013]</b> is raised if the file/directory pointed by <code>$path</code> cannot be deleted for some other reason.<br />  
+
|Appends a string to a file specified by {{Code|$path}}. If the specified file does not exists, a new file is created.<br/>The optional parameter {{Code|$encoding}} defines the output encoding (default: UTF-8).<br/>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|no-dir|#Errors}} the parent of specified path is no directory.<br/>{{Error|is-dir|#Errors}} the specified path is a directory.<br/>{{Error|unknown-encoding|#Errors}} the specified encoding is not supported, or unknown.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 +
|}
 +
 
 +
==file:append-text-lines==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:append-text-lines(
 +
  $path     as xs:string,
 +
  $values    as xs:string*,
 +
  $encoding  as xs:string  := ()
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 +
| '''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.<br/>The optional parameter {{Code|$encoding}} defines the output encoding (default: UTF-8).<br/>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|no-dir|#Errors}} the parent of specified path is no directory.<br/>{{Error|is-dir|#Errors}} the specified path is a directory.<br/>{{Error|unknown-encoding|#Errors}} the specified encoding is not supported, or unknown.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 
|}
 
|}
  
 
==file:copy==
 
==file:copy==
  
{|
+
{| width='100%'
|-
+
|- valign="top"
| width="90" | <b>Signatures</b>
+
| width='120' | '''Signature'''
|<code><b>file:copy</b>($source as xs:string, $target as xs:string) as empty-sequence()</code><br /><code><b>file:copy</b>($source as xs:string, $target as xs:string, $overwrite as xs:boolean) as empty-sequence()</code>  
+
|<pre>file:copy(
|-
+
  $source as xs:string,
| <b>Summary</b>
+
  $target as xs:string
| Copies a file.
+
) as empty-sequence()</pre>
|-
+
|- valign="top"
| <b>Rules</b>
+
| '''Summary'''
| This function copies a file specified by <code>$source</code> to <code>$target</code>.<br />If the optional parameter <code>$overwrite</code> is provided and evaluates to <code>true</code>, the target file, if it exists, will be overwritten.<br />  
+
|Copies a file or directory specified by {{Code|$source}} to the file or directory specified by {{Code|$target}}. If the target file already exists, it will be overwritten. No operation will be performed if the source and target path are equal.<br/>
|-
+
|- valign="top"
| <b>Errors</b>
+
| '''Errors'''
| <b>[FOFL0006]</b> is raised if the file pointed by <code>$source</code> does not exist.<br /> <b>[FOFL0008]</b>  is raised if the file to be copied already exists in the specified target and the <code>$overwrite</code> parameter is missing or evaluates to <code>false</code>.<br /> <b>[FOFL0016]</b>  is raised if the source file cannot be copied because of some other reason.<br />
+
|{{Error|not-found|#Errors}} the specified source does not exist.<br/>{{Error|exists|#Errors}} the specified source is a directory and the target is a file.<br/>{{Error|no-dir|#Errors}} the parent of the specified target is no directory.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
 
|}
 
|}
  
 
==file:move==
 
==file:move==
  
{|
+
{| width='100%'
|-
+
|- valign="top"
| width="90" | <b>Signatures</b>
+
| width='120' | '''Signature'''
|<code><b>file:move</b>($source as xs:string, $target as xs:string) as empty-sequence()</code>  
+
|<pre>file:move(
|-
+
  $source as xs:string,
| <b>Summary</b>
+
  $target as xs:string
| Moves a file.
+
) as empty-sequence()</pre>
|-
+
|- valign="top"
| <b>Rules</b>
+
| '''Summary'''
| This function moves/renames the file pointed by <code>$source</code> to <code>$target</code>.<br />
+
|Moves or renames the file or directory specified by {{Code|$source}} to the path specified by {{Code|$target}}. If the target file already exists, it will be overwritten. No operation will be performed if the source and target path are equal.<br/>
|-
+
|- valign="top"
| <b>Errors</b>
+
| '''Errors'''
| <b>[FOFL0006]</b> is raised if the file pointed by <code>$source</code> does not exist.<br /> <b>[FOFL0008]</b> is raised if a file/directory with the same name already exists in the given target.<br /> <b>[FOFL0009]</b> is raised if the item pointed by <code>$source</code> is a directory.<br /> <b>[FOFL0010]</b> is raised if the file pointed by <code>$source</code> is write-protected and cannot be moved.<br /> <b>[FOFL0014]</b> is raised if the file cannot be moved for some other reason.<br />  
+
|{{Error|not-found|#Errors}} the specified source does not exist.<br/>{{Error|exists|#Errors}} the specified source is a directory and the target is a file.<br/>{{Error|no-dir|#Errors}} the parent of the specified target is no directory.<br/>{{Error|io-error|#Errors}} the operation fails for some other reason.<br/>
|}  
+
|- valign="top"
+
| '''Examples'''
 +
|When renaming a file, remember that relative file paths are resolved against the current working directory. Some ways to rename:
 +
<pre lang='xquery'>
 +
file:move('/projects/new/octopus', '/projects/new/septimus')
 +
</pre>
 +
<pre lang='xquery'>
 +
$path ! file:move(., file:parent(.)||$newName)
 +
</pre>
 +
 
 +
|}
 +
 
 +
=File Properties=
 +
 
 +
==file:exists==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:exists(
 +
  $path  as xs:string
 +
) as xs:boolean</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns an {{Code|xs:boolean}} indicating whether a file or directory specified by {{Code|$path}} exists in the file system.<br/>
 +
|}
 +
 
 +
==file:is-dir==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:is-dir(
 +
  $path  as xs:string
 +
) as xs:boolean</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns an {{Code|xs:boolean}} indicating whether the argument {{Code|$path}} points to an existing directory.<br/>
 +
|}
 +
 
 +
==file:is-absolute==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:is-absolute(
 +
  $path  as xs:string
 +
) as xs:boolean</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns an {{Code|xs:boolean}} indicating whether the argument {{Code|$path}} is absolute.<br/>The behavior of this function depends on the operating system: On Windows, an absolute path starts with the drive letter and a colon, whereas on Linux it starts with a slash.
 +
|}
 +
 
 +
==file:is-file==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:is-file(
 +
  $path  as xs:string
 +
) as xs:boolean</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns an {{Code|xs:boolean}} indicating whether the argument {{Code|$path}} points to an existing file.<br/>
 +
|}
 +
 
 +
==file:last-modified==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:last-modified(
 +
  $path  as xs:string
 +
) as xs:dateTime</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Retrieves the timestamp of the last modification of the file or directory specified by {{Code|$path}}.<br/>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} the specified path does not exist.<br/>
 +
|}
 +
 
 +
==file:size==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:size(
 +
  $path  as xs:string
 +
) as xs:integer</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the size, in bytes, of the file specified by {{Code|$path}}, or {{Code|0}} for directories.<br/>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} the specified file does not exist.<br/>
 +
|}
 +
 
 +
=Path Functions=
 +
 
 +
==file:name==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:name(
 +
  $path  as xs:string
 +
) as xs:string</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the name of a file or directory specified by {{Code|$path}}. An empty string is returned if the path points to the root directory.
 +
|}
 +
 
 +
==file:parent==
 +
 
 +
{| width='100%'
 +
 
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:parent(
 +
  $path  as xs:string
 +
) as xs:string?</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the absolute path to the parent directory of a file or directory specified by {{Code|$path}}. An empty sequence is returned if the path points to a root directory.<br/>The inverse function is {{Function||file:children}}.<br/>
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* <code><nowiki>file:parent(static-base-uri())</nowiki></code> returns the directory of the current XQuery module.
 +
|}
 +
 
 +
==file:path-to-native==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:path-to-native(
 +
  $path  as xs:string
 +
) as xs:string</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Transforms the {{Code|$path}} argument to its native representation on the operating system.<br/>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} the specified file does not exist.<br/>{{Error|io-error|#Errors}} the specified path cannot be transformed to its native representation.<br/>
 +
|}
 +
 
 +
==file:resolve-path==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:resolve-path(
 +
  $path  as xs:string,
 +
  $base  as xs:string  := ()
 +
) as xs:string</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Transforms the {{Code|$path}} argument to an absolute operating system path.<br/>If the path is relative, and if an absolute {{Code|$base}} path is specified, it will be resolved against this path.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|is-relative|#Errors}} the specified base path is relative.<br/>
 +
|- valign="top"
 +
| '''Examples'''
 +
|The following examples apply to Windows:
 +
* {{Code|file:resolve-path('file.txt', 'C:/Temp/')}} returns {{Code|C:/Temp/file.txt}}.
 +
* {{Code|file:resolve-path('file.txt', 'C:/Temp')}} returns {{Code|C:/file.txt}}.
 +
* {{Code|file:resolve-path('file.txt', 'Temp')}} raises an error.
 +
|}
 +
 
 +
==file:path-to-uri==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:path-to-uri(
 +
  $path  as xs:string
 +
) as xs:string</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Transforms the path specified by {{Code|$path}} into a URI with the {{Code|file://}} scheme.<br/>
 +
|}
 +
 
 +
=System Properties=
 +
 
 +
==file:dir-separator==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|{{Code|'''file:dir-separator'''() as xs:string}}<br/>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the directory separator used by the operating system, such as {{Code|/}} or {{Code|\}}.<br/>
 +
|}
 +
 
 
==file:path-separator==
 
==file:path-separator==
  
{|
+
{| width='100%'
|-
+
|- valign="top"
| width="90" | <b>Signatures</b>
+
| width='120' | '''Signature'''
|<code><b>file:path-separator</b>() as xs:string</code>
+
|{{Code|'''file:path-separator'''() as xs:string}}<br/>
|-
+
|- valign="top"
| <b>Summary</b>
+
| '''Summary'''
| Returns the path separator.
+
|Returns the path separator used by the operating system, such as {{Code|;}} or {{Code|:}}.<br/>
|-
+
|}
| <b>Rules</b>
+
 
| This function returns the path separator used by the operating system.<br />
+
==file:line-separator==
|}  
+
 
+
{| width='100%'
==file:path-to-full-path==
+
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:line-separator() as xs:string</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the line separator used by the operating system, such as {{Code|&amp;#10;}}, {{Code|&amp;#13;&amp;#10;}} or {{Code|&amp;#13;}}.<br/>
 +
|}
 +
 
 +
==file:temp-dir==
  
{|
+
{| width='100%'
|-
+
|- valign="top"
| width="90" | <b>Signatures</b>
+
| width='120' | '''Signature'''
|<code><b>file:path-to-full-path</b>($path as xs:string) as xs:string</code>  
+
|<pre>file:temp-dir() as xs:string</pre>
|-
+
|- valign="top"
| <b>Summary</b>
+
| '''Summary'''
| Returns a full path representation.
+
|Returns the system’s default temporary-file directory.<br/>
|-
+
|}
| <b>Rules</b>
+
 
| This function transforms a path into a full operating system path.<br />
+
==file:current-dir==
|}
+
 
+
{| width='100%'
==file:path-to-uri==
+
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:current-dir() as xs:string</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the ''current working directory'', i.e., the directory from which the query processor was started. This function returns the same result as the function call <code>file:resolve-path("")</code>.
 +
|}
 +
 
 +
==file:base-dir==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>file:base-dir() as xs:string?</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the parent directory of the static base URI.<br/>If the static base URI is undefined or does not point to a local resource, it returns the empty sequence. Otherwise, it returns the same result as {{Code|file:parent(static-base-uri())}}.
 +
|}
 +
 
 +
=Errors=
  
{|
+
{| class="wikitable" width="100%"
|-
+
! width="160"|Code
| width="90" | <b>Signatures</b>
+
|Description
|<code><b>file:path-to-uri</b>($path as xs:string) as xs:string</code>
+
|- valign="top"
|-
+
|{{Code|exists}}
| <b>Summary</b>
+
|A file with the same path already exists.
| Returns an URI representation.
+
|- valign="top"
|-
+
|{{Code|invalid-path}}
| <b>Rules</b>
+
|A specified path is invalid.
| This function transforms a file system path into an URI with the file:// scheme.<br />
+
|- valign="top"
 +
|{{Code|io-error}}
 +
|The operation fails for some other reason specific to the operating system.
 +
|- valign="top"
 +
|{{Code|is-dir}}
 +
|The specified path is a directory.
 +
|- valign="top"
 +
|{{Code|is-relative}}
 +
|The specified path is relative (and must be absolute).
 +
|- valign="top"
 +
|{{Code|no-dir}}
 +
|The specified path does not point to a directory.
 +
|- valign="top"
 +
|{{Code|not-found}}
 +
|A specified path does not exist.
 +
|- valign="top"
 +
|{{Code|out-of-range}}
 +
|The specified offset or length is negative, or the chosen values would exceed the file bounds.
 +
|- valign="top"
 +
|{{Code|unknown-encoding}}
 +
|The specified encoding is not supported, or unknown.
 
|}
 
|}
[[Category:XQuery]]
+
 
 +
=Changelog=
 +
 
 +
;Version 9.3
 +
* Added: {{Function||file:descendants}}
 +
 
 +
;Version 9.0
 +
* Updated: {{Function||file:read-text-lines}}: <code>$offset</code> and <code>$length</code> arguments added.
 +
 
 +
;Version 8.5
 +
* Updated: {{Function||file:read-text}}, {{Function||file:read-text-lines}}: <code>$fallback</code> argument added.
 +
 
 +
;Version 8.2
 +
* Added: {{Function||file:is-absolute}}
 +
* Updated: {{Function||file:resolve-path}}: base argument added
 +
 
 +
;Version 8.0
 +
* Added: {{Function||file:current-dir}}, {{Function||file:base-dir}}, {{Function||file:children}}
 +
 
 +
;Version 7.8
 +
* Added: {{Function||file:parent}}, {{Function||file:name}}
 +
* Updated: error codes; {{Function||file:read-binary}}, {{Function||file:write-binary}}: {{Code|$offset}} and {{Code|$length}} arguments added.
 +
* Deleted: file:base-name, file:dir-name
 +
 
 +
;Version 7.7
 +
* Added: {{Function||file:create-temp-dir}}, {{Function||file:create-temp-file}}, {{Function||file:temp-dir}}
 +
* Updated: all returned strings that refer to existing directories will be suffixed with a directory separator.
 +
 
 +
;Version 7.3
 +
* Added: {{Function||file:append-text}}, {{Function||file:write-text}}, {{Function||file:append-text-lines}}, {{Function||file:write-text-lines}}, {{Function||file:line-separator}}
 +
* Aligned with latest specification: $file:directory-separator → {{Function||file:dir-separator}}, $file:path-separator → {{Function||file:path-separator}}, file:is-directory → {{Function||file:is-dir}}, file:create-directory → {{Function||file:create-dir}}
 +
* Updated: {{Function||file:write-binary}}, {{Function||file:append-binary}}: output limited to a single value
 +
 
 +
;Version 7.2.1
 +
* Updated: {{Function||file:delete}}: {{Code|$recursive}} parameter added to prevent subdirectories from being accidentally deleted.
 +
* Fixed: {{Function||file:list}} now returns relative instead of absolute paths.

Latest revision as of 18:20, 26 March 2024

This XQuery Module contains functions related to file system operations, such as listing, reading, or writing files.

This module is based on the EXPath File Module. The following enhancements have not been added to the specification yet:

Function Description
file:descendants new function
file:is-absolute new function
file:read-text, file:read-text-lines $fallback argument added
file:read-text-lines $offset and $length arguments added
file:resolve-path $base argument added

Conventions[edit]

All functions and errors in this module are assigned to the http://expath.org/ns/file namespace, which is statically bound to the file prefix.

For serialization parameters, the http://www.w3.org/2010/xslt-xquery-serialization namespace is used, which is statically bound to the output prefix.

The error invalid-path is raised if a path is invalid.

File Paths[edit]

  • All file paths are resolved against the current working directory (the directory from which BaseX or, more generally, the Java Virtual Machine, was started). This directory can be retrieved via file:base-dir.
  • A path can be specified as local filesystem path or as file URI.
  • Returned strings that refer to existing directories are suffixed with a directory separator.

Read Operations[edit]

file:list[edit]

Signature
file:list(
  $dir        as xs:string,
  $recursive  as xs:boolean?  := false(),
  $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.
If $recursive is set to true, subdirectories will be traversed.
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 not-found: the specified file does not exist.
no-dir: the specified path does not point to a directory.
io-error: the operation fails for some other reason.
Examples Return the contents of large .txt files located in a specific directory and its subdirectories:
let $root := 'path/to/files/'
for $file in file:list($root, true(), '*.txt')
let $path := $root || $file
where file:size($path) > 1000000
return file:read-text($path)

file:children[edit]

Signature
file:children(
  $dir  as xs:string
) as xs:string*
Summary Returns the full paths to all files and directories found in the specified $dir.
The inverse function is file:parent. The returned paths start with the specified directory. The related function file:list returns relative file paths.
Errors not-found: the specified file does not exist.
no-dir: the specified path does not point to a directory.
io-error: the operation fails for some other reason.
Examples Return the contents of large .txt files located in a specific directory:
for $file in file:children('path/to/files/')
where matches($file, '.txt', 'i') and file:size($file) > 1000000
return file:read-text($$file)

file:descendants[edit]

Signature
file:descendants(
  $dir  as xs:string
) as xs:string*
Summary Returns the full paths to all files and directories found in the specified $dir and its subdirectories.
. The returned paths start with the specified directory. The related function file:list creates relative file paths.
Errors not-found: the specified file does not exist.
no-dir: the specified path does not point to a directory.
io-error: the operation fails for some other reason.
Examples Return the contents of all .txt files located in a specific directory and its subdirectories:
for $file in file:descendants('path/to/files/')
where matches($file, '.txt', 'i') and file:size($file) > 1000000
return file:read-text($$file)

file:read-binary[edit]

Signature
file:read-binary(
  $path    as xs:string,
  $offset  as xs:integer  := (),
  $length  as xs:integer  := ()
) as xs:base64Binary
Summary Reads the binary content of the file specified by $path and returns it as lazy xs:base64Binary item.
The optional parameters $offset and $length can be used to read chunks of a file.
Errors not-found: the specified file does not exist.
is-dir: the specified path is a directory.
out-of-range: the offset or length is negative, or the chosen values would exceed the file bounds.
io-error: the operation fails for some other reason.
Examples
  • lazy:cache(file:read-binary("config.data")) enforces the file access (otherwise, it will be delayed until requested first).

file:read-text[edit]

Signature
file:read-text(
  $path      as xs:string,
  $encoding  as xs:string   := (),
  $fallback  as xs:boolean?  := false()
) as xs:string
Summary Reads the textual contents of the file specified by $path and returns it as lazy xs:string item:
  • The UTF-8 default encoding can be overwritten with the optional $encoding argument.
  • By default, invalid XML characters will be rejected. If $fallback is enabled, the characters will be replaced with the Unicode replacement character FFFD (�).
Errors not-found: the specified file does not exist.
is-dir: the specified path is a directory.
unknown-encoding: the specified encoding is not supported, or unknown.
io-error: the operation fails for some other reason.
Examples
  • lazy:cache(file:read-text("ids.txt")) enforces the file access (otherwise, it will be delayed until requested first).

file:read-text-lines[edit]

Signature
file:read-text-lines(
  $path      as xs:string,
  $encoding  as xs:string    := (),
  $fallback  as xs:boolean?  := false(),
  $offset    as xs:integer?  := (),
  $length    as xs:integer?  := ()
) 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 UTF-8 default encoding can be overwritten with the optional $encoding argument.
  • By default, invalid characters will be rejected. If $fallback is set to true, these characters will be replaced with the Unicode replacement character FFFD (�).

The lines to be read can be restricted with the optional parameters $offset and $length.

Errors not-found: the specified file does not exist.
is-dir: the specified path is a directory.
unknown-encoding: the specified encoding is not supported, or unknown.
io-error: the operation fails for some other reason.

Write Operations[edit]

file:create-dir[edit]

Signature
file:create-dir(
  $dir  as xs:string
) as empty-sequence()
Summary Creates the directory specified by $dir if it does not already exist. Non-existing parent directories will be created as well.
Errors exists: the specified target exists, but is no directory.
io-error: the operation fails for some other reason.

file:create-temp-dir[edit]

Signature
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 no-dir: the specified directory points to a file.
io-error: the directory could not be created.

file:create-temp-file[edit]

Signature
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 no-dir: the specified directory points to a file.
io-error: the directory could not be created.

file:delete[edit]

Signature
file:delete(
  $path       as xs:string,
  $recursive  as xs:boolean?  := false()
) as empty-sequence()
Summary Recursively deletes a file or directory specified by $path.
The optional parameter $recursive specifies whether subdirectories will be deleted, too.
Errors not-found: the specified path does not exist.
io-error: the operation fails for some other reason.

file:write[edit]

Signature
file:write(
  $path     as xs:string,
  $input    as item()*,
  $options  as map(*)?    := map { }
) as empty-sequence()
Summary Writes serialized $input to the specified file. If the file already exists, it will be overwritten.
The $options argument contains serialization parameters. As with fn:serialize(), the parameters can be specified
  • either as children of an <output:serialization-parameters/> element:
<output:serialization-parameters>
  <output:method value='xml'/>
  <output:cdata-section-elements value="div"/>
  ...
</output:serialization-parameters>
  • or as map, which contains all key/value pairs:
map { "method": "xml", "cdata-section-elements": "div", ... }
Errors no-dir: the parent of specified path is no directory.
is-dir: the specified path is a directory.
io-error: the operation fails for some other reason.
Examples
  • file:write('data.bin', xs:hexBinary('414243')) writes a hex representation to the specified file.
  • file:write('data.bin', xs:hexBinary('414243'), map { 'method': 'basex') writes binary data to the specified file (see Serialization for more details).

file:write-binary[edit]

Signature
file:write-binary(
  $path    as xs:string,
  $value   as xs:anyAtomicType,
  $offset  as xs:integer        := ()
) 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.
If $offset is specified, data will be written at this file position. An existing file may be resized by that operation.
Errors no-dir: the parent of specified path is no directory.
is-dir: the specified path is a directory.
out-of-range: the offset is negative, or it exceeds the current file size.
io-error: the operation fails for some other reason.

file:write-text[edit]

Signature
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 no-dir: the parent of specified path is no directory.
is-dir: the specified path is a directory.
unknown-encoding: the specified encoding is not supported, or unknown.
io-error: the operation fails for some other reason.

file:write-text-lines[edit]

Signature
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 no-dir: the parent of specified path is no directory.
is-dir: the specified path is a directory.
unknown-encoding: the specified encoding is not supported, or unknown.
io-error: the operation fails for some other reason.

file:append[edit]

Signature
file:append(
  $path     as xs:string,
  $input    as item()*,
  $options  as map(*)?    := map { }
) as empty-sequence()
Summary Appends a serialized sequence of $input to the specified file, with the supplied $options as serialization parameters. If the file does not exist, a new file is created.
Errors no-dir: the parent of specified path is no directory.
is-dir: the specified path is a directory.
io-error: the operation fails for some other reason.

file:append-binary[edit]

Signature
file:append-binary(
  $path   as xs:string,
  $value  as xs:anyAtomicType
) 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 no-dir: the parent of specified path is no directory.
is-dir: the specified path is a directory.
io-error: the operation fails for some other reason.

file:append-text[edit]

Signature
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 no-dir: the parent of specified path is no directory.
is-dir: the specified path is a directory.
unknown-encoding: the specified encoding is not supported, or unknown.
io-error: the operation fails for some other reason.

file:append-text-lines[edit]

Signature
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 no-dir: the parent of specified path is no directory.
is-dir: the specified path is a directory.
unknown-encoding: the specified encoding is not supported, or unknown.
io-error: the operation fails for some other reason.

file:copy[edit]

Signature
file:copy(
  $source  as xs:string,
  $target  as xs:string
) as empty-sequence()
Summary Copies a file or directory 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 not-found: the specified source does not exist.
exists: the specified source is a directory and the target is a file.
no-dir: the parent of the specified target is no directory.
io-error: the operation fails for some other reason.

file:move[edit]

Signature
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 not-found: the specified source does not exist.
exists: the specified source is a directory and the target is a file.
no-dir: the parent of the specified target is no directory.
io-error: the operation fails for some other reason.
Examples When renaming a file, remember that relative file paths are resolved against the current working directory. Some ways to rename:
file:move('/projects/new/octopus', '/projects/new/septimus')
$path ! file:move(., file:parent(.)||$newName)

File Properties[edit]

file:exists[edit]

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

Signature
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-absolute[edit]

Signature
file:is-absolute(
  $path  as xs:string
) as xs:boolean
Summary Returns an xs:boolean indicating whether the argument $path is absolute.
The behavior of this function depends on the operating system: On Windows, an absolute path starts with the drive letter and a colon, whereas on Linux it starts with a slash.

file:is-file[edit]

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

Signature
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 not-found: the specified path does not exist.

file:size[edit]

Signature
file:size(
  $path  as xs:string
) as xs:integer
Summary Returns the size, in bytes, of the file specified by $path, or 0 for directories.
Errors not-found: the specified file does not exist.

Path Functions[edit]

file:name[edit]

Signature
file:name(
  $path  as xs:string
) as xs:string
Summary Returns the name of a file or directory specified by $path. An empty string is returned if the path points to the root directory.

file:parent[edit]

Signature
file:parent(
  $path  as xs:string
) as xs:string?
Summary Returns the absolute path to the parent directory of a file or directory specified by $path. An empty sequence is returned if the path points to a root directory.
The inverse function is file:children.
Examples
  • file:parent(static-base-uri()) returns the directory of the current XQuery module.

file:path-to-native[edit]

Signature
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 not-found: the specified file does not exist.
io-error: the specified path cannot be transformed to its native representation.

file:resolve-path[edit]

Signature
file:resolve-path(
  $path  as xs:string,
  $base  as xs:string  := ()
) as xs:string
Summary Transforms the $path argument to an absolute operating system path.
If the path is relative, and if an absolute $base path is specified, it will be resolved against this path.
Errors is-relative: the specified base path is relative.
Examples The following examples apply to Windows:
  • file:resolve-path('file.txt', 'C:/Temp/') returns C:/Temp/file.txt.
  • file:resolve-path('file.txt', 'C:/Temp') returns C:/file.txt.
  • file:resolve-path('file.txt', 'Temp') raises an error.

file:path-to-uri[edit]

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

file:dir-separator[edit]

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

file:path-separator[edit]

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

file:line-separator[edit]

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

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

file:current-dir[edit]

Signature
file:current-dir() as xs:string
Summary Returns the current working directory, i.e., the directory from which the query processor was started. This function returns the same result as the function call file:resolve-path("").

file:base-dir[edit]

Signature
file:base-dir() as xs:string?
Summary Returns the parent directory of the static base URI.
If the static base URI is undefined or does not point to a local resource, it returns the empty sequence. Otherwise, it returns the same result as file:parent(static-base-uri()).

Errors[edit]

Code Description
exists A file with the same path already exists.
invalid-path A specified path is invalid.
io-error The operation fails for some other reason specific to the operating system.
is-dir The specified path is a directory.
is-relative The specified path is relative (and must be absolute).
no-dir The specified path does not point to a directory.
not-found A specified path does not exist.
out-of-range The specified offset or length is negative, or the chosen values would exceed the file bounds.
unknown-encoding The specified encoding is not supported, or unknown.

Changelog[edit]

Version 9.3
Version 9.0
Version 8.5
Version 8.2
Version 8.0
Version 7.8
Version 7.7
Version 7.3
Version 7.2.1
  • Updated: file:delete: $recursive parameter added to prevent subdirectories from being accidentally deleted.
  • Fixed: file:list now returns relative instead of absolute paths.