Library Reference
 
#include "source.h"
SrcBufPtr SrcBuffer;
char *SRCFILE;
char *TEXTSTART;
void initBuf(char *name, int f);
void refillBuf(char *p);
int finlBuf();
The source module has been designed to allow rapid access to the
characters of a text file.
A text file is a sequence of lines,
each terminated by a newline character.
There is no limit on the length of a line.
The source module guarantees that if the first character of a line is in
memory then all of the characters of that line, including the terminating
newline character, are in contiguous memory locations.
The newline terminating the last line in memory is followed by an ASCII NUL
character, and thus the sequence of lines constitutes a C string.
NUL characters are not allowed within the text file.
To use the module, first call initBuf, with a file name and descriptor.
The file must be opened for reading (by open(2) prior to the call.
Upon return,
SrcBuffer points to a new text buffer,
SRCFILE is the symbolic name of the input file,
and TEXTSTART points to the first character of the first line of the
input file.
(If the input file is empty then TEXTSTART points to an ASCII NUL
character.)
SRCFILE and TEXTSTART are components of the text buffer;
TEXTSTART may be arbitrarily altered by any client of the source
module.
Normally, TEXTSTART is used to describe the position reached by the
client in processing the buffer's text.
Because it is a component of the text buffer, there is no need to save and
restore it when another text buffer is created by a subsequent invocation
of initBuf.
All source module operations take place on the text buffer pointed to by
SrcBuffer, and both SRCFILE and TEXTSTART use
SrcBuffer to access the text buffer.
A client of the source module may manage a number of text buffers
simultaneously by saving and restoring SrcBuffer.
When a client has processed all of the information in a text buffer,
additional information can be obtained from the file by invoking
refillBuf with a pointer to the text in the buffer.
At least one line of text will be added to the text pointed to by the
argument of refillBuf, and upon return TEXTSTART points to
the first character of the augmented text.
The content of the memory pointed to by the argument of refillBuf
is undefined.
(If there is no more information in the file then the string pointed
to by the argument of refillBuf is not augmented.
Upon return TEXTSTART points to the first character of that string
and the content of the memory pointed to by the argument of
refillBuf is undefined.)
Invocation of finlBuf frees all storage for the text buffer pointed
to by SrcBuffer.
Upon return, SrcBuffer contains a null pointer and the value of
finlBuf is the descriptor of the file associated with the buffer.
The file itself has not been closed.
|
