.TH INPUT 3 "$Revision$"
.ad
.SH NAME
LoadChar, PushBack, InsertFile, InsertText, AtEoIF, AtEoIT\ \-\ input
module for compilers
.SH SYNOPSIS
.B LoadChar(ch)
.br
.B int ch;
.PP
.B PushBack()
.PP
.B ChPushBack(ch)
.br
.B int ch;
.PP
.B int InsertFile(filename, table, result)
.br
.B char *filename;
.br
.B char *table[];
.br
.B char **result;
.PP
.B int InsertText(text, length)
.br
.B char *text;
.br
.B int length;
.PP
.B int AtEoIF()
.PP
.B int AtEoIT()
.SH DESCRIPTION
This set of variables, macros and routines provides a fast input mechanism
for use by compilers.
They also provide a means of inserting new input streams, 
thereby temporarily suspending an input
stream to read another one.
The \fBcurrent input stream\fR is the last inserted input stream that
has not reached its end.
.PP
The module is generic: it must be instantiated by #defining INP_TYPE,
INP_VAR, INP_READ_IN_ONE, INP_BUFSIZE, and INP_NPUSHBACK.
An instantiation can be obtained by creating two files: \fIinput.c\fR and 
\fIinput.h\fR.
\fIinput.h\fR could contain the following:
.PP
.RS
.nf
#define INP_NPUSHBACK 2
#define INP_TYPE struct f_info
#define INP_VAR	file_info
#define INP_BUFSIZE 4096

#include <inp_pkg.spec>
.fi
.RE
.PP
and \fIinput.c\fR could contain:
.PP
.RS
.nf
#include "f_info.h"          /* contains definition for struct f_info */
#include "input.h"
#include <inp_pkg.body>
.fi
.RE
.PP
The user may associate certain data with each input stream. The input module 
has a facility to save these data when inserting a new input stream, and
restoring them when restoring the suspended input stream. Examples of these
data are for instance a linenumber, a filename, etc.
These data must be collected in a variable INP_VAR of type INP_TYPE.
INP_VAR and INP_TYPE must be preprocessor-#defined.
Not #defining INP_TYPE has the effect that an instantiation will be created
that does not save and restore these data.
.PP
INP_NPUSHBACK is the number of PushBacks that are guaranteed to work.
Its default value is 1. It is expected to be small.
.PP
INP_READ_IN_ONE can either be defined or not defined. Defining it has the
effect that files will be read completely with one read-system call. This
should only be used on machines with lots of memory.
.PP
INP_BUFSIZE defines the input buffer size that is used when INP_READ_IN_ONE
is not defined. Its default value is BUFSIZ, from the \fIsystem\fP(3) module.
.PP
The macro \fILoadChar\fR stores the next character from the current input stream
in the variable \fIch\fR,
which is passed as a parameter.
Note that this simulates an output parameter!
When the end of the current input stream is reached, the next character from
the last suspended input stream will be stored, etc.
If there are no suspended input streams left, the constant EOI,
which is defined in \fIinp_pkg.spec\fR, is returned.
.PP
The macro \fIPushBack\fR pushes the last character read back onto the
input stream.
.PP
The macro \fIChPushBack\fR inserts the character \fIch\fP into the
input stream.
.PP
The routine \fIInsertFile\fR suspends input from the current input stream.
The next input characters will be obtained from the specified file
\fIfilename\fR.
This file will be looked for in the directories, mentioned in the
null-terminated list \fItable\fR.
When \fItable\fR is 0, only the current directory is searched.
A null string  (different from null-pointer!) in the table means:
current directory.
When \fIfilename\fR starts with a "/", \fItable\fR is not used.
If \fIfilename\fR is a null pointer, standard input is used. In this case,
the package may not have been instantiated with INP_READ_IN_ONE defined.
\fIInsertFile\fR returns 1 if it succeeds, 0 if it fails.
When it succeeds, and \fIresult\fR is not 0, it stores the file name in the \fIresult\fR parameter.
.PP
The routine \fIInsertText\fR also suspends input from the current input stream.
The next input characters will be obtained from the string \fItext\fR,
which is \fIlength\fR characters long.
\fIInsertText\fR returns 1 if it succeeds, 0 if it fails.
The \fItext\fR string is not copied, so it should not be changed until the
corresponding \fIAtEoIT\fR is called.
.PP
The routine \fIAtEoIF\fR is called at the end of the input stream
inserted by \fIInsertFile\fR.
If it returns 1, the LoadChar causing the call returns EOI, otherwize
the LoadChar returns the next character of the suspended and now restored
input stream.
A default \fIAtEoIF\fR is provided. It does nothing, and returns 0,
making the "unstacking" completely transparent.
The user of the module can write his own if this is not what he wants.
.PP
The routine \fIAtEoIT\fR is called at the end of the string
inserted by \fIInsertText\fR.
If it returns 1, the LoadChar causing the call returns EOI, otherwise
the LoadChar returns the next character of the suspended and now restored
input stream.
A default \fIAtEoIT\fR is provided. It does nothing, and returns 0,
making the "unstacking" completely transparent.
The user of the module can write his own if this is not what he wants.
.SH FILES
~em/modules/pkg/inp_pkg.spec
.br
~em/modules/pkg/inp_pkg.body
.br
~em/modules/lib/libinput.a
.SH MODULES
system(3), alloc(3)
.SH "SEE ALSO"
\fIGeneric Packages in C\fR by Dick Grune.
.SH BUGS
A \fILoadChar\fR-call does look like a function call, 
but behaves differently. All for the sake of speed of course ...