const type: file

Interface type for sequential files. The file interface is implemented with null_file, external_file, utf8File, utf16File, socket, echoFile, lineFile, dirFile and many other types.

const proc: write (inout file: outFile, in string: stri)

Write a string to a file.

Raises:

RANGE_ERROR - - The string contains a character that does not fit into the file specific representation (e.g.: A byte-file allows just chars from '\0;' to '\255;').

const proc: writeln (inout file: outFile)

Write end-of-line to a file. The implementation function decides how writing end-of-line is done. It can be done by writing '\n', but other solutions are also possible.

const proc: writeln (inout file: outFile, in string: stri)

Write a string followed by end-of-line to a file. The implementation function decides how writing end-of-line is done. It can be done by writing '\n', but other solutions are also possible.

Raises:

RANGE_ERROR - - The string contains a character that does not fit into the file specific representation (e.g.: A byte-file allows just chars from '\0;' to '\255;').

const proc: close (inout file: aFile)

Close a file.

const proc: flush (inout file: outFile)

Forces that all buffered data of outFile is sent to its destination. Depending on the implementation type this causes data to be sent to the file system, screen, network or other destination.

const func char: getc (inout file: inFile)

Read a character from a file.

Returns:

the character read, or EOF at the end of the file.

const func string: gets (inout file: inFile, in integer: maxLength)

Read a string with a maximum length from a file.

Returns:

the string read.

Raises:

RANGE_ERROR - The parameter maxLength is negative.

const func string: getTerminatedString (inout file: inFile, in char: terminator)

Read a string from inFile until the terminator character is found. If a terminator is found the string before the terminator is returned and the terminator character is assigned to inFile.bufferChar. The file position is advanced after the terminator character. If no terminator is found the rest of inFile is returned and EOF is assigned to the inFile.bufferChar. When the function is left inFile.bufferChar contains either terminator or EOF.

Parameters:

inFile - File from which the string is read.

terminator - Character which terminates the string.

Returns:

the string read without the terminator or the rest of the file if no terminator is found.

const func string: getwd (inout file: inFile)

Read a word from a file. Before reading the word it skips spaces and tabs. The function accepts words ending with " ", "\t", end-of-line or EOF. The word ending characters are not copied into the string. When the function is left inFile.bufferChar contains the word ending character (' ', '\t', '\n' or EOF).

Returns:

the word read.

const func string: getln (inout file: inFile)

Read a line from a file. The function reads a string up to end-of-line or EOF. The line ending characters are not copied into the string. When the function is left inFile.bufferChar contains the line ending character ('\n' or EOF).

Returns:

the line read.

const func boolean: eof (in file: inFile)

Determine the end-of-file indicator. The end-of-file indicator is set if at least one request to read from the file failed.

Returns:

TRUE if the end-of-file indicator is set, FALSE otherwise.

const func boolean: hasNext (inout file: inFile)

Determine if at least one character can be read successfully. This function allows a file to be handled like an iterator.

Returns:

FALSE if getc would return EOF, TRUE otherwise.

const func boolean: inputReady (in file: inFile)

Determine if at least one character can be read without blocking. Blocking means that getc would wait until a character is received. Blocking can last for a period of unspecified length. Regular files do not block.

Returns:

TRUE if getc would not block, FALSE otherwise.

const func integer: length (inout file: aFile)

Obtain the length of a file. The file length is measured in bytes.

Returns:

the length of a file.

Raises:

RANGE_ERROR - The file length does not fit into an integer value.

FILE_ERROR - The implementation type of aFile is not seekable or a system function returns an error or the file length reported by the system is negative.

const proc: truncate (inout file: aFile, in integer: length)

Truncate aFile to the given length. If the file previously was larger than length, the extra data is lost. If the file previously was shorter, it is extended, and the extended part is filled with null bytes ('\0;').

Parameters:

aFile - File to be truncated.

length - Requested length of aFile in bytes.

Raises:

RANGE_ERROR - The requested length is negative or the length is not representable in the type used by the system function.

FILE_ERROR - A system function returns an error.

const func boolean: seekable (in file: aFile)

Determine if the file aFile is seekable. If a file is seekable the functions seek and tell can be used to set and and obtain the current file position.

Returns:

TRUE, if aFile is seekable, FALSE otherwise.

const proc: seek (inout file: aFile, in integer: position)

Set the current file position. The file position is measured in bytes from the start of the file. The first byte in the file has the position 1.

Raises:

RANGE_ERROR - The file position is negative or zero or the file position is not representable in the system file position type.

FILE_ERROR - The implementation type of aFile is not seekable or a system function returns an error.

const func integer: tell (in file: aFile)

Obtain the current file position. The file position is measured in bytes from the start of the file. The first byte in the file has the position 1.

Returns:

the current file position.

Raises:

RANGE_ERROR - The file position does not fit into an integer value.

FILE_ERROR - The implementation type of aFile is not seekable or a system function returns an error or the file position reported by the system is negative.

const func integer: compare (in file: file1, in file: file2)

Compare two file values. This function does neither compare file contents nor file names. The order of two files is determined by comparing the memory positions of their internal data representation. Therefore the result of compare is arbitrary and may change if the program is executed again. Inside a program the result of compare is consistent and can be used to maintain hash tables.

Returns:

-1, 0 or 1 if the first argument is considered to be respectively less than, equal to, or greater than the second.

const func integer: hashCode (in file: aFile)

Compute the hash value of a file.

Returns:

the hash value.

const proc: read (inout file: inFile, inout string: aVar)

Read a word from inFile into aVar. Before reading the word it skips spaces and tabs. The function accepts words ending with " ", "\t", end-of-line or EOF. The word ending character is not copied into the string. When the function is left inFile.bufferChar contains the word ending character (' ', '\t', '\n' or EOF).

const proc: read (inout file: inFile, inout string: aVar, in string: defaultValue)

Read a word from inFile into aVar or use defaultValue. Before reading the word it skips spaces and tabs. The function accepts words ending with " ", "\t", end-of-line or EOF. If the word is empty defaultValue is assigned to aVar. The word ending character is not copied into the string. When the function is left inFile.bufferChar contains the word ending character (' ', '\t', '\n' or EOF).

const proc: readln (inout file: inFile, inout string: aVar)

Read a line from inFile into aVar. The function reads a string up to end-of-line or EOF. The line ending character is not copied into the string. When the function is left inFile.bufferChar contains the line ending character ('\n' or EOF).

const proc: readln (inout file: inFile, inout string: aVar, in string: defaultValue)

Read a line from inFile into aVar or use defaultValue. The function reads a string up to end-of-line or EOF. If the line is empty defaultValue is assigned to aVar. The line ending character is not copied into the string. When the function is left inFile.bufferChar contains the line ending character ('\n' or EOF).

const proc: readln (inout file: inFile)

Discard a line from a file. The function discards characters up to end-of-line or EOF. When the function is left inFile.bufferChar contains the line ending character ('\n' or EOF).

const proc: skip (inout file: inFile, in var integer: numChars)

Skip numChars characters from inFile. When the function is left numChars have been skipped from inFile or EOF has been reached.

Raises:

RANGE_ERROR - The parameter numChars is negative.