input.3 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. .TH INPUT 3 "$Revision$"
  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. #include <inp_pkg.spec>
  56. .fi
  57. .RE
  58. .PP
  59. and \fIinput.c\fR could contain:
  60. .PP
  61. .RS
  62. .nf
  63. #include "f_info.h" /* contains definition for struct f_info */
  64. #include "input.h"
  65. #include <inp_pkg.body>
  66. .fi
  67. .RE
  68. .PP
  69. The user may associate certain data with each input stream. The input module
  70. has a facility to save these data when inserting a new input stream, and
  71. restoring them when restoring the suspended input stream. Examples of these
  72. data are for instance a linenumber, a filename, etc.
  73. These data must be collected in a variable INP_VAR of type INP_TYPE.
  74. INP_VAR and INP_TYPE must be preprocessor-#defined.
  75. Not #defining INP_TYPE has the effect that an instantiation will be created
  76. that does not save and restore these data.
  77. .PP
  78. INP_NPUSHBACK is the number of PushBacks that are guaranteed to work.
  79. Its default value is 1. It is expected to be small.
  80. .PP
  81. INP_READ_IN_ONE can either be defined or not defined. Defining it has the
  82. effect that files will be read completely with one read-system call. This
  83. should only be used on machines with lots of memory.
  84. .PP
  85. INP_BUFSIZE defines the input buffer size that is used when INP_READ_IN_ONE
  86. is not defined. Its default value is BUFSIZ, from the \fIsystem\fP(3) module.
  87. .PP
  88. The macro \fILoadChar\fR stores the next character from the current input stream
  89. in the variable \fIch\fR,
  90. which is passed as a parameter.
  91. Note that this simulates an output parameter!
  92. When the end of the current input stream is reached, the next character from
  93. the last suspended input stream will be stored, etc.
  94. If there are no suspended input streams left, the constant EOI,
  95. which is defined in \fIinp_pkg.spec\fR, is returned.
  96. .PP
  97. The macro \fIPushBack\fR pushes the last character read back onto the
  98. input stream.
  99. .PP
  100. The macro \fIChPushBack\fR inserts the character \fIch\fP into the
  101. input stream.
  102. .PP
  103. The routine \fIInsertFile\fR suspends input from the current input stream.
  104. The next input characters will be obtained from the specified file
  105. \fIfilename\fR.
  106. This file will be looked for in the directories, mentioned in the
  107. null-terminated list \fItable\fR.
  108. When \fItable\fR is 0, only the current directory is searched.
  109. A null string (different from null-pointer!) in the table means:
  110. current directory.
  111. When \fIfilename\fR starts with a "/", \fItable\fR is not used.
  112. If \fIfilename\fR is a null pointer, standard input is used. In this case,
  113. the package may not have been instantiated with INP_READ_IN_ONE defined.
  114. \fIInsertFile\fR returns 1 if it succeeds, 0 if it fails.
  115. When it succeeds, and \fIresult\fR is not 0, it stores the file name in the \fIresult\fR parameter.
  116. .PP
  117. The routine \fIInsertText\fR also suspends input from the current input stream.
  118. The next input characters will be obtained from the string \fItext\fR,
  119. which is \fIlength\fR characters long.
  120. \fIInsertText\fR returns 1 if it succeeds, 0 if it fails.
  121. The \fItext\fR string is not copied, so it should not be changed until the
  122. corresponding \fIAtEoIT\fR is called.
  123. .PP
  124. The routine \fIAtEoIF\fR is called at the end of the input stream
  125. inserted by \fIInsertFile\fR.
  126. If it returns 1, the LoadChar causing the call returns EOI, otherwize
  127. the LoadChar returns the next character of the suspended and now restored
  128. input stream.
  129. A default \fIAtEoIF\fR is provided. It does nothing, and returns 0,
  130. making the "unstacking" completely transparent.
  131. The user of the module can write his own if this is not what he wants.
  132. .PP
  133. The routine \fIAtEoIT\fR is called at the end of the string
  134. inserted by \fIInsertText\fR.
  135. If it returns 1, the LoadChar causing the call returns EOI, otherwise
  136. the LoadChar returns the next character of the suspended and now restored
  137. input stream.
  138. A default \fIAtEoIT\fR is provided. It does nothing, and returns 0,
  139. making the "unstacking" completely transparent.
  140. The user of the module can write his own if this is not what he wants.
  141. .SH FILES
  142. ~em/modules/pkg/inp_pkg.spec
  143. .br
  144. ~em/modules/pkg/inp_pkg.body
  145. .br
  146. ~em/modules/lib/libinput.a
  147. .SH MODULES
  148. system(3), alloc(3)
  149. .SH "SEE ALSO"
  150. \fIGeneric Packages in C\fR by Dick Grune.
  151. .SH BUGS
  152. A \fILoadChar\fR-call does look like a function call,
  153. but behaves differently. All for the sake of speed of course ...