File Module

w3c-designation

EXPath Proposed Module

29 November 2013 XML Revision markup Christian Grün BaseX GmbH Matthias Brantner 28msec GmbH Gabriel Petrovay 28msec GmbH

This specification was published by the EXPath Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply.s Learn more about W3C Community and Business Groups.

This proposal provides a file system API for XPath. It defines extension functions to perform file system related operations such as listing, reading, or writing files or directories. It has been designed to be compatible with XQuery 1.0 and XSLT 2.0, as well as any other XPath 2.0 usage.

en-US

revisiondesc

Status of this document

This document is in a final draft stage. Comments are welcomed at public-expath@w3.org mailing list (archive).

Introduction Namespace conventions

The module defined by this document defines the functions and variables in the namespace http://expath.org/ns/file. In this document, the file prefix, when used, is bound to this namespace URI.

The output prefix is bound to the namespace http://www.w3.org/2010/xslt-xquery-serialization. It is used to specify serialization parameters.

Error codes are defined in the namespace http://expath.org/ns/error. In this document, the The err prefix, when used, is bound to this namespace URI.

File Paths vs. URIs

All file paths are specified as strings, and are resolved against the current working directory. An implementation must accept absolute and relative UNIX/Linux and Windows paths as well as absolute file URIs. Some examples:

C:\Test Dir\my file.xml: An absolute path on Windows platforms.

/Test Dir/my file.xml: An absolute path on UNIX-based platforms.

C:\\\Test Dir//\\my file.xml: An absolute path on Windows platforms that tolerates an arbitrary number of slashes and backslashes.

my file.xml: A relative path, pointing to a file in the current working directory.

file:///C:/Test%20Dir/my%20file.xml: An absolute file URI on Windows platforms.

file:///Test%20Dir/my%20file.xml: An absolute path on UNIX-based platforms.

Before further processing, all paths must first be are normalized to an implementation-defined representation (which usually is the representation of the underlying operating system).

If a function returns a string that refers to a directory, it will always be suffixed with the system-specific directory separator.

The standard function fn:static-base-uri can be used to resolve file operations against the base URI:

let $filename := "input.txt"
let $dir := file:dir-name(static-base-uri())
let $path := concat($dir, $filename)
return file:read-text($path)

Query Execution

Functions on File Properties (Section 2) and Input/Output (Section 3) are Some function are marked as ·nondeterministic·, which means they are not guaranteed to perform the same operations and produce identical results from repeated calls. As such, a A query processor must ensure that these functions are not relocated or pre-evaluated and that its results are not cached when compiling and evaluating the query and serializing its results.

Error Management

Error conditions are identified by a code (a QName). When such an error condition is reached during the execution of the function, a dynamic error is thrown, with the corresponding error code (as if the standard XPath function fn:error had been called).

Error codes are defined through the specification. The generic error with an appropriate message is raised for I/O faults, or for specific errors caused by the underlying platform or programming language. If file operations raise additional, errors, which may be specific to the underlying platform or programming language, the generic error with an appropriate message is raised.

For a list of specific errors see the "Summary of Error Conditions" section of this document.

File Properties file:exists file:exists($path as xs:string) as xs:boolean

Tests if a path/URI is already used in the file system. the file or directory pointed by $path exists.

The function returns true() if a file or a directory exists at the location pointed by $path.

This function is ·nondeterministic·.

file:is-dir file:is-dir($path as xs:string) as xs:boolean

Tests if $path points to a directory. On UNIX-based systems the root and the volume roots are considered directories.

This function is ·nondeterministic·.

file:is-file file:is-file($path as xs:string) as xs:boolean

Tests if $path points to a file.

This function is ·nondeterministic·.

file:last-modified file:last-modified($path as xs:string) as xs:dateTime

Returns xs:dateTime representing the last modification time of a file or directory.

This function is ·nondeterministic·.

is raised if $path does not exist.

is raised if any other error occurs.

file:size file:size($file as xs:string) as xs:integer

Returns the byte size of a file as integer, or the value 0 for directories.

This function is ·nondeterministic·.

is raised if $path does not exist.

is raised if $path points to a directory.

is raised if any other error occurs.

Input/Output file:append file:append($file as xs:string, $items as item()*) as empty-sequence() file:append($file as xs:string, $items as item()*, $params as element(output:serialization-parameters)) as empty-sequence()

Appends a sequence of items to a file. If the file pointed by $file does not exist, a new file will be created.

