Mercurial > ~dholland > hg > ag > index.cgi
diff doc/misc/html/start.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/start.html Sat Dec 22 17:52:45 2007 -0500 @@ -0,0 +1,232 @@ +<!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 © 1993-1999, Parsifal Software. <BR> + All Rights Reserved.<BR> +</FONT></ADDRESS> + +</BODY> +</HTML>