File Module

w3c-designation

EXPath Proposed Module

03 December 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 functions and errors in the namespace http://expath.org/ns/file. In this document, the file prefix 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.

File Paths

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 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:parent(static-base-uri()) let $path := concat($dir, $filename) return file:read-text($path) Query Execution

Some function are marked as ·nondeterministic·, which means they are not guaranteed to perform the same operations and produce identical results from repeated calls. 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.

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

File Properties file:exists Signature

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

Rules

Tests if the file or directory pointed by $path exists.

This function is ·nondeterministic·.

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

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 Signature

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

Rules

Tests if $path points to a file.

This function is ·nondeterministic·.

file:last-modified Signature

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

Rules

Returns the last modification time of a file or directory.

This function is ·nondeterministic·.

Error Conditions is raised if $path does not exist. is raised if any other error occurs. file:size Signature

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

Rules

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

This function is ·nondeterministic·.

Error Conditions is raised if $path does not exist. is raised if any other error occurs. Input/Output file:append Signature

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()

Rules

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

Error Conditions 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 Signature

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

Rules

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

Error Conditions 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 Signature

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()

Rules

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

Error Conditions 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 Signature

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()

Rules

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

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

Rules

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, the source directory with all its files will be copied into the target directory. At each level, if a file already exists in the target with the same name as in the source, it is overwritten. If a directory already exists in the target with the same name as in the source, it is not removed, it is recursed in place (if it does not exist, it is created before recursing).

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

Error Conditions 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 Signature

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

Rules

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

Error Conditions 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 Signature

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

Rules

Creates a temporary directory and all non-existing parent directories and returns the full path to the created directory.

The temporary directory will not be automatically deleted after query execution. It is guaranteed to not already exist when the function is called.

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

This function is ·nondeterministic·.

Error Conditions is raised if the specified directory does not exist or points to a file. is raised if any other error occurs. file:create-temp-file Signature

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

Rules

Creates a temporary file and all non-existing parent directories and returns the full path to the created file.

The temporary file will not be automatically deleted after query execution. It is guaranteed to not already exist when the function is called.

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

This function is ·nondeterministic·.

Error Conditions is raised if the specified does not exist or points to a file. is raised if any other error occurs. file:delete Signature

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

Rules

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

Error Conditions 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 Signature

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*

Rules

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

Error Conditions is raised $dir does not point to an existing directory. is raised if any other error occurs. file:move Signature

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

Rules

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, the source directory with all its files will be moved into the target directory. If the target directory contains a directory with the same name as the source, the error is raised.

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

Error Conditions 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 $target points to a directory, in which a subdirectory exists with the name of the source. is raised if any other error occurs. file:read-binary Signature

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

Rules

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

Error Conditions 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 Signature

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

Rules

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

Error Conditions 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 Signature

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*

Rules

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

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()

Rules

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

Error Conditions 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 Signature

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()

Rules

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

Error Conditions 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 Signature

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()

Rules

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

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()

Rules

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

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

file:name Signature

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

Rules

Returns the name of a file or directory.

An empty string is returned if the path points to the root directory, or if it contains no directory separators.

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

file:parent Signature

file:parent($path as xs:string) as xs:string?

Rules

Transforms the given path into an absolute path, as specified by file:resolve-path, and returns the parent directory.

An empty sequence is returned if the path points to a root directory.

This function is ·nondeterministic·.

file:path-to-native Signature

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

Rules

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.

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

This function is ·nondeterministic·.

Error Conditions is raised if an error occurs while trying to obtain the native path. file:path-to-uri Signature

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

Rules

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.

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

file:resolve-path Signature

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

Rules

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

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 Signature

file:dir-separator() as xs:string

Rules

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 Signature

file:line-separator() as xs:string

Rules

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 Signature

file:path-separator() as xs:string

Rules

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 Signature

file:temp-dir() as xs:string

Rules

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.