http://expath.org/ns/file

import module namespace file = "http://expath.org/ns/file";

This module implements the file API EXPath specification available at http://expath.org/spec/file

Gabriel Petrovay, Matthias Brantner, Markus Pilman

xquery version "3.0" encoding "utf-8";

• the XQuery module can be found here.

Imported schemas:

• http://www.w3.org/2010/xslt-xquery-serialization

For more details please also see:

• http://expath.org/spec/file

	append ( $file as xs:string, $content as item()*, $serializer-params as element(output:serialization-parameters)? ) as empty-sequence() Appends a sequence of items to a file.
	append-binary ( $file as xs:string, $content as xs:base64Binary* ) as empty-sequence() external Appends a sequence of Base64 items as binary to a file.
	base-name ( $path as xs:string ) as xs:string Returns the last component from the $path, deleting any trailing directory-separator characters.
	base-name ( $path as xs:string, $suffix as xs:string ) as xs:string Returns the last component from the $path, deleting any trailing directory-separator characters and the $suffix.
	copy ( $source as xs:string, $destination as xs:string ) as empty-sequence() Copies a file or a directory given a source and a destination path/URI.
	create-directory ( $dir as xs:string ) as empty-sequence() external Creates a directory.
	delete ( $path as xs:string ) as empty-sequence() Deletes a file or a directory from the file system.
	dir-name ( $path as xs:string ) as xs:string This function is the converse of file:base-name.
	directory-separator ( ) as xs:string external This function returns the value of the operating system specific directory separator.
	exists ( $path as xs:string ) as xs:boolean external Tests if a path/URI is already used in the file system.
	glob-to-regex ( $pattern as xs:string) ) A helper function that performs a trivial (not complete) glob to regex pattern translation.
	is-directory ( $dir as xs:string ) as xs:boolean external Tests if a path/URI points to a directory.
	is-file ( $file as xs:string ) as xs:boolean external Tests if a path/URI points to a file.
	last-modified ( $path as xs:string ) as xs:dateTime external Retrieves the timestamp of the last modification of the file system item pointed by the path/URI.
	list ( $dir as xs:string ) as xs:string* external Lists the file system items in a certain directory.
	list ( $path as xs:string, $recursive as xs:boolean ) as xs:string* Lists the file system items in a certain directory.
	list ( $path as xs:string, $recursive as xs:boolean, $pattern as xs:string ) as xs:string* Lists all files matching the given pattern in a given directory.
	move ( $source as xs:string, $destination as xs:string ) as empty-sequence() Moves a file or directory given a source and a destination paths/URIs.
	path-separator ( ) as xs:string external This function returns the value of the operating system specific path separator.
	path-to-native ( $path as xs:string ) as xs:string external Transforms a URI, an absolute path, or relative path to a native path on the running platform.
	path-to-uri ( $path as xs:string ) as xs:anyURI external Transforms a file system path into a URI with the file:// scheme.
	read-binary ( $file as xs:string ) as xs:base64Binary external Reads the content of a file and returns a Base64 representation of the content.
	read-text ( $file as xs:string ) as xs:string Reads the content of a file and returns a string representation of the content.
	read-text ( $file as xs:string, $encoding as xs:string ) as xs:string external Reads the content of a file using the specified encoding and returns a string representation of the content.
	read-text-lines ( $file as xs:string ) as xs:string* Reads the content of a file and returns a sequence of strings representing the lines in the content of the file.
	read-text-lines ( $file as xs:string, $encoding as xs:string ) as xs:string* Reads the content of a file using the specified encoding and returns a sequence of strings representing the lines in the content of the file.
	resolve-path ( $path as xs:string ) as xs:string external Transforms a relative path/URI into an absolute operating system path by resolving it against the current working directory.
	size ( $file as xs:string ) as xs:integer external Retrieves the size of a file.
	write ( $file as xs:string, $content as item()*, $serializer-params as element(output:serialization-parameters)? ) as empty-sequence() Writes a sequence of items to a file.
	write-binary ( $file as xs:string, $content as xs:base64Binary* ) as empty-sequence() external Writes a sequence of Base64 items as binary to a file.
	write-binary ( $file as xs:string, $content as xs:base64Binary* ) as empty-sequence() external Writes a sequence of Base64 items as binary to a file.

