Mercurial > ~dholland > hg > ag > index.cgi
diff doc/misc/html/examples/mpp/mpp.html @ 0:13d2b8934445
Import AnaGram (near-)release tree into Mercurial.
| author | David A. Holland |
|---|---|
| date | Sat, 22 Dec 2007 17:52:45 -0500 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/misc/html/examples/mpp/mpp.html Sat Dec 22 17:52:45 2007 -0500 @@ -0,0 +1,413 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> +<HEAD> +<TITLE> Main Program - Macro preprocessor and C Parser </TITLE> +</HEAD> + + +<BODY BGCOLOR="#ffffff" BACKGROUND="tilbl6h.gif" + TEXT="#000000" LINK="#0033CC" + VLINK="#CC0033" ALINK="#CC0099"> + +<P> +<IMG ALIGN="right" SRC="../../images/agrsl6c.gif" ALT="AnaGram" + WIDTH=124 HEIGHT=30 > +<BR CLEAR="all"> +Back to : +<A HREF="../../index.html">Index</A> | +<A HREF="index.html">Macro preprocessor overview</A> +<P> +<IMG ALIGN="bottom" SRC="../../images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > +<P> + +<H1> Main Program - Macro preprocessor and C Parser </H1> + +<IMG ALIGN="bottom" SRC="../../images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > +<P> +<BR> + +<H2>Introduction</H2> +<P> + <tt>mpp.h</tt> contains type definitions, external definitions and + function declarations for the macro preprocessor. <tt>mpp.cpp</tt> + contains all global data definitions and the main program. + +<P> +<BR> + +<H2> Type Definitions </H2> +<DL> +<DT> <tt>macro_descriptor</tt> + + <DD> This structure contains a complete description of a macro. + The name index allows the linkage between the token + dictionary and the macro table to be modified when a macro + is undefined so that the macro table can be maintained in a + compact form. + + +<DT> <tt>op_descriptor</tt> + + <DD> This structure is used only for initializing tables in + <tt>mpp.cpp</tt>. +</DL> +<P> +<BR> + +<H2> Parser Class Definitions </H2> +<DL> +<DT> <tt>expression_evaluator</tt> + + <DD> This class definition serves as an interface to the + constant expression evaluation logic in <tt>ex.syn</tt>, where the + member functions are defined. It is derived from the + token_sink class. In <tt>ts.syn</tt>, + <tt>init_condition</tt> redirects scanner + output temporarily to the expression evaluator. + +<DT> <tt>c_parser</tt> + + <DD> This class definition serves as an interface to the c parser + in <tt>jrc.syn</tt> or <tt>krc.syn</tt>, where the member + functions are defined. The + <tt>c_parser</tt> class is derived from the + <tt>token_sink</tt> class. The + main program uses this capability to determine the + destination of tokens output by the token scanner. If the + user requests C parsing, the <tt>token_sink</tt> pointer + <tt>scanner_sink</tt> + is loaded with a pointer to an instance of <tt>c_parser</tt>. + Otherwise <tt>scanner_sink</tt> is loaded with a pointer to a + <tt>token_translator</tt>. +</DL> +<P> +<BR> + +<H2> Global Variables </H2> + +<H3> <tt>condition</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>expression_evaluator</tt></TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> This class encapsulates the logic for evaluating constant + expressions found in #if statements. </TD> </TR> +<TR> <TH VALIGN=top> Usage: </TH> <TD> + <TABLE> + <TR><TD VALIGN=top><tt>reset(condition);</tt></TD> + <TD WIDTH=5%> </TD> + <TD>prepares for a new expression</TD></TR> + + <TR><TD VALIGN=top><tt>condition << </tt><i>token + string,/i><tt>;</tt></TD> + <TD WIDTH=5%> </TD> + <TD>offers a token string for evaluation</TD></TR> + + <TR><TD VALIGN=top><tt>long result = condition;</tt></TD> + <TD WIDTH=5%> </TD> + <TD>retrieves value of expression</TD></TR> + </TABLE> + </TD></TR> +<TR> <TH VALIGN=top> Precautions: </TH> + <TD> The input token string must not be on the token + accumulator. If it was developed on the token + accumulator, it should be popped off before being handed + to <tt>condition</tt>. </TD> </TR> + +<TR> <TH VALIGN=top> Notes: </TH> + <TD> This is the only instance of an + <tt>expression_evaluator</tt> in the program. Member + functions are implemented in <tt>ex.syn</tt>. </TD> </TR> +</TABLE> +<P> + +<H3> <tt>default_path</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>char[]</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + This character array contains the default paths for + include files. If more than one directory is specified, + use a '<CODE>;</CODE>' just as with the DOS PATH command. + <P> + More paths can be provided using the command line -i + switch. Note that directories are searched in order + beginning with those specified in the command line. </TD></TR> +</TABLE> +<P> + +<H3> <tt>defined_value</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>unsigned</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + This variable holds the token dictionary index for the + (sometimes) keyword "defined". "defined" is recognized + only when evaluating the conditional expressions in <tt>#if</tt> + statements. </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + Initialization: + <tt>defined_value</tt> is initialized by + <tt>init_tokens</tt>. </TD></TR> +</TABLE> +<P> + +<H3> <tt>if_clause</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>int</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + This variable holds a switch which, when set, tells the + macro/argument substitution processor it is expanding the + conditional for a <tt>#if</tt> statement. It should be zero + otherwise. </TD></TR> +</TABLE> +<P> + +<H3> <tt>macro</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>macro_descriptor[]</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + This array is the repository for all macro definitions. + Each element describes one macro. The description includes + the index of the macro's name in the token dictionary, so + that when a macro becomes undefined the slot it used can + be recaptured and the reference linkages can be correctly + updated. The index into the macro table is usually called + the <i>macro id</i>. </TD></TR> +<TR> <TH VALIGN=top> Size: </TH> + <TD> + The size of the array is determined by the <tt>N_MACROS</tt> + definition in <tt>mpp.h</tt>. </TD></TR> +</TABLE> +<P> + +<H3> <tt>macro_id</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>unsigned[]</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + This array is indexed by index in the token dictionary. If + the item in the token dictionary is a macro name, macro_id + will contain the id of the macro, otherwise zero. Thus + <tt>macro_id</tt> can be used for a quick test to see if a macro is + defined. When a macro is removed with <tt>#undef</tt>, the + entry in <tt>macro_id</tt> + is reset to zero. </TD></TR> +<TR> <TH VALIGN=top> Size: </TH> + <TD> The size of the array is determined by the <tt>N_SYMBOLS</tt> + definition in <tt>mpp.h</tt>. </TD></TR> +</TABLE> +<P> + +<H3> <tt>n_macros</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>int</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + <tt>n_macros</tt> counts the number of macros which have been + defined. It is decremented when a macro becomes undefined. + It is also the index of the most recently defined macro in + the <tt>macro</tt> array. </TD></TR> +</TABLE> +<P> + +<H3> <tt>nest_comments</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>int</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + <tt>nest_comments</tt> is a switch initialized to zero. When set to + a nonzero value, by means of a command line switch, the + token scanner will allow nested comments. </TD></TR> +</TABLE> +<P> + +<H3> <tt>one_value</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>unsigned</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + This variable is initialized to hold the token dictionary + index of the string "1". It is used to return true values + for the <tt>defined()</tt> function when expanding + <tt>#if</tt> conditions. </TD></TR> +</TABLE> +<P> + +<H3> <tt>ops</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD> <tt>op_descriptor[]</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + This array is used only for initializing the <tt>token_vals</tt> + array. It lists all of the multi-character punctuation + characters and their token ids. </TD></TR> +</TABLE> +<P> + +<H3> <tt>paths</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD> <tt>stack<char *></tt></TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + This stack contains all of the individual directory paths + specified in the <tt>default_path</tt> constant and by the command + line switch. When an include file is specified using <>, + the paths are searched for a directory containing the + file. Paths are pushed onto the stack in the following + order: Those in the <tt>default_path</tt> list, starting from the + right, then those specified by the command line switch, + starting from the right, and finally the current + directory. The search goes from the top down, starting + with the current directory and ending with the last + directory in the <tt>default_path</tt> list. </TD></TR> +</TABLE> +<P> + +<H3> <tt>reserved_words</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>op_descriptor[]</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + This array lists all of the reserved words recognized by + an ANSI C compiler. It is used to initialize the + <tt>token_vals</tt> array, and also by the token scanner to + distinguish identifiers from reserved words. </TD></TR> +</TABLE> +<P> + +<H3> <tt>sa</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD> <tt>string_accumulator</tt></TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + The string accumulator is the principal working + storage for accumulating token strings, character + constants, string literals, and so forth. </TD></TR> +</TABLE> +<P> + +<H3> <tt>scanner_sink</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD> <tt>token_sink</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + The <tt>scanner_sink</tt> points to the active output destination + for the token scanner. When the macro preprocessor + initializes itself, scanner_sink is set up to point to + <tt>stdout</tt>, a file, or the C parser, depending on the + command line. During parsing, the value of <tt>scanner_sink</tt> + from time to time is temporarily changed. +<P> + For macro definitions, it is set to point to the token + accumulator to capture the body of macro definitions and + macro arguments. For conditional expressions, + scanner_sink is set to point to the <tt>expression_evaluator</tt>. + For <tt>#include</tt> file names, <tt>scanner_sink</tt> is + set to the token accumulator. +<P> + In all cases, once the need for the temporary diversion is + over, <tt>scanner_sink</tt> is restored so that output continues to + flow to the correct destination. </TD></TR> +</TABLE> +<P> + +<H3> <tt>ta</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>token_accumulator</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + The token accumulator is the principal working storage for + accumulating macro bodies, argument strings, and for + returning expanded strings from the macro/argument + substitution procedure. </TD></TR> +</TABLE> +<P> + +<H3> <tt>td</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>string_dictionary</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + All distinct input tokens (in the K & R sense) are + entered in the token dictionary, <tt>td</tt>, so that they can be + subsequently referred to by using a dictionary index. <tt>td</tt> + contains numbers, constants, and strings as well as + variable names, operators and reserved words. It contains + everything in the input. </TD></TR> +</TABLE> +<P> + +<H3> <tt>token_vals</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>unsigned[256]</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + token_vals holds the token_dictionary indices for all pre- + defined tokens: reserved words, operators, and + punctuation. These values are used in the token scanner to + create appropriate tokens as necessary. </TD></TR> +</TABLE> +<P> + +<H3> <tt>zero_value</tt> </H3> +<TABLE> +<TR> <TH VALIGN=top> Type: </TH><TD><tt>unsigned</tt> </TD></TR> + +<TR> <TH VALIGN=top> Purpose: </TH> + <TD> + This variable is initialized to hold the token dictionary + index of the string "0". It is used to return false values + for the <tt>defined()</tt> function when expanding <tt>#if</tt> + conditions. </TD></TR> +</TABLE> + +<P> + +<BR> + +<IMG ALIGN="bottom" SRC="../../images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > +<P> +<IMG ALIGN="right" SRC="../../images/pslrb6d.gif" ALT="Parsifal Software" + WIDTH=181 HEIGHT=25> +<BR CLEAR="right"> + +<P> +Back to : +<A HREF="../../index.html">Index</A> | +<A HREF="index.html">Macro preprocessor overview</A> + +<P> + +<ADDRESS><FONT SIZE="-1"> + AnaGram parser generator - examples<BR> + Main Program - Macro preprocessor and C Parser <BR> + Copyright © 1993-1999, Parsifal Software. <BR> + All Rights Reserved.<BR> +</FONT></ADDRESS> + +</BODY> +</HTML>