LARD I/O Library: Introduction

Accessing the I/O Library

For your program to access the I/O library it needs to start with a use clause:

	use(io).

File Handles

Files are accessed via hadles, in a similar way to C or many other languages. (This shouldn't be suprising as LARD files are implemented on top of C files). You open a named file and a handle is returned. You then use that handle to refer to the open file when reading or writing to it.

File Types

LARD has two types of file: text files and binary files. Text files operate line-by-line and are intended for conveniently reading human-readable input. Binary files are just sequences of characters and are intended for reading non-human-readable input.

Handles for text files are variables of type tfile, and handles for binary files are variables of type bfile.

Predefined Files

There are three predefined file handles: stdin, stdout and stderr. These are all text files.

Opening and Closing Files

Five functions exist to open files. Each function takes a filename as its argument and returns a file handle.

topenin: Open a text file for input.
topenout: Open a text file for output.
bopenin: Open a binary file for input.
bopenout: Open a binary file for output.
bopeninout: Open a binary file for input and output.

The function close takes a file handle and closes the file.

Reading and Writing to Text Files

The following functions provide formatted input/output on text files:

fprintint: Write an integer in decimal.
fprinthex: Write an integer in hex.
fprintchar: Write a single character.
fprintstr: Write a string.

The above output functions output only the data supplied; any newlines must be provided explicitly.

freadint: Read an integer.
freadchar: Read a single character.
freadstr: Read a string.

freadint and freadstr each read a whole line from the file.

freadint recognises numbers with a base specified using the syntax

If no base is specified in this way the number is parsed according to the base specified by the last call to set_default_input_base, or decimal if that function has not been called. Note that set_default_input_base works globally, not on a per-file basis.

For each fprint... or fread... function there is a coresponding print... or read... function that operates on stdin or stdout. There is also an overloaded varargs function print that takes many types.

Input/Output to Binary Files

The following functions provide input/output to binary files:

fputc: Write a single character to a file.
fgetc: Read a single character from a file.
fwrite: Write to a file. Any value can be passed to this function, and enough bytes are written to store its LARD representation.
fread: Read from a file. Any variable can be passed to this function, and enough bytes are read to fill the variable.

There are some important caveats concerning the use of fwrite and fread:

The representation stored or read depends on the host byte sex.
The LARD representation of certain types may not be what you expect. In particular storing strings will not work, and characters are actually stored in words. Arrays and records of integers will come out OK.

Detecting End Of File

The function eof returns a boolean indicating whether end of file has been reached for a particular file. The exact behaviour of this function depends on whether the file is a text file or a binary file. For a text file, eof skips over any whitespace before performing the actual end of file test. This does not occur for binary files.

File Positioning and Miscellaneous Functions

The following other functions are available for binary files:

fseek: Set the file position.
ftell: Return the current file position.
flen: Return the length of the file.
ftrunc: Truncate the file, discarding the part beyond the current file position.

Error Handling

All of these functions cause a run-time error if something goes wrong.