Difference between revisions of "File Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replacement - "<br />" to "<br/>")
Line 47: Line 47:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:list|$dir as xs:string|xs:string*}}<br/>{{Func|file:list|$dir as xs:string, $recursive as xs:boolean|xs:string*}}<br/>{{Func|file:list|$dir as xs:string, $recursive as xs:boolean, $pattern as xs:string|xs:string*}}<br/>
+
|<pre>file:list(
 +
  $dir       as xs:string
 +
  $recursive as xs:boolean := ()
 +
  $pattern    as xs:string   := ()
 +
) as xs:string*</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 71: Line 75:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:children|$dir as xs:string|xs:string*}}
+
|<pre>file:children(
 +
  $dir as xs:string
 +
) as xs:string*</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 93: Line 99:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:descendants|$dir as xs:string|xs:string*}}
+
|<pre>file:descendants(
 +
  $dir as xs:string
 +
) as xs:string*</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 115: Line 123:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:read-binary|$path as xs:string|xs:base64Binary}}<br/>{{Func|file:read-binary|$path as xs:string, $offset as xs:integer|xs:base64Binary}}<br/>{{Func|file:read-binary|$path as xs:string, $offset as xs:integer, $length as xs:integer|xs:base64Binary}}
+
|<pre>file:read-binary(
 +
  $path   as xs:string
 +
  $offset as xs:integer := ()
 +
  $length  as xs:integer  := ()
 +
) as xs:base64Binary</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 133: Line 145:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:read-text|$path as xs:string|xs:string}}<br/>{{Func|file:read-text|$path as xs:string, $encoding as xs:string|xs:string}}<br/>{{Func|file:read-text|$path as xs:string, $encoding as xs:string, $fallback as xs:boolean|xs:string}}<br/>
+
|<pre>file:read-text(
 +
  $path     as xs:string
 +
  $encoding as xs:string   := ()
 +
  $fallback  as xs:boolean  := ()
 +
) as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 153: Line 169:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:read-text-lines|$path as xs:string|xs:string*}}<br/>{{Func|file:read-text-lines|$path as xs:string, $encoding as xs:string|xs:string*}}<br/>{{Func|file:read-text-lines|$path as xs:string, $encoding as xs:string, $fallback as xs:boolean|xs:string*}}<br/>{{Func|file:read-text-lines|$path as xs:string, $encoding as xs:string, $fallback as xs:boolean, $offset as xs:integer|xs:string*}}<br/>{{Func|file:read-text-lines|$path as xs:string, $encoding as xs:string, $fallback as xs:boolean, $offset as xs:integer, $length as xs:integer|xs:string*}}<br/>
+
|<pre>file:read-text-lines(
 +
  $path     as xs:string
 +
  $encoding as xs:string   := ()
 +
  $fallback as xs:boolean := ()
 +
  $offset   as xs:integer := ()
 +
  $length    as xs:integer  := ()
 +
) as xs:string*</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 172: Line 194:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:create-dir|$dir as xs:string|empty-sequence()}}<br/>
+
|<pre>file:create-dir(
 +
  $dir as xs:string
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 186: Line 210:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:create-temp-dir|$prefix as xs:string, $suffix as xs:string|xs:string}}<br/>{{Func|file:create-temp-dir|$prefix as xs:string, $suffix as xs:string, $dir as xs:string|xs:string}}
+
|<pre>file:create-temp-dir(
 +
  $prefix as xs:string
 +
  $suffix as xs:string
 +
  $dir     as xs:string := ()
 +
) as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 200: Line 228:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:create-temp-file|$prefix as xs:string, $suffix as xs:string|xs:string}}<br/>{{Func|file:create-temp-file|$prefix as xs:string, $suffix as xs:string, $dir as xs:string|xs:string}}
+
|<pre>file:create-temp-file(
 +
  $prefix as xs:string
 +
  $suffix as xs:string
 +
  $dir     as xs:string := ()
 +
) as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 214: Line 246:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:delete|$path as xs:string|empty-sequence()}}<br/>{{Func|file:delete|$path as xs:string, $recursive as xs:boolean|empty-sequence()}}<br/>
+
|<pre>file:delete(
 +
  $path       as xs:string
 +
  $recursive as xs:boolean := ()
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 228: Line 263:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:write|$path as xs:string, $items as item()*|empty-sequence()}}<br/>{{Func|file:write|$path as xs:string, $items as item()*, $params as item()|empty-sequence()}}<br/>
+
|<pre>file:write(
 +
  $path   as xs:string
 +
  $items   as item()*
 +
  $params as item()     := ()
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 259: Line 298:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:write-binary|$path as xs:string, $value as xs:anyAtomicType|empty-sequence()}}<br/>{{Func|file:write-binary|$path as xs:string, $value as xs:anyAtomicType, $offset as xs:integer|empty-sequence()}}<br/>
+
|<pre>file:write-binary(
 +
  $path   as xs:string
 +
  $value   as xs:anyAtomicType
 +
  $offset as xs:integer       := ()
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 273: Line 316:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:write-text|$path as xs:string, $value as xs:string|empty-sequence()}}<br/>{{Func|file:write-text|$path as xs:string, $value as xs:string, $encoding as xs:string|empty-sequence()}}<br/>
+
|<pre>file:write-text(
 +
  $path     as xs:string
 +
  $value     as xs:string
 +
  $encoding as xs:string := ()
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 287: Line 334:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:write-text-lines|$path as xs:string, $values as xs:string*|empty-sequence()}}<br/>{{Func|file:write-text-lines|$path as xs:string, $values as xs:string*, $encoding as xs:string|empty-sequence()}}<br/>
+
|<pre>file:write-text-lines(
 +
  $path     as xs:string
 +
  $values   as xs:string*
 +
  $encoding as xs:string   := ()
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 301: Line 352:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:append|$path as xs:string, $items as item()*|empty-sequence()}}<br/>{{Func|file:append|$path as xs:string, $items as item()*, $params as item()|empty-sequence()}}<br/>
+
|<pre>file:append(
 +
  $path   as xs:string
 +
  $items   as item()*
 +
  $params as item()     := ()
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 315: Line 370:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:append-binary|$path as xs:string, $value as xs:anyAtomicType|empty-sequence()}}<br/>
+
|<pre>file:append-binary(
 +
  $path   as xs:string
 +
  $value as xs:anyAtomicType
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 329: Line 387:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:append-text|$path as xs:string, $value as xs:string|empty-sequence()}}<br/>{{Func|file:append-text|$path as xs:string, $value as xs:string, $encoding as xs:string|empty-sequence()}}<br/>
+
|<pre>file:append-text(
 +
  $path     as xs:string
 +
  $value     as xs:string
 +
  $encoding as xs:string := ()
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 343: Line 405:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:append-text-lines|$path as xs:string, $values as xs:string*|empty-sequence()}}<br/>{{Func|file:append-text-lines|$path as xs:string, $values as xs:string*, $encoding as xs:string|empty-sequence()}}<br/>
+
|<pre>file:append-text-lines(
 +
  $path     as xs:string
 +
  $values   as xs:string*
 +
  $encoding as xs:string   := ()
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 357: Line 423:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:copy|$source as xs:string, $target as xs:string|empty-sequence()}}<br/>
+
|<pre>file:copy(
 +
  $source as xs:string
 +
  $target as xs:string
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 371: Line 440:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:move|$source as xs:string, $target as xs:string|empty-sequence()}}<br/>
+
|<pre>file:move(
 +
  $source as xs:string
 +
  $target as xs:string
 +
) as empty-sequence()</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 397: Line 469:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:exists|$path as xs:string|xs:boolean}}<br/>
+
|<pre>file:exists(
 +
  $path as xs:string
 +
) as xs:boolean</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 408: Line 482:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:is-dir|$path as xs:string|xs:boolean}}<br/>
+
|<pre>file:is-dir(
 +
  $path as xs:string
 +
) as xs:boolean</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 419: Line 495:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:is-absolute|$path as xs:string|xs:boolean}}<br/>
+
|<pre>file:is-absolute(
 +
  $path as xs:string
 +
) as xs:boolean</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 430: Line 508:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:is-file|$path as xs:string|xs:boolean}}<br/>
+
|<pre>file:is-file(
 +
  $path as xs:string
 +
) as xs:boolean</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 441: Line 521:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:last-modified|$path as xs:string|xs:dateTime}}<br/>
+
|<pre>file:last-modified(
 +
  $path as xs:string
 +
) as xs:dateTime</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 455: Line 537:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:size|$path as xs:string|xs:integer}}<br/>
+
|<pre>file:size(
 +
  $path as xs:string
 +
) as xs:integer</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 471: Line 555:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:name|$path as xs:string|xs:string}}
+
|<pre>file:name(
 +
  $path as xs:string
 +
) as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 483: Line 569:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:parent|$path as xs:string|xs:string?}}<br/>
+
|<pre>file:parent(
 +
  $path as xs:string
 +
) as xs:string?</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 498: Line 586:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:path-to-native|$path as xs:string|xs:string}}<br/>
+
|<pre>file:path-to-native(
 +
  $path as xs:string
 +
) as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 512: Line 602:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:resolve-path|$path as xs:string|xs:string}}<br/>{{Func|file:resolve-path|$path as xs:string, $base as xs:string|xs:string}}<br/>
+
|<pre>file:resolve-path(
 +
  $path as xs:string
 +
  $base as xs:string := ()
 +
) as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 532: Line 625:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:path-to-uri|$path as xs:string|xs:string}}<br/>
+
|<pre>file:path-to-uri(
 +
  $path as xs:string
 +
) as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 567: Line 662:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:line-separator||xs:string}}
+
|<pre>file:line-separator() as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 578: Line 673:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:temp-dir||xs:string}}
+
|<pre>file:temp-dir() as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 589: Line 684:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:current-dir||xs:string}}
+
|<pre>file:current-dir() as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 600: Line 695:
 