$params controls the way the $items items are serialized. The semantics of $params is the same as for the fn:serialize function in . This consists of an output:serialization-parameters element whose format is defined in . In contrast to fn:serialize,, the encoding stage will not be skipped by this function.

The function returns the empty sequence if the operation is successful.

This function is ·nondeterministic·.

is raised if the parent directory of $file does not exist.

is raised if $file points to a directory.

is raised if any other error occurs.

file:append-binary file:append-binary($file as xs:string, $value as xs:base64Binary) as empty-sequence()

Appends a Base64 item as binary to a file. If the file pointed by $file does not exist, a new file will be created.

The function returns the empty sequence if the operation is successful.

This function is ·nondeterministic·.

is raised if the parent directory of $file does not exist.

is raised if $file points to a directory.

is raised if any other error occurs.

file:append-text file:append-text($file as xs:string, $value as xs:string) as empty-sequence() file:append-text($file as xs:string, $value as xs:string, $encoding as xs:string) as empty-sequence()

Appends a string to a file. If the file pointed by $file does not exist, a new file will be created.

The optional parameter $encoding, if not provided, is considered to be UTF-8.

The function returns the empty sequence if the operation is successful.

This function is ·nondeterministic·.

is raised if the parent directory of $file does not exist.

is raised if $file points to a directory.

is raised if $encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

file:append-text-lines file:append-text-lines($file as xs:string, $values as xs:string*) as empty-sequence() file:append-text-lines($file as xs:string, $lines as xs:string*, $encoding as xs:string) as empty-sequence()

Appends a sequence of strings to a file, each followed by the system-dependent newline character. If the file pointed by $file does not exist, a new file will be created.

The optional parameter $encoding, if not provided, is considered to be UTF-8.

The function returns the empty sequence if the operation is successful.

This function is ·nondeterministic·.

is raised if the parent directory of $file does not exist.

is raised if $file points to a directory.

is raised if $encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

file:copy file:copy($source as xs:string, $target as xs:string) as empty-sequence()

Copies a file or a directory given a source and a target path/URI. The following cases may occur if $source points to a file:

if $target does not exist, it will be created.
if $target is a file, it will be overwritten.
if $target is a directory, the file will be created in that directory with the name of the source file. If a file already exists, it will be overwritten.

The following cases may occur if $source points to a directory:

if $target does not exist, it will be created as directory, and all files of the source directory are copied to this directory with their existing local names.
if $target is a directory, all files are copied from the source the source directory with all its files will be copied into the target directory. If a file already exists, it will be overwritten.

Other cases will raise one of the errors listed below.

The function returns the empty sequence if the operation is successful. If an error occurs during the operation, no rollback to the original state will be possible

This function is ·nondeterministic·.

is raised if the $source path does not exist.

is raised if $source points to a directory and $target points to an existing file.

is raised if the parent directory of $source does not exist.

is raised if $source points to a file and $target points to a directory, in which a subdirectory exists with the name of the source file.

is raised if any other error occurs.

file:create-dir file:create-dir($dir as xs:string) as empty-sequence()

Creates a directory, or does nothing if the directory already exists. The operation will create all non-existing parent directories.

The function returns the empty sequence if the operation is successful.

This function is ·nondeterministic·.

is raised if the specified path, or any of its parent directories, points to an existing file.

is raised if any other error occurs.

file:create-temp-dir 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

Creates a temporary directory and all non-existing parent directories. The temporary directory is guaranteed to not already exist when the function is called. It will not be automatically deleted after query execution.

If $dir is not given, the directory will be created inside the system-dependent default temporary-file directory.

The function returns the full path to the created directory.

This function is ·nondeterministic·.

is raised if the specified directory does not exist.

is raised if any other error occurs.

file:create-temp-file 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

Creates a temporary file and all non-existing parent directories. The temporary file is guaranteed to not already exist when the function is called. It will not be automatically deleted after query execution.

If $dir is not given, the directory will be created inside the system-dependent default temporary-file directory.

The function returns the full path to the created file.

This function is ·nondeterministic·.

is raised if the specified directory does not exist.

is raised if any other error occurs.

file:delete file:delete($path as xs:string) as empty-sequence() file:delete($path as xs:string, $recursive as xs:boolean) as empty-sequence()

Deletes a file or a directory from the file system.

If the optional parameter $recursive is set to true(), sub-directories will be deleted as well.

The function returns the empty sequence if the operation is successful.

This function is ·nondeterministic·.

is raised if $path does not exist.

