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

comparison doc/misc/html/start.html @ 0:13d2b8934445

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import AnaGram (near-)release tree into Mercurial.
author David A. Holland
date Sat, 22 Dec 2007 17:52:45 -0500
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:13d2b8934445
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <HTML>
3 <HEAD>
4 <TITLE>Getting Started with AnaGram</TITLE>
5 </HEAD>
6
7 <BODY BGCOLOR="#ffffff" BACKGROUND="tilbl6h.gif"
8 TEXT="#000000" LINK="#0033CC"
9 VLINK="#CC0033" ALINK="#CC0099">
10
11 <P>
12
13 <IMG ALIGN="right" SRC="images/agrsl6c.gif" ALT="AnaGram"
14 WIDTH=124 HEIGHT=30>
15 <BR CLEAR="all">
16 Back to <A HREF="index.html">Index</A>
17 <P>
18 <IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------"
19 WIDTH=1010 HEIGHT=2 >
20
21 <BR CLEAR="all">
22
23
24 <H1>Getting Started with AnaGram</H1>
25 <IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------"
26 WIDTH=1010 HEIGHT=2 >
27 <P>
28
29 <A HREF = "#RunningAnaGram">Running AnaGram</A><BR>
30 <A HREF = "#AnaGramHelp">AnaGram Help</A><BR>
31 <A HREF = "#AnaGramWorks">How Anagram Works</A><BR>
32 <A HREF = "#ProgDevelop">Program Development with AnaGram</A><BR>
33 <A HREF = "#AnaGramExample">An AnaGram Example</A><BR>
34 <A HREF = "#OtherExamples">Other AnaGram Examples</A><BR>
35 <P>
36 <BR>
37
38 <H2><A NAME="RunningAnaGram">Running AnaGram</A></H2>
39 <P>There are two AnaGram executables: ag.exe is the graphical version; agcl.exe
40 is a command line version, suitable for use in make files. If you provide
41 a file name on the command line when you invoke ag.exe, it will load and
42 analyze the file. If the Autobuild switch on the Options menu has been
43 set AnaGram will also build a parser.
44 <P>
45 The command line version can accept any number of syntax files on the
46 command line. It will attempt to build a parser for each in turn. If it
47 fails it will return a non-zero value and will ignore any remaining
48 command line arguments.
49 <P>
50 <BR>
51
52 <H2><A NAME="AnaGramHelp">AnaGram Help</A></H2>
53 AnaGram has an online hypertext help system, with a Help Cursor, F1 help,
54 flyover help, and a Help Topics window. Online Help windows stay on-screen
55 until you dismiss them, so you can view any number at the same time.
56 Right-clicking on an Online Help window brings up a popup menu of all
57 linked topics in the window. For details, select Using Help from the Help menu
58 of the Control Panel.
59 <P>
60 AnaGram's documentation in HTML format, part of which you are currently
61 reading, is indexed in <A HREF="index.html">index.html</A>. It covers
62 Getting Started, examples, and some further topics mainly condensed from
63 the User's Guide.
64 <P>
65 The <A HREF=../usersguide.pdf>AnaGram User's Guide</A> provides the
66 most detail, and could, if desired, be printed and bound.
67 <P>
68 <BR>
69
70 <H2><A NAME="AnaGramWorks">How AnaGram Works</A></H2>
71 AnaGram contains an LALR-1 parser generator which creates a
72 table driven <A HREF="gloss.html#Parser"> parser</A> from a
73 <A HREF="gloss.html#Grammar"> grammar</A> written in a variant of
74 Backus-Naur form. AnaGram works in two steps. In the first step,
75 or analysis phase, it reads a <em>syntax
76 file</em> and compiles a number of tables describing the grammar. In
77 the second step, or build phase, it writes two output files: a
78 <em>parser file</em>, written in C or C++, and a header file.
79
80 <p>
81 The header file contains definitions and declarations. The parser file
82 consists of:
83 <UL>
84 <LI>The <em>C prologue</em>, if any.</LI>
85 <LI>Definitions and declarations provided by AnaGram.</LI>
86 <LI><A HREF="gloss.html#ReductionProcedure"> Reduction
87 procedures</A>.</LI>
88 <LI>A customized <A HREF="gloss.html#ParsingEngine"> parsing
89 engine</A>.</LI>
90 </UL>
91 <P> The name of the parser file is controlled
92 by the <b> parser file name</b> parameter. The name of the parser
93 itself, that is, the C symbol within the program, is controlled by
94 <b>parser name</b>. In the default case, the
95 parser file will have the same name as the syntax file, with the
96 extension <tt>.c</tt>. The name of the parser will be the same as the name of
97 the syntax file, except that it will be entirely lower case.
98 <p>
99 Syntax files normally have the extension <tt>.syn</tt>. The rules for
100 writing syntax files are given in the AnaGram User's Guide and in
101 appropriate help windows in AnaGram. A summary of the rules is
102 given in <A HREF="summary.html">Summary of AnaGram Notation</A>. As with
103 all programming languages, it is easiest to
104 learn the basics of AnaGram from examples.
105 <P>
106 <BR>
107
108 <H2><A NAME="ProgDevelop">Program Development with AnaGram</A></H2>
109 The first step in writing a program is to write a grammar in
110 AnaGram notation which describes the input the program expects.<p>
111 The file containing the grammar, called the <em>syntax file</em>, should have
112 the extension <tt>.syn</tt>. You could also make up a few sample input
113 files at this time, but it is not necessary to write
114 <A HREF="gloss.html#ReductionProcedure"> reduction
115 procedures</A> at this stage.
116 <p>
117 Run AnaGram and use the <em>Analyze Grammar</em> command to
118 create parse tables. If there are syntax errors in the grammar at this
119 point, you will have to correct them before proceeding, but you do
120 not necessarily have to eliminate conflicts, if there are any, at this
121 time. There are, however, many aids available to help you with
122 conflicts. These aids are described in the AnaGram User's Guide,
123 and somewhat more briefly in the Online Help topics.
124 <p>
125 Once syntax errors are corrected, you can try out your grammar
126 on the sample input files using the <A HREF="ftrace.html">
127 File Trace</A> facility described below. With File Trace, you can see
128 interactively just how your grammar operates on your test files. You
129 can also use <A HREF="gtrace.html"> GrammarTrace</A> to
130 answer "what if" questions concerning input to the grammar. The
131 Grammar Trace does not use a test file, but rather allows you to make
132 input choices interactively.
133 <p>
134 At any time, you can write
135 <A HREF="gloss.html#ReductionProcedure">
136 reduction procedures</A> to process your input data as its components
137 are identified in the input stream. Each procedure is associated
138 with a <A HREF="gloss.html#GrammarRule"> grammar rule</A>. The
139 reduction procedures will be incorporated into your parser when you
140 create it with the <em>Build Parser</em> command.
141
142 <P>
143 By default, unless you specify an input procedure, your parser will read
144 input from <tt>stdin</tt>, using the default <tt>GET_INPUT</tt> macro. You will
145 probably wish to redefine <tt>GET_INPUT</tt>, or configure your parser to use
146 <B>pointer input</B> or <B>event driven</B> input.
147 <P> <BR>
148
149 <H2><A NAME="AnaGramExample">An AnaGram Example: <tt>ffcalc.syn</tt></A></H2>
150 <p>
151 To give you a quick introduction to AnaGram notation, a simple,
152 but complete, AnaGram program called <tt>ffcalc.syn</tt> is provided
153 in <A HREF="examples/ffcex.html">annotated form</A>. This program may
154 also be found
155 in <tt>examples/ffcalc</tt> in your AnaGram distribution.
156 <p>
157 <tt>ffcalc.syn</tt> implements a simple four function calculator.
158 The calculator has 52 registers, labeled `a' through `z' and `A'
159 through `Z'. <tt>ffcalc</tt> evaluates arithmetic expressions and
160 assignment statements and prints the results. The expressions may
161 contain `+', `-', `*', and `/' operators as well as parentheses. In
162 addition, <tt>ffcalc</tt> supports the free use of white space and C style
163 comments in the input. It also contains complete error handling,
164 including syntax error diagnostics, and
165 <A HREF="gloss.html#Resynchronization"> resynchronization</A>.<p>
166 <P>
167 <BR>
168
169 <H2><A NAME="OtherExamples">Other AnaGram Examples</A></H2>
170
171 A number of other <A HREF="examples/index.html">examples</A>, ranging from
172 nearly trivial to quite complex, have been provided on the AnaGram
173 distribution disk in the <tt>examples</tt> directory. All of the examples are
174 complete programs which you may build, compile and run.
175
176 <p>
177 At the
178 most elementary level, there are example files for Hello, World! (<tt>hw</tt>)
179 and Fahrenheit/Celsius Conversion (<tt>fc</tt>). The documentation files for
180 these examples are essentially tutorials in the use of AnaGram. A
181 good way to familiarize yourself with AnaGram, therefore, is to try
182 out these examples.
183
184 <p>
185 You could also try building a <A
186 HREF="gloss.html#Parser">parser</A> from <tt>ffcalc.syn</tt>. Compile and link
187 it using your C compiler. Then try running it. Since it uses default
188 input options which read <tt>stdin</tt> you can either type input
189 directly, redirect input from one of the test files provided, or
190 create your own test file.
191
192 <p>
193 At the more advanced level, there is
194 a complete, functional C macro preprocessor (<tt>mpp</tt>) with your choice of
195 two C grammars. There is also a moderately complex scripting
196 language (<tt>dsl</tt>) which provides the functionality of DOS batch files
197 combined with standard programming constructs such as if statements
198 and while statements. <tt>dsl</tt> also contains capability for describing
199 data acquisition screens.
200
201 <p>
202 For each example there is a
203 subdirectory containing all of the source files necessary for the
204 example as well as a documentation file explaining the example.
205
206 <p>
207 A number of the examples have been written using C++. Some of these
208 use class definitions which are found in the
209 <A HREF="oldclasslib/index.html">oldclasslib</A>
210 directory.
211 </p>
212 <BR>
213
214 <IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------"
215 WIDTH=1010 HEIGHT=2 >
216 <P>
217 <IMG ALIGN="right" SRC="images/pslrb6d.gif" ALT="Parsifal Software"
218 WIDTH=181 HEIGHT=25>
219 <BR CLEAR="right">
220 <P>
221
222 <A HREF="index.html">Back to Index</A>
223 <P>
224 <ADDRESS><FONT SIZE="-1">
225 AnaGram parser generator - documentation<BR>
226 Getting Started With AnaGram<BR>
227 Copyright &copy; 1993-1999, Parsifal Software. <BR>
228 All Rights Reserved.<BR>
229 </FONT></ADDRESS>
230
231 </BODY>
232 </HTML>