append

declare %ann:sequential function file:append (
            $file as xs:string, 
            $content as item()*, 
            $serializer-params as element(output:serialization-parameters)? 
 ) as empty-sequence()

Appends a sequence of items to a file. If the file pointed by

$file

$serializer-params

$serializer-params

$params

• $file The path/URI of the file to write the content to.
• $content The content to be serialized to the file.
• $serializer-params Parameter to control the serialization of the content.

• The empty sequence.

• file:FOFL0004 If $file points to a directory.
• file:FOFL9999 If any other error occurs.

append-binary

declare %ann:sequential function file:append-binary (
            $file as xs:string, 
            $content as xs:base64Binary* 
 ) as empty-sequence() external

Appends a sequence of Base64 items as binary to a file. If the file pointed by

$file

• $file The path/URI of the file to write the content to.
• $content The content to be serialized to the file.

• The empty sequence.

• file:FOFL0004 If $file points to a directory.
• file:FOFL9999 If any other error occurs.

base-name

declare function file:base-name (
            $path as xs:string 
 ) as xs:string

Returns the last component from the

$path

$path

$path

"."

• $path A file path/URI.

• The base name of this file.

base-name

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

Returns the last component from the

$path

$suffix

"."

$suffix

• $path A file path/URI.
• $suffix A suffix which should get deleted from the result.

• The base-name of $path with a deleted $suffix.

copy

declare %ann:nondeterministic %ann:sequential function file:copy (
            $source as xs:string, 
            $destination as xs:string 
 ) as empty-sequence()

Copies a file or a directory given a source and a destination path/URI.

• $source The path/URI of the file or directory to copy.
• $destination The destination path/URI.

• The empty sequence.

• file:FOFL0001 If the $source path does not exist.
• file:FOFL0002 If the computed destination points to a file system item with a different type than the $source.
• file:FOFL0003 If $destination does not exist and it's parent directory does not exist either.
• file:FOFL9999 If any other error occurs.

create-directory

declare %ann:sequential function file:create-directory (
            $dir as xs:string 
 ) as empty-sequence() external

Creates a directory. The operation is will create all the missing parent directories from the given path.

• $dir The path/URI denoting the directory to be created.

• The empty sequence.

• file:FOFL0002 If the directory cannot be created because of an already existing file.
• file:FOFL9999 If any other error occurs.

delete

declare %ann:nondeterministic %ann:sequential function file:delete (
            $path as xs:string 
 ) as empty-sequence()

Deletes a file or a directory from the file system. If

$path

• $path The path/URI of the file or directory to delete.

• The empty sequence.

• file:FOFL0001 If the $path path does not exist.
• file:FOFL9999 If any other error occurs.

dir-name

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

This function is the converse of

file:base-name

$path

"."

• $path The filename, of which the dirname should be get.

• The name of the directory the file is in.

directory-separator

declare function file:directory-separator (
 ) as xs:string external

This function returns the value of the operating system specific directory separator. For example,

/

\

• The operating system specific directory separator.

exists

declare %ann:nondeterministic function file:exists (
            $path as xs:string 
 ) as xs:boolean external

Tests if a path/URI is already used in the file system.

• $path The path/URI to test for existence.

• true if the path/URI points to an existing file system item.

glob-to-regex

declare function file:glob-to-regex (
            $pattern as xs:string) 
 )

A helper function that performs a trivial (not complete) glob to regex pattern translation.

• $pattern The glob pattern.

• A regex pattern corresponding to the glob pattern provided.

is-directory

declare %ann:nondeterministic function file:is-directory (
            $dir as xs:string 
 ) as xs:boolean external

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

• $dir The path/URI to test.

• true if the path/URI points to a directory.

is-file

declare %ann:nondeterministic function file:is-file (
            $file as xs:string 
 ) as xs:boolean external

Tests if a path/URI points to a file.

