modules/src/input/input.3

   1 .TH INPUT 3 "$Revision: 1.8 $"
   2 .ad
   3 .SH NAME
   4 LoadChar, PushBack, InsertFile, InsertText, AtEoIF, AtEoIT\ \-\ input
   5 module for compilers
   6 .SH SYNOPSIS
   7 .B LoadChar(ch)
   8 .br
   9 .B int ch;
  10 .PP
  11 .B PushBack()
  12 .PP
  13 .B ChPushBack(ch)
  14 .br
  15 .B int ch;
  16 .PP
  17 .B int InsertFile(filename, table, result)
  18 .br
  19 .B char *filename;
  20 .br
  21 .B char *table[];
  22 .br
  23 .B char **result;
  24 .PP
  25 .B int InsertText(text, length)
  26 .br
  27 .B char *text;
  28 .br
  29 .B int length;
  30 .PP
  31 .B int AtEoIF()
  32 .PP
  33 .B int AtEoIT()
  34 .SH DESCRIPTION
  35 This set of variables, macros and routines provides a fast input mechanism
  36 for use by compilers.
  37 They also provide a means of inserting new input streams,
  38 thereby temporarily suspending an input
  39 stream to read another one.
  40 The \fBcurrent input stream\fR is the last inserted input stream that
  41 has not reached its end.
  42 .PP
  43 The module is generic: it must be instantiated by #defining INP_TYPE,
  44 INP_VAR, INP_READ_IN_ONE, INP_BUFSIZE, and INP_NPUSHBACK.
  45 An instantiation can be obtained by creating two files: \fIinput.c\fR and
  46 \fIinput.h\fR.
  47 \fIinput.h\fR could contain the following:
  48 .PP
  49 .RS
  50 .nf
  51 #define INP_NPUSHBACK 2
  52 #define INP_TYPE struct f_info
  53 #define INP_VAR file_info
  54 #define INP_BUFSIZE 4096
  55
  56 #include <inp_pkg.spec>
  57 .fi
  58 .RE
  59 .PP
  60 and \fIinput.c\fR could contain:
  61 .PP
  62 .RS
  63 .nf
  64 #include "f_info.h"          /* contains definition for struct f_info */
  65 #include "input.h"
  66 #include <inp_pkg.body>
  67 .fi
  68 .RE
  69 .PP
  70 The user may associate certain data with each input stream. The input module
  71 has a facility to save these data when inserting a new input stream, and
  72 restoring them when restoring the suspended input stream. Examples of these
  73 data are for instance a linenumber, a filename, etc.
  74 These data must be collected in a variable INP_VAR of type INP_TYPE.
  75 INP_VAR and INP_TYPE must be preprocessor-#defined.
  76 Not #defining INP_TYPE has the effect that an instantiation will be created
  77 that does not save and restore these data.
  78 .PP
  79 INP_NPUSHBACK is the number of PushBacks that are guaranteed to work.
  80 Its default value is 1. It is expected to be small.
  81 .PP
  82 INP_READ_IN_ONE can either be defined or not defined. Defining it has the
  83 effect that files will be read completely with one read-system call. This
  84 should only be used on machines with lots of memory.
  85 .PP
  86 INP_BUFSIZE defines the input buffer size that is used when INP_READ_IN_ONE
  87 is not defined. Its default value is BUFSIZ, from the \fIsystem\fP(3) module.
  88 .PP
  89 The macro \fILoadChar\fR stores the next character from the current input stream
  90 in the variable \fIch\fR,
  91 which is passed as a parameter.
  92 Note that this simulates an output parameter!
  93 When the end of the current input stream is reached, the next character from
  94 the last suspended input stream will be stored, etc.
  95 If there are no suspended input streams left, the constant EOI,
  96 which is defined in \fIinp_pkg.spec\fR, is returned.
  97 .PP
  98 The macro \fIPushBack\fR pushes the last character read back onto the
  99 input stream.
 100 .PP
 101 The macro \fIChPushBack\fR inserts the character \fIch\fP into the
 102 input stream.
 103 .PP
 104 The routine \fIInsertFile\fR suspends input from the current input stream.
 105 The next input characters will be obtained from the specified file
 106 \fIfilename\fR.
 107 This file will be looked for in the directories, mentioned in the
 108 null-terminated list \fItable\fR.
 109 When \fItable\fR is 0, only the current directory is searched.
 110 A null string  (different from null-pointer!) in the table means:
 111 current directory.
 112 When \fIfilename\fR starts with a "/", \fItable\fR is not used.
 113 If \fIfilename\fR is a null pointer, standard input is used. In this case,
 114 the package may not have been instantiated with INP_READ_IN_ONE defined.
 115 \fIInsertFile\fR returns 1 if it succeeds, 0 if it fails.
 116 When it succeeds, and \fIresult\fR is not 0, it stores the file name in the \fIresult\fR parameter.
 117 .PP
 118 The routine \fIInsertText\fR also suspends input from the current input stream.
 119 The next input characters will be obtained from the string \fItext\fR,
 120 which is \fIlength\fR characters long.
 121 \fIInsertText\fR returns 1 if it succeeds, 0 if it fails.
 122 The \fItext\fR string is not copied, so it should not be changed until the
 123 corresponding \fIAtEoIT\fR is called.
 124 .PP
 125 The routine \fIAtEoIF\fR is called at the end of the input stream
 126 inserted by \fIInsertFile\fR.
 127 If it returns 1, the LoadChar causing the call returns EOI, otherwize
 128 the LoadChar returns the next character of the suspended and now restored
 129 input stream.
 130 A default \fIAtEoIF\fR is provided. It does nothing, and returns 0,
 131 making the "unstacking" completely transparent.
 132 The user of the module can write his own if this is not what he wants.
 133 .PP
 134 The routine \fIAtEoIT\fR is called at the end of the string
 135 inserted by \fIInsertText\fR.
 136 If it returns 1, the LoadChar causing the call returns EOI, otherwise
 137 the LoadChar returns the next character of the suspended and now restored
 138 input stream.
 139 A default \fIAtEoIT\fR is provided. It does nothing, and returns 0,
 140 making the "unstacking" completely transparent.
 141 The user of the module can write his own if this is not what he wants.
 142 .SH FILES
 143 ~em/modules/pkg/inp_pkg.spec
 144 .br
 145 ~em/modules/pkg/inp_pkg.body
 146 .br
 147 ~em/modules/lib/libinput.a
 148 .SH MODULES
 149 system(3), alloc(3)
 150 .SH "SEE ALSO"
 151 \fIGeneric Packages in C\fR by Dick Grune.
 152 .SH BUGS
 153 A \fILoadChar\fR-call does look like a function call,
 154 but behaves differently. All for the sake of speed of course ...