const type: clib_file

File type realized with FILE * files from the C runtime library. The type clib_file is not accessible via the file interface. The type external_file, which implements the file interface is based on a clib_file. Access to operating system files should always be done via the file interface and files of the type external_file.

const clib_file: CLIB_NULL_FILE

NULL file of the C runtime library. This value is returned by openClibFile and other functions if no clib_file could be opened. Reading from or writing to a CLIB_NULL_FILE raises an exception.

const func boolean: (in clib_file: file1) = (in clib_file: file2)

Check if two files are equal.

Returns:

TRUE if the two files are equal, FALSE otherwise.

const func boolean: (in clib_file: file1) <> (in clib_file: file2)

Check if two files are not equal.

Returns:

FALSE if both files are equal, TRUE otherwise.

const func clib_file: openClibFile (in string: path, in string: mode)

Opens a clib_file with the specified path and mode. There are text modes and binary modes:

• Binary modes:
  • "r" Open file for reading.
  • "w" Truncate to zero length or create file for writing.
  • "a" Append; open or create file for writing at end-of-file.
  • "r+" Open file for update (reading and writing).
  • "w+" Truncate to zero length or create file for update.
  • "a+" Append; open or create file for update, writing at end-of-file.
• Text modes:
  • "rt" Open file for reading.
  • "wt" Truncate to zero length or create file for writing.
  • "at" Append; open or create file for writing at end-of-file.
  • "rt+" Open file for update (reading and writing).
  • "wt+" Truncate to zero length or create file for update.
  • "at+" Append; open or create file for update, writing at end-of-file.

Note that this modes differ from the ones used by the C function fopen().

Parameters:

path - Path of the file to be opened. The path must use the standard path representation.

mode - Mode of the file to be opened.

Returns:

the file opened, or STD_NULL if it could not be opened or if path refers to a directory.

Raises:

MEMORY_ERROR - Not enough memory to convert the path to the system path type.

RANGE_ERROR - The mode is not one of the allowed values or path does not use the standard path representation or path cannot be converted to the system path type.

const proc: close (in clib_file: aFile)

Close a clib_file.

Raises:

FILE_ERROR - A system function returns an error.

const func boolean: eof (in clib_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 (in clib_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 clib_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 proc: flush (in clib_file: outFile)

Forces that all buffered data of outFile is sent to its destination. This causes data to be sent to the file system of the OS.

const func char: getc (in clib_file: inFile)

Read a character from a clib_file.

Returns:

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

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

Read a string with a maximum length from a clib_file.

Returns:

the string read.

Raises:

RANGE_ERROR - The parameter maxLength is negative.

MEMORY_ERROR - Not enough memory to represent the result.

FILE_ERROR - A system function returns an error.

const func string: terminated_read (in clib_file: inFile, in char: terminator, inout char: terminationChar)

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

Parameters:

inFile - File from which the string is read.

terminator - Character which terminates the string.

terminationChar - Variable to receive the actual termination character (either terminator or EOF).

Returns:

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

Raises:

MEMORY_ERROR - Not enough memory to represent the result.

FILE_ERROR - A system function returns an error.

const func string: word_read (in clib_file: inFile, inout char: terminationChar)

Read a word from a clib_file. Before reading the word it skips spaces and tabs. The function accepts words ending with " ", "\t", "\n", "\r\n" or EOF. The word ending characters are not copied into the string. That means that the "\r" of a "\r\n" sequence is silently removed. When the function is left terminationChar contains ' ', '\t', '\n' or EOF.

Returns:

the word read.

Raises:

MEMORY_ERROR - Not enough memory to represent the result.

FILE_ERROR - A system function returns an error.

const func string: line_read (in clib_file: inFile, inout char: terminationChar)

Read a line from a clib_file. The function accepts lines ending with "\n", "\r\n" or EOF. The line ending characters are not copied into the string. That means that the "\r" of a "\r\n" sequence is silently removed. When the function is left terminationChar contains '\n' or EOF.

Returns:

the line read.

Raises:

MEMORY_ERROR - Not enough memory to represent the result.

FILE_ERROR - A system function returns an error.

const proc: write (in clib_file: outFile, in string: stri)

Write a string to a clib_file.

Raises:

FILE_ERROR - A system function returns an error.

RANGE_ERROR - The string contains a character that does not fit into a byte.

const func integer: length (in clib_file: aFile)

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

Returns:

the size of the given file.

Raises:

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

FILE_ERROR - A system function returns an error or the file length reported by the system is negative.

const proc: truncate (in clib_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 clib_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 (in clib_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 - A system function returns an error.

const func integer: tell (in clib_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 - A system function returns an error or the file position reported by the system is negative.