administrator, editor
33
edits
Changes
Jump to navigation
Jump to search
m
For serialization parameters, the {{Code|http://www.w3.org/2010/xslt-xquery-serialization}} namespace is used, which is statically bound to the {{Code|output}} prefix.<br/>==File Paths==
{{Mark|Introduced with Version 8.0:}}
==file:copy==
{{Mark|Introduced with Version 8.0:}}
{{Mark|Introduced with Version 8.0:}}
[[Category:XQuery]]
file:size, corrected the parameter name from $file to $path to match Summary
This [[Module Library|XQuery Module]] contains functions related to file system operations, such as listing, reading, or writing files.
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"| [[#file:descendants|file:descendants]]| new function|- valign="top"| [[#file:is-absolute|file:is-absolute]]| new function|- valign="top"| [[#file:read-text|file:read-text]], [[#file:read-text-lines|file:read-text-lines]]| <code>$fallback</code> argument added|- valign="top"| [[#file:read-text-lines|file:read-text-lines]]| <code>$offset</code> and <code>$length</code> arguments added|- valign="top"| [[#file:resolve-path|file:resolve-path]]| <code>$base</code> argument added|}
=Conventions=
All functions and errors in this module are assigned to the {{Code|<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> namespaceis used, which is statically bound to the {{Code|fileoutput}} prefix.<br/> The error <code>[[#Errors|invalid-path]]</code> is raised if a path is invalid.
* 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|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. {{Error|invalid-path|#Errors}} is raised if a path is invalid.
=Read Operations=
==file:list==
{| width='100%'
|-
==file:children==
{| width='100%'
| '''Summary'''
|Returns the full paths to all files and directories found in the specified {{Code|$dir}}.<br/>The inverse function is [[#file:parent|file:parent]]. The related function [[#file:list|file:list]] returns relative file paths.
|-
| '''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 />
|}
==file:descendants==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|file:descendants|$dir as xs:string|xs:string*}}
|-
| '''Summary'''
|Returns the full paths to all files and directories found in the specified {{Code|$dir}} and its sub-directories.<br/>. The related function [[#file:list|file:list]] returns relative file paths.
|-
| '''Errors'''
|-
| '''Summary'''
|Reads the binary content of the file specified by {{Code|$path}} and returns it as [[Streaming Lazy Module|streamablelazy]] {{Code|xs:base64Binary}}item.<br />The optional parameters {{Code|$offset}} and {{Code|$length}} can be used to read chunks of a file.
|-
| '''Errors'''
| '''Examples'''
|
* <code><nowiki>streamlazy:materializecache(file:read-binary("config.data"))</nowiki></code> returns a materialized representation of enforces the streamable resultfile access (otherwise, it will be delayed until requested first).
|}
==file:read-text==
{| width='100%'
|-
| 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 />
|-
| '''Summary'''
|Reads the textual contents of the file specified by {{Code|$path}} and returns it as [[Streaming Lazy Module|streamablelazy]] {{Code|xs:string}}.<br />item:* The UTF-8 default encoding can be overwritten with the optional parameter {{Code|$encoding}} defines argument.* By default, invalid characters will be rejected. If {{Code|$fallback}} is set to true, these characters will be replaced with the encoding of the file.Unicode replacement character <code>FFFD<br /code>(�).
|-
| '''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. Invalid XML characters will be ignored if the <code>[[Options#CHECKSTRINGS|CHECKSTRINGS]]</code> option is turned off.<br />
|-
| '''Examples'''
|
* <code><nowiki>streamlazy:materializecache(file:read-text("configids.txt"))</nowiki></code> returns a materialized representation of enforces the streamable resultfile access (otherwise, it will be delayed until requested first).
|}
==file:read-text-lines==
{| width='100%'
|-
| 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 />
|-
| '''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<br /code>(�).The lines to be read can be restricted with the optional parameter parameters {{Code|$encodingoffset}} and {{Code|$length}} defines the encoding of the file.<br />
|-
| '''Errors'''
|-
| '''Summary'''
|Creates the directory specified by {{Code|$dir}}, including all nonif it does not already exist. Non-existing parent directorieswill be created as well.<br />
|-
| '''Errors'''
|{{Error|exists|#Errors}} a file with the same path already specified target exists, but is no directory.<br />{{Error|io-error|#Errors}} the operation fails for some other reason.<br />
|}
==file:delete==
{| width='100%'
|-
==file:write==
{| width='100%'
|-
|-
| '''Summary'''
|Writes a serialized sequence of items to the specified file. If the file already exists, it will be overwritten.<br />The {{Code|$params}} argument contains serialization parameters (see [[Serialization|serialization parameters]] for more details. As with [https://www.w3.org/TR/xpath-functions-31/#func-serialize fn:serialize()], which the parameters can either be specified<br />* either as children of an {{Code|<output:serialization-parameters/>}} element, as defined for the [http://www.w3.org/TR/xpath-functions-30/#func-serialize fn:serialize()] function; e.g.:<pre classsyntaxhighlight lang="brush:xml">
<output:serialization-parameters>
<output:method value='xml'/>
...
</output:serialization-parameters>
</presyntaxhighlight>* or as map, which contains all key/value pairs:<pre classsyntaxhighlight lang="brush:xmlxquery">
map { "method": "xml", "cdata-section-elements": "div", ... }
</presyntaxhighlight>
|-
| '''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 />
|-
| '''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:append==
{| width='100%'
|-
|}
==file:copy==
{| width='100%'
|-
|-
| '''Summary'''
|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 />
|-
| '''Errors'''
==file:move==
{| width='100%'
|-
==file:exists==
{| width='100%'
|-
| '''Summary'''
|Returns an {{Code|xs:boolean}} indicating whether the argument {{Code|$path}} points to an existing directory.<br />
|}
==file:is-absolute==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|file:is-absolute|$path as xs:string|xs:boolean}}<br />
|-
| '''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%'
|-
==file:last-modified==
{| width='100%'
|-
==file:size==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|file:size|$file path as xs:string|xs:integer}}<br />
|-
| '''Summary'''
==file:name==
{| width='100%'
|-
{| width='100%'
|-
| width='120' | '''Signatures'''
==file:path-to-native==
{| width='100%'
|-
==file:resolve-path==
{| width='100%'
|-
| 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 />
|-
| '''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.|-| '''Errors'''|{{Error|is-relative|#Errors}} the specified base path is relative.<br />|-| '''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%'
|-
==file:dir-separator==
{| width='100%'
|-
==file:path-separator==
{| width='100%'
|-
==file:line-separator==
{| width='100%'
|-
==file:current-dir==
{| width='100%'
|-
| '''Summary'''
|Returns the current working directory. - This function returns the same result as the function call {{Code|<code>file:resolve-path(''"")}}<br /code>.
|}
==file:base-dir==
{| width='100%'
|Description
|-
|{{Code|not-foundexists}}|A specified file with the same path does not existalready exists.
|-
|{{Code|invalid-path}}
|A specified path is invalid.
|-
|{{Code|existsio-error}}|A file with The operation fails for some other reason specific to the same operating system.|-|{{Code|is-dir}}|The specified path is a directory.|-|{{Code|is-relative}}|The specified path already existsis relative (and must be absolute).
|-
|{{Code|no-dir}}
|The specified path does not point to a directory.
|-
|{{Code|isnot-dirfound}}|The A specified path is a directory.|-|{{Code|unknown-encoding}}|The specified encoding is does not supported, or unknownexist.
|-
|{{Code|out-of-range}}
|The specified offset or length is negative, or the chosen values would exceed the file bounds.
|-
|{{Code|iounknown-errorencoding}}|The operation fails for some other reason specific to the operating systemspecified encoding is not supported, or unknown.
|}
=Changelog=
;Version 9.3
* Added: [[#file:descendants|file:descendants]]
;Version 9.0
* Updated: [[#file:read-text-lines|file:read-text-lines]]: <code>$offset</code> and <code>$length</code> arguments added.
;Version 8.5
* Updated: [[#file:read-text|file:read-text]], [[#file:read-text-lines|file:read-text-lines]]: <code>$fallback</code> argument added.
;Version 8.2
* Added: [[#file:is-absolute|file:is-absolute]]
* Updated: [[#file:resolve-path|file:resolve-path]]: base argument added
;Version 8.0
* Updated: [[#file:delete|file:delete]]: {{Code|$recursive}} parameter added to prevent sub-directories from being accidentally deleted.
* Fixed: [[#file:list|file:list]] now returns relative instead of absolute paths.
