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

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>Getting Started with AnaGram</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>
<P>
<IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------"
        WIDTH=1010 HEIGHT=2  >

<BR CLEAR="all">


<H1>Getting Started with AnaGram</H1>
<IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------"
        WIDTH=1010 HEIGHT=2  >
<P>

<A HREF = "#RunningAnaGram">Running AnaGram</A><BR>
<A HREF = "#AnaGramHelp">AnaGram Help</A><BR>
<A HREF = "#AnaGramWorks">How Anagram Works</A><BR>
<A HREF = "#ProgDevelop">Program Development with AnaGram</A><BR>
<A HREF = "#AnaGramExample">An AnaGram Example</A><BR>
<A HREF = "#OtherExamples">Other AnaGram Examples</A><BR>
<P>
<BR>

<H2><A NAME="RunningAnaGram">Running AnaGram</A></H2>
<P>There are two AnaGram executables: ag.exe is the graphical version; agcl.exe
is a command line version, suitable for use in make files. If you provide
a file name on the command line when you invoke ag.exe, it will load and
analyze the file. If the Autobuild switch on the Options menu has been
set AnaGram will also build a parser.
<P>
 The command line version can accept any number of syntax files on the
 command line. It will attempt to build a parser for each in turn. If it
 fails it will return a non-zero value and will ignore any remaining
 command line arguments.
<P>
<BR>

<H2><A NAME="AnaGramHelp">AnaGram Help</A></H2>
AnaGram has an online hypertext help system, with a Help Cursor, F1 help,
flyover help, and a Help Topics window. Online Help windows stay on-screen
until you dismiss them, so you can view any number at the same time.
Right-clicking on an Online Help window brings up a popup menu of all
linked topics in the window. For details, select Using Help from the Help menu
of the Control Panel.
<P>
AnaGram's documentation in HTML format, part of which you are currently
reading, is indexed in <A HREF="index.html">index.html</A>. It covers
Getting Started, examples, and some further topics mainly condensed from
the User's Guide.
<P>
The <A HREF=../usersguide.pdf>AnaGram User's Guide</A> provides the
most detail, and could, if desired, be printed and bound.
<P>
<BR>

<H2><A NAME="AnaGramWorks">How AnaGram Works</A></H2>
AnaGram contains an LALR-1 parser generator which creates a
table driven <A HREF="gloss.html#Parser"> parser</A> from a
<A HREF="gloss.html#Grammar"> grammar</A> written in a variant of
Backus-Naur form. AnaGram works in two steps. In the first step,
or analysis phase, it reads a <em>syntax
file</em> and compiles a number of tables describing the grammar. In
the second step, or build phase, it writes two output files: a
<em>parser file</em>, written in C or C++, and a header file.

<p>
The header file contains definitions and declarations. The parser file
consists of:
<UL>
  <LI>The <em>C prologue</em>, if any.</LI>
  <LI>Definitions and declarations provided by AnaGram.</LI>
  <LI><A HREF="gloss.html#ReductionProcedure"> Reduction
  procedures</A>.</LI>
  <LI>A customized <A HREF="gloss.html#ParsingEngine"> parsing
engine</A>.</LI>
</UL>
<P> The name of the parser file is controlled
by the <b> parser file name</b> parameter. The name of the parser
itself, that is, the C symbol within the program, is controlled by
<b>parser name</b>. In the default case, the
parser file will have the same name as the syntax file, with the
extension <tt>.c</tt>. The name of the parser will be the same as the name of
the syntax file, except that it will be entirely lower case.
<p>
Syntax files normally have the extension <tt>.syn</tt>. The rules for
writing syntax files are given in the AnaGram User's Guide and in
appropriate help windows in AnaGram. A summary of the rules is
given in <A HREF="summary.html">Summary of AnaGram Notation</A>. As with
all programming languages, it is easiest to
learn the basics of AnaGram from examples.
<P>
<BR>

