Mercurial > ~dholland > hg > ag > index.cgi

comparison doc/misc/html/examples/mpp/mpp.html @ 0:13d2b8934445

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import AnaGram (near-)release tree into Mercurial.
author David A. Holland
date Sat, 22 Dec 2007 17:52:45 -0500
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:13d2b8934445
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <HTML>
3 <HEAD>
4 <TITLE> Main Program - Macro preprocessor and C Parser </TITLE>
5 </HEAD>
6
7
8 <BODY BGCOLOR="#ffffff" BACKGROUND="tilbl6h.gif"
9 TEXT="#000000" LINK="#0033CC"
10 VLINK="#CC0033" ALINK="#CC0099">
11
12 <P>
13 <IMG ALIGN="right" SRC="../../images/agrsl6c.gif" ALT="AnaGram"
14 WIDTH=124 HEIGHT=30 >
15 <BR CLEAR="all">
16 Back to :
17 <A HREF="../../index.html">Index</A> |
18 <A HREF="index.html">Macro preprocessor overview</A>
19 <P>
20 <IMG ALIGN="bottom" SRC="../../images/rbline6j.gif" ALT="----------------------"
21 WIDTH=1010 HEIGHT=2 >
22 <P>
23
24 <H1> Main Program - Macro preprocessor and C Parser </H1>
25
26 <IMG ALIGN="bottom" SRC="../../images/rbline6j.gif" ALT="----------------------"
27 WIDTH=1010 HEIGHT=2 >
28 <P>
29 <BR>
30
31 <H2>Introduction</H2>
32 <P>
33 <tt>mpp.h</tt> contains type definitions, external definitions and
34 function declarations for the macro preprocessor. <tt>mpp.cpp</tt>
35 contains all global data definitions and the main program.
36
37 <P>
38 <BR>
39
40 <H2> Type Definitions </H2>
41 <DL>
42 <DT> <tt>macro_descriptor</tt>
43
44 <DD> This structure contains a complete description of a macro.
45 The name index allows the linkage between the token
46 dictionary and the macro table to be modified when a macro
47 is undefined so that the macro table can be maintained in a
48 compact form.
49
50
51 <DT> <tt>op_descriptor</tt>
52
53 <DD> This structure is used only for initializing tables in
54 <tt>mpp.cpp</tt>.
55 </DL>
56 <P>
57 <BR>
58
59 <H2> Parser Class Definitions </H2>
60 <DL>
61 <DT> <tt>expression_evaluator</tt>
62
63 <DD> This class definition serves as an interface to the
64 constant expression evaluation logic in <tt>ex.syn</tt>, where the
65 member functions are defined. It is derived from the
66 token_sink class. In <tt>ts.syn</tt>,
67 <tt>init_condition</tt> redirects scanner
68 output temporarily to the expression evaluator.
69
70 <DT> <tt>c_parser</tt>
71
72 <DD> This class definition serves as an interface to the c parser
73 in <tt>jrc.syn</tt> or <tt>krc.syn</tt>, where the member
74 functions are defined. The
75 <tt>c_parser</tt> class is derived from the
76 <tt>token_sink</tt> class. The
77 main program uses this capability to determine the
78 destination of tokens output by the token scanner. If the
79 user requests C parsing, the <tt>token_sink</tt> pointer
80 <tt>scanner_sink</tt>
81 is loaded with a pointer to an instance of <tt>c_parser</tt>.
82 Otherwise <tt>scanner_sink</tt> is loaded with a pointer to a
83 <tt>token_translator</tt>.
84 </DL>
85 <P>
86 <BR>
87
88 <H2> Global Variables </H2>
89
90 <H3> <tt>condition</tt> </H3>
91 <TABLE>
92 <TR> <TH VALIGN=top> Type: </TH><TD><tt>expression_evaluator</tt></TD></TR>
93
94 <TR> <TH VALIGN=top> Purpose: </TH>
95 <TD> This class encapsulates the logic for evaluating constant
96 expressions found in #if statements. </TD> </TR>
97 <TR> <TH VALIGN=top> Usage: </TH> <TD>
98 <TABLE>
99 <TR><TD VALIGN=top><tt>reset(condition);</tt></TD>
100 <TD WIDTH=5%>&nbsp;</TD>
101 <TD>prepares for a new expression</TD></TR>
102
103 <TR><TD VALIGN=top><tt>condition &lt;&lt; </tt><i>token
104 string,/i><tt>;</tt></TD>
105 <TD WIDTH=5%>&nbsp;</TD>
106 <TD>offers a token string for evaluation</TD></TR>
107
108 <TR><TD VALIGN=top><tt>long result = condition;</tt></TD>
109 <TD WIDTH=5%>&nbsp;</TD>
110 <TD>retrieves value of expression</TD></TR>
111 </TABLE>
112 </TD></TR>
113 <TR> <TH VALIGN=top> Precautions: </TH>
114 <TD> The input token string must not be on the token
115 accumulator. If it was developed on the token
116 accumulator, it should be popped off before being handed
117 to <tt>condition</tt>. </TD> </TR>
118
119 <TR> <TH VALIGN=top> Notes: </TH>
120 <TD> This is the only instance of an
121 <tt>expression_evaluator</tt> in the program. Member
122 functions are implemented in <tt>ex.syn</tt>. </TD> </TR>
123 </TABLE>
124 <P>
125
126 <H3> <tt>default_path</tt> </H3>
127 <TABLE>
128 <TR> <TH VALIGN=top> Type: </TH><TD><tt>char[]</tt> </TD></TR>
129
130 <TR> <TH VALIGN=top> Purpose: </TH>
131 <TD>
132 This character array contains the default paths for
133 include files. If more than one directory is specified,
134 use a '<CODE>;</CODE>' just as with the DOS PATH command.
135 <P>
136 More paths can be provided using the command line -i
137 switch. Note that directories are searched in order
138 beginning with those specified in the command line. </TD></TR>
139 </TABLE>
140 <P>
141
142 <H3> <tt>defined_value</tt> </H3>
143 <TABLE>
144 <TR> <TH VALIGN=top> Type: </TH><TD><tt>unsigned</tt> </TD></TR>
145
146 <TR> <TH VALIGN=top> Purpose: </TH>
147 <TD>
148 This variable holds the token dictionary index for the
149 (sometimes) keyword "defined". "defined" is recognized
150 only when evaluating the conditional expressions in <tt>#if</tt>
151 statements. </TD></TR>
152
153 <TR> <TH VALIGN=top> Purpose: </TH>
154 <TD>
155 Initialization:
156 <tt>defined_value</tt> is initialized by
157 <tt>init_tokens</tt>. </TD></TR>
158 </TABLE>
159 <P>
160
161 <H3> <tt>if_clause</tt> </H3>
162 <TABLE>
163 <TR> <TH VALIGN=top> Type: </TH><TD><tt>int</tt> </TD></TR>
164
165 <TR> <TH VALIGN=top> Purpose: </TH>
166 <TD>
167 This variable holds a switch which, when set, tells the
168 macro/argument substitution processor it is expanding the
169 conditional for a <tt>#if</tt> statement. It should be zero
170 otherwise. </TD></TR>
171 </TABLE>
172 <P>
173
174 <H3> <tt>macro</tt> </H3>
175 <TABLE>
176 <TR> <TH VALIGN=top> Type: </TH><TD><tt>macro_descriptor[]</tt> </TD></TR>
177
178 <TR> <TH VALIGN=top> Purpose: </TH>
179 <TD>
180 This array is the repository for all macro definitions.
181 Each element describes one macro. The description includes
182 the index of the macro's name in the token dictionary, so
183 that when a macro becomes undefined the slot it used can
184 be recaptured and the reference linkages can be correctly
185 updated. The index into the macro table is usually called
186 the <i>macro id</i>. </TD></TR>
187 <TR> <TH VALIGN=top> Size: </TH>
188 <TD>
189 The size of the array is determined by the <tt>N_MACROS</tt>
190 definition in <tt>mpp.h</tt>. </TD></TR>
191 </TABLE>
192 <P>
193
194 <H3> <tt>macro_id</tt> </H3>
195 <TABLE>
196 <TR> <TH VALIGN=top> Type: </TH><TD><tt>unsigned[]</tt> </TD></TR>
197
198 <TR> <TH VALIGN=top> Purpose: </TH>
199 <TD>
200 This array is indexed by index in the token dictionary. If
201 the item in the token dictionary is a macro name, macro_id
202 will contain the id of the macro, otherwise zero. Thus
203 <tt>macro_id</tt> can be used for a quick test to see if a macro is
204 defined. When a macro is removed with <tt>#undef</tt>, the
205 entry in <tt>macro_id</tt>
206 is reset to zero. </TD></TR>
207 <TR> <TH VALIGN=top> Size: </TH>
208 <TD> The size of the array is determined by the <tt>N_SYMBOLS</tt>
209 definition in <tt>mpp.h</tt>. </TD></TR>
210 </TABLE>
211 <P>
212
213 <H3> <tt>n_macros</tt> </H3>
214 <TABLE>
215 <TR> <TH VALIGN=top> Type: </TH><TD><tt>int</tt> </TD></TR>
216
217 <TR> <TH VALIGN=top> Purpose: </TH>
218 <TD>
219 <tt>n_macros</tt> counts the number of macros which have been
220 defined. It is decremented when a macro becomes undefined.
221 It is also the index of the most recently defined macro in
222 the <tt>macro</tt> array. </TD></TR>
223 </TABLE>
224 <P>
225
226 <H3> <tt>nest_comments</tt> </H3>
227 <TABLE>
228 <TR> <TH VALIGN=top> Type: </TH><TD><tt>int</tt> </TD></TR>
229
230 <TR> <TH VALIGN=top> Purpose: </TH>
231 <TD>
232 <tt>nest_comments</tt> is a switch initialized to zero. When set to
233 a nonzero value, by means of a command line switch, the
234 token scanner will allow nested comments. </TD></TR>
235 </TABLE>
236 <P>
237
238 <H3> <tt>one_value</tt> </H3>
239 <TABLE>
240 <TR> <TH VALIGN=top> Type: </TH><TD><tt>unsigned</tt> </TD></TR>
241
242 <TR> <TH VALIGN=top> Purpose: </TH>
243 <TD>
244 This variable is initialized to hold the token dictionary
245 index of the string "1". It is used to return true values
246 for the <tt>defined()</tt> function when expanding
247 <tt>#if</tt> conditions. </TD></TR>
248 </TABLE>
249 <P>
250
251 <H3> <tt>ops</tt> </H3>
252 <TABLE>
253 <TR> <TH VALIGN=top> Type: </TH><TD> <tt>op_descriptor[]</tt> </TD></TR>
254
255 <TR> <TH VALIGN=top> Purpose: </TH>
256 <TD>
257 This array is used only for initializing the <tt>token_vals</tt>
258 array. It lists all of the multi-character punctuation
259 characters and their token ids. </TD></TR>
260 </TABLE>
261 <P>
262
263 <H3> <tt>paths</tt> </H3>
264 <TABLE>
265 <TR> <TH VALIGN=top> Type: </TH><TD> <tt>stack&lt;char *&gt;</tt></TD></TR>
266
267 <TR> <TH VALIGN=top> Purpose: </TH>
268 <TD>
269 This stack contains all of the individual directory paths
270 specified in the <tt>default_path</tt> constant and by the command
271 line switch. When an include file is specified using &lt;&gt;,
272 the paths are searched for a directory containing the
273 file. Paths are pushed onto the stack in the following
274 order: Those in the <tt>default_path</tt> list, starting from the
275 right, then those specified by the command line switch,
276 starting from the right, and finally the current
277 directory. The search goes from the top down, starting
278 with the current directory and ending with the last
279 directory in the <tt>default_path</tt> list. </TD></TR>
280 </TABLE>
281 <P>
282
283 <H3> <tt>reserved_words</tt> </H3>
284 <TABLE>
285 <TR> <TH VALIGN=top> Type: </TH><TD><tt>op_descriptor[]</tt> </TD></TR>
286
287 <TR> <TH VALIGN=top> Purpose: </TH>
288 <TD>
289 This array lists all of the reserved words recognized by
290 an ANSI C compiler. It is used to initialize the
291 <tt>token_vals</tt> array, and also by the token scanner to
292 distinguish identifiers from reserved words. </TD></TR>
293 </TABLE>
294 <P>
295
296 <H3> <tt>sa</tt> </H3>
297 <TABLE>
298 <TR> <TH VALIGN=top> Type: </TH><TD> <tt>string_accumulator</tt></TD></TR>
299
300 <TR> <TH VALIGN=top> Purpose: </TH>
301 <TD>
302 The string accumulator is the principal working
303 storage for accumulating token strings, character
304 constants, string literals, and so forth. </TD></TR>
305 </TABLE>
306 <P>
307
308 <H3> <tt>scanner_sink</tt> </H3>
309 <TABLE>
310 <TR> <TH VALIGN=top> Type: </TH><TD> <tt>token_sink</tt> </TD></TR>
311
312 <TR> <TH VALIGN=top> Purpose: </TH>
313 <TD>
314 The <tt>scanner_sink</tt> points to the active output destination
315 for the token scanner. When the macro preprocessor
316 initializes itself, scanner_sink is set up to point to
317 <tt>stdout</tt>, a file, or the C parser, depending on the
318 command line. During parsing, the value of <tt>scanner_sink</tt>
319 from time to time is temporarily changed.
320 <P>
321 For macro definitions, it is set to point to the token
322 accumulator to capture the body of macro definitions and
323 macro arguments. For conditional expressions,
324 scanner_sink is set to point to the <tt>expression_evaluator</tt>.
325 For <tt>#include</tt> file names, <tt>scanner_sink</tt> is
326 set to the token accumulator.
327 <P>
328 In all cases, once the need for the temporary diversion is
329 over, <tt>scanner_sink</tt> is restored so that output continues to
330 flow to the correct destination. </TD></TR>
331 </TABLE>
332 <P>
333
334 <H3> <tt>ta</tt> </H3>
335 <TABLE>
336 <TR> <TH VALIGN=top> Type: </TH><TD><tt>token_accumulator</tt> </TD></TR>
337
338 <TR> <TH VALIGN=top> Purpose: </TH>
339 <TD>
340 The token accumulator is the principal working storage for
341 accumulating macro bodies, argument strings, and for
342 returning expanded strings from the macro/argument
343 substitution procedure. </TD></TR>
344 </TABLE>
345 <P>
346
347 <H3> <tt>td</tt> </H3>
348 <TABLE>
349 <TR> <TH VALIGN=top> Type: </TH><TD><tt>string_dictionary</tt> </TD></TR>
350
351 <TR> <TH VALIGN=top> Purpose: </TH>
352 <TD>
353 All distinct input tokens (in the K &amp; R sense) are
354 entered in the token dictionary, <tt>td</tt>, so that they can be
355 subsequently referred to by using a dictionary index. <tt>td</tt>
356 contains numbers, constants, and strings as well as
357 variable names, operators and reserved words. It contains
358 everything in the input. </TD></TR>
359 </TABLE>
360 <P>
361
362 <H3> <tt>token_vals</tt> </H3>
363 <TABLE>
364 <TR> <TH VALIGN=top> Type: </TH><TD><tt>unsigned[256]</tt> </TD></TR>
365
366 <TR> <TH VALIGN=top> Purpose: </TH>
367 <TD>
368 token_vals holds the token_dictionary indices for all pre-
369 defined tokens: reserved words, operators, and
370 punctuation. These values are used in the token scanner to
371 create appropriate tokens as necessary. </TD></TR>
372 </TABLE>
373 <P>
374
375 <H3> <tt>zero_value</tt> </H3>
376 <TABLE>
377 <TR> <TH VALIGN=top> Type: </TH><TD><tt>unsigned</tt> </TD></TR>
378
379 <TR> <TH VALIGN=top> Purpose: </TH>
380 <TD>
381 This variable is initialized to hold the token dictionary
382 index of the string "0". It is used to return false values
383 for the <tt>defined()</tt> function when expanding <tt>#if</tt>
384 conditions. </TD></TR>
385 </TABLE>
386
387 <P>
388
389 <BR>
390
391 <IMG ALIGN="bottom" SRC="../../images/rbline6j.gif" ALT="----------------------"
392 WIDTH=1010 HEIGHT=2 >
393 <P>
394 <IMG ALIGN="right" SRC="../../images/pslrb6d.gif" ALT="Parsifal Software"
395 WIDTH=181 HEIGHT=25>
396 <BR CLEAR="right">
397
398 <P>
399 Back to :
400 <A HREF="../../index.html">Index</A> |
401 <A HREF="index.html">Macro preprocessor overview</A>
402
403 <P>
404
405 <ADDRESS><FONT SIZE="-1">
406 AnaGram parser generator - examples<BR>
407 Main Program - Macro preprocessor and C Parser <BR>
408 Copyright &copy; 1993-1999, Parsifal Software. <BR>
409 All Rights Reserved.<BR>
410 </FONT></ADDRESS>
411
412 </BODY>
413 </HTML>