is raised if $file points to a non-empty directory.

is raised if any other error occurs.

file:list 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*

Lists all files and directories in a given directory. The order of the items in the resulting sequence is not defined. The "." and ".." items are never returned. The returned paths are relative to the provided directory $dir.

If the optional parameter $recursive is set to true(), all directories and files will be returned that are found while recursively traversing the given directory.

The optional $pattern parameter defines a name pattern in the glob syntax. If this is provided, only the paths of the files and directories whose names are matching the pattern will be returned.

An implementation must support at least the following glob syntax for the pattern:

* for matching any number of unknown characters and
? for matching one unknown character.

This function is ·nondeterministic·.

is raised $dir does not point to an existing directory.

is raised if any other error occurs.

file:move file:move($source as xs:string, $target as xs:string) as empty-sequence()

Moves a file or a directory given a source and a target path/URI. The following cases may occur if $source points to a file:

if $target does not exist, it will be created.
if $target is a file, it will be overwritten.
if $target is a directory, the file will be created in that directory with the name of the source file. If a file already exists, it will be overwritten.

The following cases may occur if $source points to a directory:

if $target does not exist, it will be created as directory, and all files of the source directory are moved to this directory with their existing local names.
if $target is a directory, all files are moved from the source the source directory with all its files will be moved into the target directory. If a file already exists, it will be overwritten.

Other cases will raise one of the errors listed below.

The function returns the empty sequence if the operation is successful. If an error occurs during the operation, no rollback to the original state will be possible

This function is ·nondeterministic·.

is raised if the $source path does not exist.

is raised if $source points to a directory and $target points to an existing file.

is raised if the parent directory of $source does not exist.

is raised if $source points to a file and $target points to a directory, in which a subdirectory exists with the name of the source file.

is raised if any other error occurs.

file:read-binary file:read-binary($file as xs:string) as xs:base64Binary file:read-binary($file as xs:string, $offset as xs:integer) as xs:base64Binary file:read-binary($file as xs:string, $offset as xs:integer, $length as xs:integer) as xs:base64Binary

Returns the content of a file in its Base64 representation.

The optional parameters $offset and $length can be used to read chunks of a file.

This function is ·nondeterministic·.

is raised if $file does not exist.

is raised if $file points to a directory.

is raised if $offset or $length is negative, or if the chosen values would exceed the file bounds.

is raised if any other error occurs.

file:read-text file:read-text($file as xs:string) as xs:string file:read-text($file as xs:string, $encoding as xs:string) as xs:string

Returns the content of a file in its string representation.

The optional parameter $encoding, if not provided, is considered to be UTF-8.

This function is ·nondeterministic·.

is raised if $file does not exist.

is raised if $file points to a directory.

is raised if $encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

file:read-text-lines file:read-text-lines($file as xs:string) as xs:string* file:read-text-lines($file as xs:string, $encoding as xs:string) as xs:string*

Returns the contents of a file as a sequence of strings, separated at newline boundaries.

The optional parameter $encoding, if not provided, is considered to be UTF-8.

The newline handling is the same as for the fn:unparsed-text-lines function in .

This function is ·nondeterministic·.

is raised if $file does not exist.

is raised if $file points to a directory.

is raised if $encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

file:write file:write($file as xs:string, $items as item()*) as empty-sequence() file:write($file as xs:string, $items as item()*, $params as element(output:serialization-parameters)) as empty-sequence()

Writes a sequence of items to a file. If $file already exists, it will be overwritten; otherwise, it will be created.

$params controls the way the $items items are serialized. The semantics of $params is the same as for the fn:serialize function in . This consists of an output:serialization-parameters element whose format is defined in . In contrast to fn:serialize, the encoding stage will not be skipped by this function.

The function returns the empty sequence if the operation is successful.

This function is ·nondeterministic·.

is raised if the parent directory of $file does not exist.

is raised if $file points to a directory.

is raised if any other error occurs.

file:write-binary file:write-binary($file as xs:string, $value as xs:base64Binary) as empty-sequence() file:write-binary($file as xs:string, $value as xs:base64Binary, $offset as xs:integer) as empty-sequence()

Writes a Base64 item as binary to a file. If $file already exists, it will be overwritten; otherwise, it will be created.

If the optional parameter $offset is specified, data will be written to this file position. An existing file may be resized by that operation.

The function returns the empty sequence if the operation is successful.

This function is ·nondeterministic·.

is raised if the parent directory of $file does not exist.

is raised if $file points to a directory.

