Changes

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|<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 [[#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.

|Lists all files and directories found in the specified {{Code|$dir}}. The returned paths are relative to the provided path.<br />The optional parameter {{Code|$recursive}} specifies whether sub-directories will be traversed, too.<br />The optional parameter {{Code|$pattern}} defines a file name pattern in the [http://en.wikipedia.org/wiki/Glob_(programming) glob syntax[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 />

|{{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:children== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|file:children|$dir as xs:string|xs:string*}}|-| '''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 />

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

|{{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 />

* <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).

|{{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 />

|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>(&#xFFFD;).

|{{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 />

* <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).

|{{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 />

|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>(&#xFFFD;).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 />

map { "method" := "xml", "cdata-section-elements" := "div", ... }

|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 to at this file position. An existing file may be resized by that operation.

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

|Returns the size, in bytes, of the file specified by {{Code|$path}}, or {{Code|0}} for directories.<br />

|{{Error|not-found|#Errors}} the specified file does not exist.<br />{{Error|is-dir|#Errors}} the specified file points to a directory.<br />

|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, or if it contains no directory separators.

==file:dir-nameparent== [[Mark|Introduced with Version 7.8:]]

|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, or if it contains no directory separators.<br/>The inverse function is [[#file:children|file:children]].<br />

|{{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 />

|{{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 />

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

|{{CodeFunc|'''file:line-separator'''() as ||xs:string}}<br />

|{{CodeFunc|'''file:temp-dir'''() as ||xs:string}}<br />

! width="240160"|Code

|{{Code|noinvalid-dirpath}}|The A specified path does not point is invalid.|-|{{Code|io-error}}|The operation fails for some other reason specific to a directorythe operating system.

|{{Code|unknownis-encodingrelative}}|The specified encoding path is relative (and must be absolute).|-|{{Code|no-dir}}|The specified path does not point to a directory.|-|{{Code|not-found}}|A specified path does not supported, or unknownexist.

|{{Code|iounknown-errorencoding}}|The operation fails for some other reason specific to the operating systemspecified encoding is not supported, or unknown.