INPUT(3)

NAME
LoadChar, PushBack, InsertFile, InsertText, AtEoIF, AtEoIT - input module for compilers

SYNOPSIS
LoadChar(ch)
int ch;

PushBack()

ChPushBack(ch)
int ch;

int InsertFile(filename, table, result)
char *filename;
char *table[];
char **result;

int InsertText(text, length)
char *text;
int length;

int AtEoIF()

int AtEoIT()

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 current input stream is the last inserted input stream that has not reached its end.

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: input.c and input.h. input.h could contain the following:

    #define INP_NPUSHBACK 2
    #define INP_TYPE struct f_info
    #define INP_VAR	file_info
    #define INP_BUFSIZE 4096
    #include <inp_pkg.spec>

and input.c could contain:

    #include "f_info.h"          /* contains definition for struct f_info */
    #include "input.h"
    #include <inp_pkg.body>

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.

INP_NPUSHBACK is the number of PushBacks that are guaranteed to work. Its default value is 1. It is expected to be small.

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.

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 system(3) module.

The macro LoadChar stores the next character from the current input stream in the variable ch, 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 inp_pkg.spec, is returned.

The macro PushBack pushes the last character read back onto the input stream.

The macro ChPushBack inserts the character ch into the input stream.

The routine InsertFile suspends input from the current input stream. The next input characters will be obtained from the specified file filename. This file will be looked for in the directories, mentioned in the null-terminated list table. When table is 0, only the current directory is searched. A null string (different from null-pointer!) in the table means: current directory. When filename starts with a "/", table is not used. If filename is a null pointer, standard input is used. In this case, the package may not have been instantiated with INP_READ_IN_ONE defined. InsertFile returns 1 if it succeeds, 0 if it fails. When it succeeds, and result is not 0, it stores the file name in the result parameter.

The routine InsertText also suspends input from the current input stream. The next input characters will be obtained from the string text, which is length characters long. InsertText returns 1 if it succeeds, 0 if it fails. The text string is not copied, so it should not be changed until the corresponding AtEoIT is called.

The routine AtEoIF is called at the end of the input stream inserted by InsertFile. 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 AtEoIF 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.

The routine AtEoIT is called at the end of the string inserted by InsertText. 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 AtEoIT 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.

FILES
~em/modules/pkg/inp_pkg.spec
~em/modules/pkg/inp_pkg.body
~em/modules/lib/libinput.a

MODULES
system(3), alloc(3)

SEE ALSO
Generic Packages in C by Dick Grune.

BUGS
A LoadChar-call does look like a function call, but behaves differently. All for the sake of speed of course ...