Mercurial > ~dholland > hg > ag > index.cgi
view 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 source
<!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>