<H2><A NAME="ProgDevelop">Program Development with AnaGram</A></H2>
The first step in writing a program is to write a grammar in
AnaGram notation which describes the input the program expects.<p>
The file containing the grammar, called the <em>syntax file</em>, should have
the extension <tt>.syn</tt>. You could also make up a few sample input
files at this time, but it is not necessary to write
<A HREF="gloss.html#ReductionProcedure"> reduction
procedures</A> at this stage.
<p>
Run AnaGram and use the <em>Analyze Grammar</em> command to
create parse tables. If there are syntax errors in the grammar at this
point, you will have to correct them before proceeding, but you do
not necessarily have to eliminate conflicts, if there are any, at this
time. There are, however, many aids available to help you with
conflicts. These aids are described in the AnaGram User's Guide,
and somewhat more briefly in the Online Help topics.
<p>
Once syntax errors are corrected, you can try out your grammar
on the sample input files using the <A HREF="ftrace.html">
File Trace</A> facility described below. With File Trace, you can see
interactively just how your grammar operates on your test files. You
can also use <A HREF="gtrace.html"> GrammarTrace</A> to
answer "what if" questions concerning input to the grammar. The
Grammar Trace does not use a test file, but rather allows you to make
input choices interactively.
<p>
At any time, you can write
<A HREF="gloss.html#ReductionProcedure">
reduction procedures</A> to process your input data as its components
are identified in the input stream.  Each procedure is associated
with a <A HREF="gloss.html#GrammarRule"> grammar rule</A>. The
reduction procedures will be incorporated into your parser when you
create it with the <em>Build Parser</em> command.

<P>
By default, unless you specify an input procedure, your parser will read
input from <tt>stdin</tt>, using the default <tt>GET_INPUT</tt> macro. You will
probably wish to redefine <tt>GET_INPUT</tt>, or configure your parser to use
<B>pointer input</B> or <B>event driven</B> input.
<P> <BR>

<H2><A NAME="AnaGramExample">An AnaGram Example: <tt>ffcalc.syn</tt></A></H2>
<p>
To give you a quick introduction to AnaGram notation, a simple,
but complete, AnaGram program called <tt>ffcalc.syn</tt> is provided
in <A HREF="examples/ffcex.html">annotated form</A>. This program may
also be found
in <tt>examples/ffcalc</tt> in your AnaGram distribution.
<p>
<tt>ffcalc.syn</tt> implements a simple four function calculator.
The calculator has 52 registers, labeled `a' through `z' and `A'
through `Z'. <tt>ffcalc</tt> evaluates arithmetic expressions and
assignment statements and prints the results. The expressions may
contain `+', `-', `*', and `/' operators as well as parentheses. In
addition, <tt>ffcalc</tt> supports the free use of white space and C style
comments in the input. It also contains complete error handling,
including syntax error diagnostics, and
<A HREF="gloss.html#Resynchronization"> resynchronization</A>.<p>
<P>
<BR>

<H2><A NAME="OtherExamples">Other AnaGram Examples</A></H2>

A number of other <A HREF="examples/index.html">examples</A>, ranging from
nearly trivial to quite complex, have been provided on the AnaGram
distribution disk in the <tt>examples</tt> directory. All of the examples are
complete programs which you may build, compile and run.

<p>
At the
most elementary level, there are example files for Hello, World! (<tt>hw</tt>)
and Fahrenheit/Celsius Conversion (<tt>fc</tt>). The documentation files for
these examples are essentially tutorials in the use of AnaGram. A
good way to familiarize yourself with AnaGram, therefore, is to try
out these examples.

<p>
You could also try building a <A
HREF="gloss.html#Parser">parser</A> from <tt>ffcalc.syn</tt>.  Compile and link
it using your C compiler. Then try running it.  Since it uses default
input options which read <tt>stdin</tt> you can either type input
directly, redirect input from one of the test files provided, or
create your own test file.

<p>
At the more advanced level, there is
a complete, functional C macro preprocessor (<tt>mpp</tt>) with your choice of
two C grammars.  There is also a moderately complex scripting
language (<tt>dsl</tt>) which provides the functionality of DOS batch files
combined with standard programming constructs such as if statements
and while statements. <tt>dsl</tt> also contains capability for describing
data acquisition screens.

<p>
For each example there is a
subdirectory containing all of the source files necessary for the
example as well as a documentation file explaining the example.

<p>
A number of the examples have been written using C++. Some of these
use class definitions which are found in the
<A HREF="oldclasslib/index.html">oldclasslib</A>
directory.
</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>

<A HREF="index.html">Back to Index</A>
<P>
<ADDRESS><FONT SIZE="-1">
                  AnaGram parser generator - documentation<BR>
                  Getting Started With AnaGram<BR>
                  Copyright &copy; 1993-1999, Parsifal Software. <BR>
                  All Rights Reserved.<BR>
</FONT></ADDRESS>

</BODY>
</HTML>
author	David A. Holland
date	Mon, 30 May 2022 23:51:43 -0400
parents	13d2b8934445
children