153 lines
5.2 KiB
Groff
153 lines
5.2 KiB
Groff
.TH INPUT 3ACK "March 25, 1986"
|
|
.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. When it is not,
|
|
perhaps it is wise to include "." in the table ...
|
|
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 ...
|