Difference between revisions of "File Module"
Jump to navigation
Jump to search
m (Text replace - "{| width='100%'" to "{|") |
m (Text replace - "{|" to "{| width='100%'") |
||
Line 9: | Line 9: | ||
==file:list== | ==file:list== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 22: | Line 22: | ||
==file:read-binary== | ==file:read-binary== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 35: | Line 35: | ||
==file:read-text== | ==file:read-text== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 48: | Line 48: | ||
==file:read-text-lines== | ==file:read-text-lines== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 64: | Line 64: | ||
==file:create-dir== | ==file:create-dir== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 77: | Line 77: | ||
==file:delete== | ==file:delete== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 90: | Line 90: | ||
==file:write== | ==file:write== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 116: | Line 116: | ||
==file:write-binary== | ==file:write-binary== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 130: | Line 130: | ||
==file:write-text== | ==file:write-text== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 144: | Line 144: | ||
==file:write-text-lines== | ==file:write-text-lines== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 157: | Line 157: | ||
==file:append== | ==file:append== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 171: | Line 171: | ||
==file:append-binary== | ==file:append-binary== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 185: | Line 185: | ||
==file:append-text== | ==file:append-text== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 199: | Line 199: | ||
==file:append-text-lines== | ==file:append-text-lines== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 213: | Line 213: | ||
==file:copy== | ==file:copy== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 226: | Line 226: | ||
==file:move== | ==file:move== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 241: | Line 241: | ||
==file:exists== | ==file:exists== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 252: | Line 252: | ||
==file:is-dir== | ==file:is-dir== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 262: | Line 262: | ||
==file:is-file== | ==file:is-file== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 272: | Line 272: | ||
==file:last-modified== | ==file:last-modified== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 285: | Line 285: | ||
==file:size== | ==file:size== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 300: | Line 300: | ||
==file:base-name== | ==file:base-name== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 310: | Line 310: | ||
==file:dir-name== | ==file:dir-name== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 320: | Line 320: | ||
==file:path-to-native== | ==file:path-to-native== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 333: | Line 333: | ||
==file:resolve-path== | ==file:resolve-path== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 343: | Line 343: | ||
==file:path-to-uri== | ==file:path-to-uri== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 355: | Line 355: | ||
==file:dir-separator== | ==file:dir-separator== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 365: | Line 365: | ||
==file:path-separator== | ==file:path-separator== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 375: | Line 375: | ||
==file:line-separator== | ==file:line-separator== | ||
− | {| | + | {| width='100%' |
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
Line 386: | Line 386: | ||
=Errors= | =Errors= | ||
− | {| class="wikitable" width="100%" | + | {| width='100%' class="wikitable" width="100%" |
! width="5%"|Code | ! width="5%"|Code | ||
! width="95%"|Description | ! width="95%"|Description |
Revision as of 15:21, 21 December 2012
This XQuery Module contains functions and variables related to file system operations, such as listing, reading, or writing files. This module is based on the EXPath File Module.
Contents
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.
Read Operations
file:list
Signatures | file:list($dir as xs:string) as xs:string* file:list($dir as xs:string, $recursive as xs:boolean) as xs:string* 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 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 | FILE0003 : the specified path does not point to a directory.FILE9999 : 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 it as xs:base64Binary . |
Errors | FILE0001 : the specified file does not exist.FILE0004 : the specified path is a directory.FILE9999 : 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 xs:string .The optional parameter $encoding defines the encoding of the file. |
Errors | FILE0001 : the specified file does not exist.FILE0004 : the specified path is a directory.FILE0005 : the specified encoding is not supported, or unknown.FILE9999 : 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 | FILE0001 : the specified file does not exist.FILE0004 : the specified path is a directory.FILE0005 : the specified encoding is not supported, or unknown.FILE9999 : the operation fails for some other reason. |
Write Operations
file:create-dir
Signatures | file:create-dir($dir as xs:string) as empty-sequence() |
Summary | Recursively creates the directories specified by $dir . |
Errors | FILE0002 : a file with the same path already exists.FILE9999 : the operation fails for some other reason. |
file:delete
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 | FILE0001 : the specified path does not exist.FILE9999 : 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 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 (see Serialization for more details), which can either be specified
<output:serialization-parameters> <output:method value='xml'/> <output:cdata-section-elements value="div"/> ... </serialization-parameters>
map { "method" := "xml", "cdata-section-elements" := "div", ... } |
Errors | FILE0003 : the parent of specified path is no directory.FILE0004 : the specified path is a directory.FILE9999 : the operation fails for some other reason. |
file:write-binary
Signatures | file:write-binary($path as xs:string, $value as basex:binary) 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. |
Errors | FILE0003 : the parent of specified path is no directory.FILE0004 : the specified path is a directory.FILE9999 : the operation fails for some other reason. |
file:write-text
Signatures | file:write-text($path as xs:string, $value as xs:string) as empty-sequence() 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 | FILE0003 : the parent of specified path is no directory.FILE0004 : the specified path is a directory.FILE0005 : the specified encoding is not supported, or unknown.FILE9999 : the operation fails for some other reason. |
file:write-text-lines
Signatures | file:write-text-lines($path as xs:string, $values as xs:string*) as empty-sequence() 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 | FILE0003 : the parent of specified path is no directory.FILE0004 : the specified path is a directory.FILE0005 : the specified encoding is not supported, or unknown.FILE9999 : 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 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 | FILE0003 : the parent of specified path is no directory.FILE0004 : the specified path is a directory.FILE9999 : the operation fails for some other reason. |
file:append-binary
Signatures | file:append-binary($path as xs:string, $value as basex:binary) 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 | FILE0003 : the parent of specified path is no directory.FILE0004 : the specified path is a directory.FILE9999 : the operation fails for some other reason. |
file:append-text
Signatures | file:append-text($path as xs:string, $value as xs:string) as empty-sequence() 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 | FILE0003 : the parent of specified path is no directory.FILE0004 : the specified path is a directory.FILE0005 : the specified encoding is not supported, or unknown.FILE9999 : the operation fails for some other reason. |
file:append-text-lines
Signatures | file:append-text-lines($path as xs:string, $values as xs:string*) as empty-sequence() 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 | FILE0003 : the parent of specified path is no directory.FILE0004 : the specified path is a directory.FILE0005 : the specified encoding is not supported, or unknown.FILE9999 : 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 file already exists, it will be overwritten. No operation will be performed if the source and target path are equal. |
Errors | FILE0001 : the specified source does not exist.FILE0002 : the specified source is a directory and the target is a file.FILE0003 : the parent of the specified target is no directory.FILE9999 : 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 | FILE0001 : the specified source does not exist.FILE0002 : the specified source is a directory and the target is a file.FILE0003 : the parent of the specified target is no directory.FILE9999 : the operation fails for some other reason. |
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-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 | FILE0001 : 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 | FILE0001 : the specified file does not exist.FILE0004 : the specified file points to a directory. |
Path Functions
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 | FILE9999 : 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. |
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 , or . |
Errors
Code | Description |
---|---|
FILE0001
|
A specified path does not exist. |
FILE0002
|
A file with the same path already exists. |
FILE0003
|
The specified path does not point to a directory. |
FILE0004
|
The specified path is a directory. |
FILE0005
|
The specified encoding is not supported, or unknown. |
FILE9999
|
The operation fails for some other reason specific to the operating system. |
Changelog
- Version 7.3
- Added: file:append-text, file:write-text, file:append-text-lines, file:write-text-lines, file:line-separator
- Aligned with latest specification: $file:directory-separator → file:dir-separator, $file:path-separator → file:path-separator, file:is-directory → file:is-dir, file:create-directory → file:create-dir
- Updated: file:write-binary, file:append-binary: output limited to a single value
- 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.