• $dir The path/URI to test.

• true if the path/URI points to a file.

last-modified

declare %ann:nondeterministic function file:last-modified (
            $path as xs:string 
 ) as xs:dateTime external

Retrieves the timestamp of the last modification of the file system item pointed by the path/URI.

• $path The file system item to read the last modification timestamp from.

• The date and time of the last modification of the item.

• file:FOFL0001 If the $path does not exist.
• file:FOFL9999 If any other error occurs.

list

declare %ann:nondeterministic function file:list (
            $dir as xs:string 
 ) as xs:string* external

Lists the file system items in a certain directory. The operation is equivalent to calling:

file:list($dir, fn:false())

• $dir The path/URI of the directory to retrieve the children from.

• The sequence of names of the direct children.

• file:FOFL0003 If $dir does not point to an existing directory.
• file:FOFL9999 If any other error occurs.

list

declare %ann:nondeterministic function file:list (
            $path as xs:string, 
            $recursive as xs:boolean 
 ) as xs:string*

Lists the file system items in a certain directory. The order of the items in the resulting sequence is not defined. The "." and ".." items are not returned. The returned paths are relative to the provided

$path

$recursive

fn:true()

• $dir The path/URI to retrieve the children from.
• $recursive A boolean flag indicating whether the operation should be performed recursively.

• A sequence of relative paths.

• file:FOFL0003 If $dir does not point to an existing directory.
• file:FOFL9999 If any other error occurs.

list

declare %ann:nondeterministic function file:list (
            $path as xs:string, 
            $recursive as xs:boolean, 
            $pattern as xs:string 
 ) as xs:string*

Lists all files matching the given pattern in a given directory. The order of the items in the result is not defined. The "." and ".." items are not considered for the match. The file paths are relative to the provided $path. The pattern is a glob expression supporting:

• *

  for matching any number of unknown characters

• ?

  for matching one unknown character

• $path The path/URI to retrieve the children from.
• $recursive A boolean flag indicating whether the operation should be performed recursively.
• $pattern The file name pattern.

• A sequence of file names matching the pattern.

• file:FOFL0003 If $dir does not point to an existing directory.
• file:FOFL9999 If any other error occurs.

move

declare %ann:sequential function file:move (
            $source as xs:string, 
            $destination as xs:string 
 ) as empty-sequence()

Moves a file or directory given a source and a destination paths/URIs.

• $source The path/URI of the file to move.
• $destination The destination path/URI.

• The empty sequence.

• file:FOFL0001 If the $source path does not exist.
• file:FOFL0002 If $source points to a directory and $destination points to an existing file.
• file:FOFL0003 If $destination does not exist and it's parent directory does not exist either.
• file:FOFL9999 If any other error occurs.

path-separator

declare function file:path-separator (
 ) as xs:string external

This function returns the value of the operating system specific path separator. For example,

:

;

• The operating system specific path separator.

path-to-native

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

Transforms a URI, an absolute path, or relative path to a native path on the running platform. No path existence check is made.

• $path The uri or path to normalize.

• The native path corresponding to

  $path

  .

• file:FOFL9999 If an error occurs while trying to obtain the native path.

path-to-uri

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

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.

• $path The path to transform.

• The file URI corresponding to

  path

  .

read-binary

declare %ann:nondeterministic function file:read-binary (
            $file as xs:string 
 ) as xs:base64Binary external

Reads the content of a file and returns a Base64 representation of the content.

• $file The file to read.

• The content of the file as Base64.

• file:FOFL0001 If the $source path does not exist.
• file:FOFL0004 If $source points to a directory.
• file:FOFL9999 If any other error occurs.

read-text

declare %ann:nondeterministic function file:read-text (
            $file as xs:string 
 ) as xs:string

Reads the content of a file and returns a string representation of the content. The operation is equivalent to calling:

file:read-text($file, "UTF-8")

• $file The file to read.

• The content of the file as string.

• file:FOFL0001 If the $source path does not exist.
• file:FOFL0004 If $source points to a directory.
• file:FOFL9999 If any other error occurs.

