Difference between revisions of "File Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replace - "{{Mono|" to "{{Code|")
Line 3: Line 3:
 
=Conventions=
 
=Conventions=
  
−
All functions in this module are assigned to the <code>http://expath.org/ns/file</code> namespace, which is statically bound to the <code>file</code> prefix.<br/>
+
All functions in this module are assigned to the {{Code|http://expath.org/ns/file}} namespace, which is statically bound to the {{Code|file}} prefix.<br/>
−
All errors are assigned to the <code>http://expath.org/ns/error</code> namespace, which is statically bound to the <code>exerr</code> prefix.
+
All errors are assigned to the {{Code|http://expath.org/ns/error}} namespace, which is statically bound to the {{Code|exerr}} prefix.
  
 
=Variables=
 
=Variables=
Line 12: Line 12:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>$file:directory-separator</b> as xs:string</code><br />
+
|{{Code|'''$file:directory-separator''' as xs:string}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 22: Line 22:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>$file:path-separator</b> as xs:string</code><br />
+
|{{Code|'''$file:path-separator''' as xs:string}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 34: Line 34:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:exists</b>($path as xs:string) as xs:boolean</code><br />
+
|{{Func|file:exists|$path as xs:string|xs:boolean}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Returns an <code>xs:boolean</code> indicating whether a file or directory specified by <code>$path</code> exists in the file system.<br />
+
|Returns an {{Code|xs:boolean}} indicating whether a file or directory specified by {{Code|$path}} exists in the file system.<br />
 
|}
 
|}
  
Line 44: Line 44:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:is-directory</b>($path as xs:string) as xs:boolean</code><br />
+
|{{Func|file:is-directory|$path as xs:string|xs:boolean}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Returns an <code>xs:boolean</code> indicating whether the argument <code>$path</code> points to an existing directory.<br />
+
|Returns an {{Code|xs:boolean}} indicating whether the argument {{Code|$path}} points to an existing directory.<br />
 
|}
 
|}
  
Line 54: Line 54:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:is-file</b>($path as xs:string) as xs:boolean</code><br />
+
|{{Func|file:is-file|$path as xs:string|xs:boolean}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Returns an <code>xs:boolean</code> indicating whether the argument <code>$path</code> points to an existing file.<br />
+
|Returns an {{Code|xs:boolean}} indicating whether the argument {{Code|$path}} points to an existing file.<br />
 
|}
 
|}
  
Line 64: Line 64:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:last-modified</b>($path as xs:string) as xs:dateTime</code><br />
+
|{{Func|file:last-modified|$path as xs:string|xs:dateTime}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Retrieves the timestamp of the last modification of the file or directory specified by <code>$path</code>.<br />
+
|Retrieves the timestamp of the last modification of the file or directory specified by {{Code|$path}}.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0001]]</b> is raised if the specified path does not exist.<br />
+
|{{Error|FOFL0001|#Errors}} the specified path does not exist.<br />
 
|}
 
|}
  
Line 77: Line 77:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:size</b>($file as xs:string) as xs:integer</code><br />
+
|{{Func|file:size|$file as xs:string|xs:integer}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the size, in bytes, of the file specified by <code>$path</code>.<br />
+
|Returns the size, in bytes, of the file specified by {{Code|$path}}.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0001]]</b> is raised if the specified file does not exist.<br /><b>[[#Errors|FOFL0004]]</b> is raised if the specified file points to a directory.<br />
+
|{{Error|FOFL0001|#Errors}} the specified file does not exist.<br />{{Error|FOFL0004|#Errors}} the specified file points to a directory.<br />
 
|}
 
|}
  
Line 90: Line 90:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:base-name</b>($path as xs:string) as xs:string</code><br /><code><b>file:base-name</b>($path as xs:string, $suffix as xs:string) as xs:string</code><br />
+
|{{Func|file:base-name|$path as xs:string|xs:string}}<br />{{Func|file:base-name|$path as xs:string, $suffix as xs:string|xs:string}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the base-name of the path specified by <code>$path</code>, which is the component after the last directory separator.<br />If <code>$suffix</code> is specified, it will be trimmed from the end of the result.<br />
+
|Returns the base-name of the path specified by {{Code|$path}}, which is the component after the last directory separator.<br />If {{Code|$suffix}} is specified, it will be trimmed from the end of the result.<br />
 
|}
 
|}
  
Line 100: Line 100:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:dir-name</b>($path as xs:string) as xs:string</code><br />
+
|{{Func|file:dir-name|$path as xs:string|xs:string}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the parent directory of the path specified by <code>$path</code>, which is the component before the last directory separator.<br />
+
|Returns the parent directory of the path specified by {{Code|$path}}, which is the component before the last directory separator.<br />
 
|}
 
|}
  
Line 110: Line 110:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:path-to-native</b>($path as xs:string) as xs:string</code><br />
+
|{{Func|file:path-to-native|$path as xs:string|xs:string}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Transforms the <code>$path</code> argument to its native representation on the operating system.<br />
+
|Transforms the {{Code|$path}} argument to its native representation on the operating system.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL9999]]</b> is raised if the specified path cannot be transformed to its native representation.<br />
+
|{{Error|FOFL9999|#Errors}} the specified path cannot be transformed to its native representation.<br />
 
|}
 
|}
  
Line 123: Line 123:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:resolve-path</b>($path as xs:string) as xs:string</code><br />
+
|{{Func|file:resolve-path|$path as xs:string|xs:string}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Transforms the <code>$path</code> argument to an absolute operating system path.<br />
+
|Transforms the {{Code|$path}} argument to an absolute operating system path.<br />
 
|}
 
|}
  
Line 133: Line 133:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:path-to-uri</b>($path as xs:string) as xs:string</code><br />
+
|{{Func|file:path-to-uri|$path as xs:string|xs:string}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Transforms the path specified by <code>$path</code> into a URI with the <code>file://</code> scheme.<br />
+
|Transforms the path specified by {{Code|$path}} into a URI with the {{Code|file://}} scheme.<br />
 
|}
 
|}
  
Line 143: Line 143:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:list</b>($directory as xs:string) as xs:string*</code><br /><code><b>file:list</b>($directory as xs:string, $recursive as xs:boolean) as xs:string*</code><br /><code><b>file:list</b>($directory as xs:string, $recursive as xs:boolean, $pattern as xs:string) as xs:string*</code><br />
+
|{{Func|file:list|$directory as xs:string|xs:string*}}<br />{{Func|file:list|$directory as xs:string, $recursive as xs:boolean|xs:string*}}<br />{{Func|file:list|$directory as xs:string, $recursive as xs:boolean, $pattern as xs:string|xs:string*}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Lists all files and directories found in the specified <code>$directory</code>. The returned paths are relative to the provided path.<br />The optional parameter <code>$recursive</code> specifies whether sub-directories will be traversed, too.<br />The optional parameter <code>$pattern</code> defines a file name pattern in the [http://en.wikipedia.org/wiki/Glob_(programming) 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>,</code>).<br />
+
|Lists all files and directories found in the specified {{Code|$directory}}. 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]. If present, only those files and directories are returned that correspond to the pattern. Several patterns can be separated with a comma ({{Code|,}}).<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0003]]</b> is raised if the specified path does not point to a directory.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0003|#Errors}} the specified path does not point to a directory.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 156: Line 156:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:create-directory</b>($directory as xs:string) as empty-sequence()</code><br />
+
|{{Func|file:create-directory|$directory as xs:string|empty-sequence()}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Recursively creates the directories specified by <code>$directory</code>.<br />
+
|Recursively creates the directories specified by {{Code|$directory}}.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0002]]</b> is raised if a file with the same path already exists.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0002|#Errors}} a file with the same path already exists.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 170: Line 170:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<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><br />
+
|{{Func|file:delete|$path as xs:string|empty-sequence()}}<br />{{Func|file:delete|$path as xs:string, $recursive as xs:boolean|empty-sequence()}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Recursively deletes a file or directory specified by <code>$path</code>.<br />The optional parameter <code>$recursive</code> specifies whether sub-directories will be deleted, too.<br />
+
|Recursively deletes a file or directory specified by {{Code|$path}}.<br />The optional parameter {{Code|$recursive}} specifies whether sub-directories will be deleted, too.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0001]]</b> is raised if the specified path does not exist.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0001|#Errors}} the specified path does not exist.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 183: Line 183:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:read-text</b>($path as xs:string) as xs:string</code><br /><code><b>file:read-text</b>($path as xs:string, $encoding as xs:string) as xs:string</code><br />
+
|{{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 />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Reads the textual contents of the file specified by <code>$path</code> and returns it as a <code>xs:string</code>.<br />The optional parameter <code>$encoding</code> defines the encoding of the file.<br />
+
|Reads the textual contents of the file specified by {{Code|$path}} and returns it as a {{Code|xs:string}}.<br />The optional parameter {{Code|$encoding}} defines the encoding of the file.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0001]]</b> is raised if the specified file does not exist.<br /><b>[[#Errors|FOFL0004]]</b> is raised if the specified path is a directory.<br /><b>[[#Errors|FOFL0005]]</b> is raised if the specified encoding is not supported, or unknown.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0001|#Errors}} the specified file does not exist.<br />{{Error|FOFL0004|#Errors}} the specified path is a directory.<br />{{Error|FOFL0005|#Errors}} the specified encoding is not supported, or unknown.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 196: Line 196:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:read-text-lines</b>($path as xs:string) as xs:string</code><br /><code><b>file:read-text-lines</b>($path as xs:string, $encoding as xs:string) as xs:string*</code><br />
+
|{{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 />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Reads the textual contents of the file specified by <code>$path</code> and returns it as a sequence of <code>xs:string</code> items.<br />The optional parameter <code>$encoding</code> defines the encoding of the file.<br />
+
|Reads the textual contents of the file specified by {{Code|$path}} and returns it as a sequence of {{Code|xs:string}} items.<br />The optional parameter {{Code|$encoding}} defines the encoding of the file.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0001]]</b> is raised if the specified file does not exist.<br /><b>[[#Errors|FOFL0004]]</b> is raised if the specified path is a directory.<br /><b>[[#Errors|FOFL0005]]</b> is raised if the specified encoding is not supported, or unknown.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0001|#Errors}} the specified file does not exist.<br />{{Error|FOFL0004|#Errors}} the specified path is a directory.<br />{{Error|FOFL0005|#Errors}} the specified encoding is not supported, or unknown.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 209: Line 209:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:read-binary</b>($path as xs:string) as xs:base64Binary</code><br />
+
|{{Func|file:read-binary|$path as xs:string|xs:base64Binary}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Reads the binary content of the file specified by <code>$path</code> and returns as a <code>xs:base64Binary</code>.<br />
+
|Reads the binary content of the file specified by {{Code|$path}} and returns as a {{Code|xs:base64Binary}}.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0001]]</b> is raised if the specified file does not exist.<br /><b>[[#Errors|FOFL0004]]</b> is raised if the specified path is a directory.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0001|#Errors}} the specified file does not exist.<br />{{Error|FOFL0004|#Errors}} the specified path is a directory.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 222: Line 222:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:write</b>($path as xs:string, $items as item()*) as empty-sequence()</code><br /><code><b>file:write</b>($path as xs:string, $items as item()*, $params as xs:node()*) as empty-sequence()</code><br />
+
|{{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 xs:node()*|empty-sequence()}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Writes a sequence of <code>$items</code> to a file specified by <code>$path</code>. If the specified file already exists, it will be overwritten.<br />The optional argument <code>$params</code> is used to set the serialization parameters  (see [[Serialization]] for more details).It can be specified as<br />
+
|Writes a sequence of {{Code|$items}} to a file specified by {{Code|$path}}. If the specified file already exists, it will be overwritten.<br />The optional argument {{Code|$params}} is used to set the serialization parameters  (see [[Serialization]] for more details).It can be specified as<br />
−
* <code>element(serialization-parameters)</code>: <code>&lt;serialization-parameters/&gt;</code> must be used as root element, and the parameters are specified as child nodes, with the element name representing the serialization parameter and the attribute <code>value</code> representing its value:<br /><code>&lt;serialization-parameters xmlns="http://www.w3.org/2010/xslt-xquery-serialization"&gt;<br/>&nbsp;&nbsp;&lt;method value='xml'/&gt;<br/>&nbsp;&nbsp;&lt;cdata-section-elements value="div"/&gt;<br/>&nbsp;&nbsp;...<br/>&lt;/serialization-parameters&gt;</code>
+
* {{Code|element(serialization-parameters)}}: {{Code|&lt;serialization-parameters/&gt;}} must be used as root element, and the parameters are specified as child nodes, with the element name representing the serialization parameter and the attribute {{Code|value}} representing its value:<br />{{Code|&lt;serialization-parameters xmlns="http://www.w3.org/2010/xslt-xquery-serialization"&gt;<br/>&nbsp;&nbsp;&lt;method value='xml'/&gt;<br/>&nbsp;&nbsp;&lt;cdata-section-elements value="div"/&gt;<br/>&nbsp;&nbsp;...<br/>&lt;/serialization-parameters&gt;}}
−
* [[Map Module|map structure]]: all parameters can be directly represented as key/value pairs:<br /><code>map { "method" := "xml", "cdata-section-elements" := "div", ... </code>}<br/>
+
* [[Map Module|map structure]]: all parameters can be directly represented as key/value pairs:<br />{{Code|map { "method" := "xml", "cdata-section-elements" := "div", ... }}}<br/>
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0004]]</b> is raised if the specified path is a directory.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0004|#Errors}} the specified path is a directory.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 237: Line 237:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:write-binary</b>($path as xs:string, $items as xs:base64Binary*) as empty-sequence()</code><br />
+
|{{Func|file:write-binary|$path as xs:string, $items as xs:base64Binary*|empty-sequence()}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Writes a sequence of <code>xs:basex64Binary</code> <code>$items</code> to a file specified by <code>$path</code>. If the specified file already exists, it will be overwritten.<br />
+
|Writes a sequence of {{Code|xs:basex64Binary}} {{Code|$items}} to a file specified by {{Code|$path}}. If the specified file already exists, it will be overwritten.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0004]]</b> is raised if the specified path is a directory.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0004|#Errors}} the specified path is a directory.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 250: Line 250:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:append</b>($path as xs:string, $items as item()*) as empty-sequence()</code><br /><code><b>file:append</b>($path as xs:string, $items as item()*, $params as xs:node()*) as empty-sequence()</code><br />
+
|{{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 xs:node()*|empty-sequence()}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Appends a sequence of <code>$items</code> to a file specified by <code>$path</code>. If the specified file does not exists, a new file is created.<br />
+
|Appends a sequence of {{Code|$items}} to a file specified by {{Code|$path}}. If the specified file does not exists, a new file is created.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0004]]</b> is raised if the specified path is a directory.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0004|#Errors}} the specified path is a directory.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 263: Line 263:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:append-binary</b>($path as xs:string, $items as xs:base64Binary*) as empty-sequence()</code><br />
+
|{{Func|file:append-binary|$path as xs:string, $items as xs:base64Binary*|empty-sequence()}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Appends a sequence of <code>xs:basex64Binary</code> <code>$items</code> to a file specified by <code>$path</code>. If the specified file does not exists, a new file is created.<br />
+
|Appends a sequence of {{Code|xs:basex64Binary}} {{Code|$items}} to a file specified by {{Code|$path}}. If the specified file does not exists, a new file is created.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0004]]</b> is raised if the specified path is a directory.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0004|#Errors}} the specified path is a directory.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 276: Line 276:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:copy</b>($source as xs:string, $target as xs:string) as empty-sequence()</code><br />
+
|{{Func|file:copy|$source as xs:string, $target as xs:string|empty-sequence()}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Copies a file specified by <code>$source</code> to the file or directory specified by <code>$target</code>. If the target represents an existing file, it will be overwritten. No operation will be performed if the source and target path are equal.<br />
+
|Copies a file specified by {{Code|$source}} to the file or directory specified by {{Code|$target}}. If the target represents an existing file, it will be overwritten. No operation will be performed if the source and target path are equal.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0001]]</b> is raised if the specified source does not exist.<br /><b>[[#Errors|FOFL0002]]</b> is raised if the specified source is a directory and the target is a file.<br /><b>[[#Errors|FOFL0003]]</b> is raised if the parent of the specified target is no directory.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0001|#Errors}} the specified source does not exist.<br />{{Error|FOFL0002|#Errors}} the specified source is a directory and the target is a file.<br />{{Error|FOFL0003|#Errors}} the parent of the specified target is no directory.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 289: Line 289:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>file:move</b>($source as xs:string, $target as xs:string) as empty-sequence()</code><br />
+
|{{Func|file:move|$source as xs:string, $target as xs:string|empty-sequence()}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Moves or renames the file or directory specified by <code>$source</code> to the path specified by <code>$target</code>. No operation will be performed if the source and target path are equal.<br />
+
|Moves or renames the file or directory specified by {{Code|$source}} to the path specified by {{Code|$target}}. No operation will be performed if the source and target path are equal.<br />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|<b>[[#Errors|FOFL0001]]</b> is raised if the specified source does not exist.<br /><b>[[#Errors|FOFL0002]]</b> is raised if the specified source is a directory and the target is a file.<br /><b>[[#Errors|FOFL0003]]</b> is raised if the parent of the specified target is no directory.<br /><b>[[#Errors|FOFL9999]]</b> is raised if the operation fails for some other reason.<br />
+
|{{Error|FOFL0001|#Errors}} the specified source does not exist.<br />{{Error|FOFL0002|#Errors}} the specified source is a directory and the target is a file.<br />{{Error|FOFL0003|#Errors}} the parent of the specified target is no directory.<br />{{Error|FOFL9999|#Errors}} the operation fails for some other reason.<br />
 
|}
 
|}
  
Line 304: Line 304:
 
! width="95%"|Description
 
! width="95%"|Description
 
|-
 
|-
−
|<code>FOFL0001</code>
+
|{{Code|FOFL0001}}
 
|A specified path does not exist.
 
|A specified path does not exist.
 
|-
 
|-
−
|<code>FOFL0002</code>
+
|{{Code|FOFL0002}}
 
|A file with the same path already exists.
 
|A file with the same path already exists.
 
|-
 
|-
−
|<code>FOFL0003</code>
+
|{{Code|FOFL0003}}
 
|The specified path does not point to a directory.
 
|The specified path does not point to a directory.
 
|-
 
|-
−
|<code>FOFL0004</code>
+
|{{Code|FOFL0004}}
 
|The specified path is a directory.
 
|The specified path is a directory.
 
|-
 
|-
−
|<code>FOFL0005</code>
+
|{{Code|FOFL0005}}
 
|The specified encoding is not supported, or unknown.
 
|The specified encoding is not supported, or unknown.
 
|-
 
|-
−
|<code>FOFL9999</code>
+
|{{Code|FOFL9999}}
 
|The operation fails for some other reason specific to the operating system.
 
|The operation fails for some other reason specific to the operating system.
 
|}
 
|}

Revision as of 15:51, 26 May 2012

This XQuery Module contains functions and variables related to file system operations, such as listing, reading, or writing files. This module has been aligned with the latest EXPath File Module draft from 2011.

Conventions

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

Variables

$file:directory-separator

Signatures $file:directory-separator as xs:string
Summary This variable returns the directory separator used by the operating system, such as "/" or "\".

$file:path-separator

Signatures $file:path-separator as xs:string
Summary This variable returns the path separator used by the operating system, such as ";" or ":".

Functions

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

Signatures file:is-directory($path as xs:string) as xs:boolean
Summary Returns an xs:boolean indicating whether the argument $path points to an existing directory.

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

file:size

Signatures file:size($file as xs:string) as xs:integer
Summary Returns the size, in bytes, of the file specified by $path.
Errors FOFL0001: the specified file does not exist.
FOFL0004: the specified file points to a directory.

file:base-name

Signatures file:base-name($path as xs:string) as xs:string
file:base-name($path as xs:string, $suffix as xs:string) as xs:string
Summary Returns the base-name of the path specified by $path, which is the component after the last directory separator.
If $suffix is specified, it will be trimmed from the end of the result.

file:dir-name

Signatures file:dir-name($path as xs:string) as xs:string
Summary Returns the parent directory of the path specified by $path, which is the component before the last directory separator.

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 FOFL9999: the specified path cannot be transformed to its native representation.

file:resolve-path

Signatures file:resolve-path($path as xs:string) as xs:string
Summary Transforms the $path argument to an absolute operating system path.

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.

file:list

Signatures file:list($directory as xs:string) as xs:string*
file:list($directory as xs:string, $recursive as xs:boolean) as xs:string*
file:list($directory as xs:string, $recursive as xs:boolean, $pattern as xs:string) as xs:string*
Summary Lists all files and directories found in the specified $directory. The returned paths are relative to the provided path.
The optional parameter $recursive specifies whether sub-directories 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 FOFL0003: the specified path does not point to a directory.
FOFL9999: the operation fails for some other reason.

file:create-directory

Signatures file:create-directory($directory as xs:string) as empty-sequence()
Summary Recursively creates the directories specified by $directory.
Errors FOFL0002: a file with the same path already exists.
FOFL9999: the operation fails for some other reason.

file:delete

Template:Mark $recursive parameter added to prevent sub-directories from being accidentally deleted.

Signatures file:delete($path as xs:string) as empty-sequence()
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 sub-directories will be deleted, too.
Errors FOFL0001: the specified path does not exist.
FOFL9999: the operation fails for some other reason.

file:read-text

Signatures file:read-text($path as xs:string) as xs:string
file:read-text($path as xs:string, $encoding as xs:string) as xs:string
Summary Reads the textual contents of the file specified by $path and returns it as a xs:string.
The optional parameter $encoding defines the encoding of the file.
Errors FOFL0001: the specified file does not exist.
FOFL0004: the specified path is a directory.
FOFL0005: the specified encoding is not supported, or unknown.
FOFL9999: the operation fails for some other reason.

file:read-text-lines

Signatures file:read-text-lines($path as xs:string) as xs:string
file:read-text-lines($path as xs:string, $encoding as xs:string) 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 optional parameter $encoding defines the encoding of the file.
Errors FOFL0001: the specified file does not exist.
FOFL0004: the specified path is a directory.
FOFL0005: the specified encoding is not supported, or unknown.
FOFL9999: the operation fails for some other reason.

file:read-binary

Signatures file:read-binary($path as xs:string) as xs:base64Binary
Summary Reads the binary content of the file specified by $path and returns as a xs:base64Binary.
Errors FOFL0001: the specified file does not exist.
FOFL0004: the specified path is a directory.
FOFL9999: the operation fails for some other reason.

file:write

Signatures file:write($path as xs:string, $items as item()*) as empty-sequence()
file:write($path as xs:string, $items as item()*, $params as xs:node()*) as empty-sequence()
Summary Writes a sequence of $items to a file specified by $path. If the specified file already exists, it will be overwritten.
The optional argument $params is used to set the serialization parameters (see Serialization for more details).It can be specified as
  • element(serialization-parameters): <serialization-parameters/> must be used as root element, and the parameters are specified as child nodes, with the element name representing the serialization parameter and the attribute value representing its value:
    {{{1}}}
  • map structure: all parameters can be directly represented as key/value pairs:
    {{{1}}}}
Errors FOFL0004: the specified path is a directory.
FOFL9999: the operation fails for some other reason.

file:write-binary

Signatures file:write-binary($path as xs:string, $items as xs:base64Binary*) as empty-sequence()
Summary Writes a sequence of xs:basex64Binary $items to a file specified by $path. If the specified file already exists, it will be overwritten.
Errors FOFL0004: the specified path is a directory.
FOFL9999: the operation fails for some other reason.

file:append

Signatures file:append($path as xs:string, $items as item()*) as empty-sequence()
file:append($path as xs:string, $items as item()*, $params as xs:node()*) as empty-sequence()
Summary Appends a sequence of $items to a file specified by $path. If the specified file does not exists, a new file is created.
Errors FOFL0004: the specified path is a directory.
FOFL9999: the operation fails for some other reason.

file:append-binary

Signatures file:append-binary($path as xs:string, $items as xs:base64Binary*) as empty-sequence()
Summary Appends a sequence of xs:basex64Binary $items to a file specified by $path. If the specified file does not exists, a new file is created.
Errors FOFL0004: the specified path is a directory.
FOFL9999: 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 specified by $source to the file or directory specified by $target. If the target represents an existing file, it will be overwritten. No operation will be performed if the source and target path are equal.
Errors FOFL0001: the specified source does not exist.
FOFL0002: the specified source is a directory and the target is a file.
FOFL0003: the parent of the specified target is no directory.
FOFL9999: 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. No operation will be performed if the source and target path are equal.
Errors FOFL0001: the specified source does not exist.
FOFL0002: the specified source is a directory and the target is a file.
FOFL0003: the parent of the specified target is no directory.
FOFL9999: the operation fails for some other reason.

Errors

Code Description
FOFL0001 A specified path does not exist.
FOFL0002 A file with the same path already exists.
FOFL0003 The specified path does not point to a directory.
FOFL0004 The specified path is a directory.
FOFL0005 The specified encoding is not supported, or unknown.
FOFL9999 The operation fails for some other reason specific to the operating system.

Changelog

Version 7.2.1

  • Updated: file:delete: $recursive parameter added to prevent sub-directories 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=7254"