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%>&nbsp;</TD>
                <TD>prepares for a new expression</TD></TR>

                <TR><TD VALIGN=top><tt>condition &lt;&lt; </tt><i>token
                    string,/i><tt>;</tt></TD>
                <TD WIDTH=5%>&nbsp;</TD>
                <TD>offers a token string for evaluation</TD></TR>

                <TR><TD VALIGN=top><tt>long result = condition;</tt></TD>
                <TD WIDTH=5%>&nbsp;</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&lt;char *&gt;</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 &lt;&gt;,
            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 &amp; 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 &copy; 1993-1999, Parsifal Software. <BR>
                  All Rights Reserved.<BR>
</FONT></ADDRESS>

</BODY>
</HTML>