read-text

declare %ann:nondeterministic function file:read-text (
            $file as xs:string, 
            $encoding as xs:string 
 ) as xs:string external

Reads the content of a file using the specified encoding and returns a string representation of the content. In Zorba only the following encodings are currently supported: "UTF-8", "UTF8". The encoding parameter is case insensitive.

• $file The file to read.
• $encoding The encoding used when reading the file.

• The content of the file as string.

• file:FOFL0001 If the $source path does not exist.
• file:FOFL0004 If $source points to a directory.
• file:FOFL0006 If $encoding is not supported.
• file:FOFL9999 If any other error occurs.

read-text-lines

declare %ann:nondeterministic function file:read-text-lines (
            $file as xs:string 
 ) as xs:string*

Reads the content of a file and returns a sequence of strings representing the lines in the content of the file. The operation is equivalent to calling:

file:read-text-lines($file, "UTF-8")

• $file The file to read.

• The content of the file as a sequence of strings.

• file:FOFL0001 If the $source path does not exist.
• file:FOFL0004 If $source points to a directory.
• file:FOFL9999 If any other error occurs.

read-text-lines

declare %ann:nondeterministic function file:read-text-lines (
            $file as xs:string, 
            $encoding as xs:string 
 ) as xs:string*

Reads the content of a file using the specified encoding and returns a sequence of strings representing the lines in the content of the file. This implementation considers the LF ( ) character as the line separator. If a resulting line ends with the CR ( ) character, this is trimmed as well. This implementation will uniformly treat LF and CRLF as line separators. In Zorba only the following encodings are currently supported: "UTF-8", "UTF8". The encoding parameter is case insensitive.

• $file The file to read.
• $encoding The encoding used when reading the file.

• The content of the file as a sequence of strings.

• file:FOFL0001 If the $source path does not exist.
• file:FOFL0004 If $source points to a directory.
• file:FOFL0006 If $encoding is not supported.
• file:FOFL9999 If any other error occurs.

resolve-path

declare function file:resolve-path (
            $path as xs:string 
 ) as xs:string external

Transforms a relative path/URI into an absolute operating system path by resolving it against the current working directory. No path existence check is made.

• $path The path/URI to transform.

• The operating system file path.

size

declare %ann:nondeterministic function file:size (
            $file as xs:string 
 ) as xs:integer external

Retrieves the size of a file.

• $file The file get the size.

• An integer representing the size in bytes of the file.

• file:FOFL0001 If the $file does not exist.
• file:FOFL0004 If the $file points to a directory.
• file:FOFL9999 If any other error occurs.

write

declare %ann:sequential function file:write (
            $file as xs:string, 
            $content as item()*, 
            $serializer-params as element(output:serialization-parameters)? 
 ) as empty-sequence()

Writes a sequence of items to a file. Before writing to the file, the items are serialized according to the

$serializer-params

$serializer-params

$params

• $file The path/URI of the file to write the content to.
• $content The content to be serialized to the file.
• $serializer-params Parameter to control the serialization of the content.

• The empty sequence.

• file:FOFL0004 If $file points to a directory.
• file:FOFL9999 If any other error occurs.

write-binary

declare %ann:sequential function file:write-binary (
            $file as xs:string, 
            $content as xs:base64Binary* 
 ) as empty-sequence() external

Writes a sequence of Base64 items as binary to a file.

• $file The path/URI of the file to write the content to.
• $content The content to be serialized to the file.

• The empty sequence.

• file:FOFL0004 If $file points to a directory.
• file:FOFL9999 If any other error occurs.

write-binary

declare %ann:sequential function file:write-binary (
            $file as xs:string, 
            $content as xs:base64Binary* 
 ) as empty-sequence() external

Writes a sequence of Base64 items as binary to a file. The operation is equivalent to calling:

file:write-binary($file, $content, fn:true())

• $file The path/URI of the file to write the content to.
• $content The content to be serialized to the file.

• The empty sequence.

• file:FOFL0004 If $file points to a directory.
• file:FOFL9999 If any other error occurs.