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
2#10101010
8#072
10#365
16#1A02
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.