|- valign="top"
 
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|file:base-dir||xs:string?}}
+
|<pre>file:base-dir() as xs:string?</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''

Revision as of 13:05, 9 March 2023

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

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

  • 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

file:list

Signatures 
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 subdirectories 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 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 .txt} files located in a specific directory and its subdirectories:

<syntaxhighlight 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) </syntaxhighlight>

file:children

Signatures 
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:

<syntaxhighlight 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) </syntaxhighlight>

file:descendants

Signatures 
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:

<syntaxhighlight 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) </syntaxhighlight>

file:read-binary

Signatures 
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

Signatures 
file:read-text(
  $path      as xs:string
  $encoding  as xs:string   := ()
  $fallback  as xs:boolean  := ()
) 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 characters will be rejected. If $fallback is set to true, these 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

Signatures 
file:read-text-lines(
  $path      as xs:string
  $encoding  as xs:string   := ()
  $fallback  as xs:boolean  := ()
  $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

file:create-dir

Signatures 
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

Signatures 
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

Signatures 
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

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

Signatures 
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. As with fn:serialize(), the parameters can be specified
  • either as children of an <output:serialization-parameters/> element:

<syntaxhighlight lang="xml"> <output:serialization-parameters> 

 <output:method value='xml'/>
 <output:cdata-section-elements value="div"/>
 ...

</output:serialization-parameters> </syntaxhighlight>

  • or as map, which contains all key/value pairs:

<syntaxhighlight lang="xquery"> map { "method": "xml", "cdata-section-elements": "div", ... } </syntaxhighlight>

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

Signatures 
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

Signatures 
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

Signatures 
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

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

Signatures 
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

Signatures 
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

Signatures 
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

Signatures 
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

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

<syntaxhighlight lang="xquery"> file:move('/projects/new/octopus', '/projects/new/septimus') </syntaxhighlight> <syntaxhighlight lang="xquery"> $path ! file:move(., file:parent(.)||$newName) </syntaxhighlight>

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

Signatures 
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

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

file:size

Signatures 
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

file:name

Signatures 
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

Signatures 
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

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

file:resolve-path

Signatures 
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

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

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

file:current-dir

Signatures 
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

Signatures 
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

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

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