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.
With Template:Mark, all returned strings that refer to existing directories will be suffixed with a directory separator.
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 experr
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 streamable 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.
|
Examples
|
stream:materialize(file:read-binary("config.data")) returns a materialized representation of the streamable result.
|
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 streamable 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. Invalid XML characters will be ignored if the CHECKSTRINGS option is turned off.
|
Examples
|
stream:materialize(file:read-text("config.txt")) returns a materialized representation of the streamable result.
|
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
|
Creates the directory specified by $dir , including all non-existing parent directories.
|
Errors
|
FILE0002 : a file with the same path already exists.
FILE9999 : the operation fails for some other reason.
|
file:create-temp-dir
Template:Mark
Signatures
|
file:create-temp-dir($prefix as xs:string, $suffix as xs:string) as xs:string
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
|
FILE0003 : the specified directory points to a file.
FILE9999 : the directory could not be created.
|
file:create-temp-file
Template:Mark
Signatures
|
file:create-temp-file($prefix as xs:string, $suffix as xs:string) as xs:string
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
|
FILE0003 : the specified directory points to a file.
FILE9999 : the directory could not be created.
|
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
- as children of an
<output:serialization-parameters/> element, as defined for the fn:serialize() function; e.g.:
<output:serialization-parameters>
<output:method value='xml'/>
<output:cdata-section-elements value="div"/>
...
</output:serialization-parameters>
- as map, which contains all key/value pairs:
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 .
|
file:temp-dir
Template:Mark
Signatures
|
file:temp-dir() as xs:string
|
Summary
|
Returns the system’s default temporary-file directory.
|
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.7
- Version 7.3
- 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.