123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154 |
- .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 ...
|