is raised if $offset is negative, or if it exceeds the current file size.

is raised if any other error occurs.

file:write-text file:write-text($file as xs:string, $value as xs:string) as empty-sequence() file:write-text($file as xs:string, $value as xs:string, $encoding as xs:string) as empty-sequence()

Writes a strings to a file. If $file already exists, it will be overwritten.

The optional parameter $encoding, if not provided, is considered to be UTF-8.

The function returns the empty sequence if the operation is successful.

This function is ·nondeterministic·.

is raised if the parent directory of $file does not exist.

is raised if $file points to a directory.

is raised if $encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

file:write-text-lines file:write-text-lines($file as xs:string, $values as xs:string*) as empty-sequence() file:write-text-lines($file as xs:string, $values as xs:string*, $encoding as xs:string) as empty-sequence()

Writes a sequence of strings to a file, each followed by the system-dependent newline character. If $file already exists, it will be overwritten; otherwise, it will be created.

The optional parameter $encoding, if not provided, is considered to be UTF-8.

The function returns the empty sequence if the operation is successful.

This function is ·nondeterministic·.

is raised if the parent directory of $file does not exist.

is raised if $file points to a directory.

is raised if $encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

Paths

None of the functions in this section performs any check regarding the existence of the received or returned paths.

file:base-name file:base-name($path as xs:string) as xs:string file:base-name($path as xs:string, $suffix as xs:string) as xs:string

Returns the last component from $path, deleting any trailing directory separators. If $path consists entirely of directory separator, the empty string is returned. If $path is the empty string, the string "." is returned, signifying the current working directory.

If $suffix is present, it will be trimmed from the end of the result. This can be used to eliminate file extensions.

No path existence check is made.

This function is ·deterministic· (no path existence check is made).

file:dir-name file:dir-name($path as xs:string) as xs:string

This function returns a string denoting the parent directory of $path. Any trailing directory separators are not counted as part of the directory name. If the specified string is empty or contains no directory separators, "." is returned, signifying the current directory. If the specified string is empty or contains no directory separators, it is replaced with a single dot (.), signifying the current directory. If the resulting string does not end with a directory separator, it will be suffixed with the system-dependent directory separator.

No path existence check is made.

This function is ·deterministic· (no path existence check is made).

file:path-to-native file:path-to-native($path as xs:string) as xs:string

Transforms a URI, an absolute path, or relative path to a canonical, system-dependent path representation. A canonical path is both absolute and unique and thus contains no redirections such as references to parent directories or symbolic links.

No path existence check is made.

If the resulting path points to a directory, it will be suffixed with the system-specific directory separator.

This function is ·nondeterministic·.

is raised if an error occurs while trying to obtain the native path.

file:path-to-uri file:path-to-uri($path as xs:string) as xs:anyURI

Transforms a file system path into a URI with the file:// scheme. If the path is relative, it is first resolved against the current working directory.

No path existence check is made.

This function is ·deterministic· (no path existence check is made).

file:resolve-path file:resolve-path($path as xs:string) as xs:string

Transforms a relative path into an absolute operating system path by resolving it against the current working directory.

No path existence check is made.

If the resulting path points to a directory, it will be suffixed with the system-specific directory separator.

This function is ·nondeterministic·.

System Properties file:dir-separator file:dir-separator() as xs:string

Returns the value of the operating system-specific directory separator, which usually is / on UNIX-based systems and \ on Windows systems.

This function is ·nondeterministic·.

file:line-separator file:line-separator() as xs:string

Returns the value of the operating system-specific line separator, which usually is 
 on UNIX-based systems, 
 on Windows systems and  on Mac systems.

This function is ·nondeterministic·.

file:path-separator file:path-separator() as xs:string

Returns the value of the operating system-specific path separator, which usually is : on UNIX-based systems and ; on Windows systems.

This function is ·nondeterministic·.

file:temp-dir file:temp-dir() as xs:string

Returns the path to the default temporary-file directory of an operating system.

This function is ·nondeterministic·.

References XSLT and XQuery Serialization 3.0. Henry Zongaro. W3C Working Draft 14 December 2010. XPath and XQuery Functions and Operators 3.0. Michael Kay. W3C Working Draft 14 December 2010. Summary of Error Conditions The specified path does not exist. The specified path already exists. The specified path does not point to a directory. The specified path points to a directory. The specified encoding is not supported. The specified offset or length is negative, or the chosen values would exceed the file bounds. A generic file system error occurred.