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

comparison doc/manual/gs.tex @ 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 \chapter{Getting Started}
2
3
4 \section{Hardware and Software Requirements}
5 \index{Requirements}
6 \index{Hardware requirements}
7 \index{Software requirements}
8
9 AnaGram V2.0 will run on any Windows 95 or Windows NT system. The
10 installation requires approximately five megabytes of hard disk space.
11
12 The parsers AnaGram generates are either C or C++ program modules, and
13 can be compiled and run using almost any C or C++ compiler, in any
14 operating system environment. If your compiler does not support
15 \agcode{near} and \agcode{far} declarations, or does not support ANSI
16 function declarations, see the descriptions of the
17 \index{Near functions}\agparam{near functions}
18 and
19 \index{Old style}\agparam{old style}
20 \index{Configuration switches}configuration switches in Appendix A.
21
22
23 \section{Installation}
24 \index{Installation}
25
26 For details on installation, please see the \agfile{readme.txt} file
27 on the AnaGram installation disk.
28
29 The AnaGram installation disk contains the AnaGram executables,
30 several support files, an \agfile{html} documentation directory, an
31 \index{\agfile{examples}}\agfile{examples} directory, and a
32 \agfile{classlib} directory. The \agfile{examples} directory
33 contains a number of subdirectories, each of which contains the
34 necessary syntax files and supporting C or C++ code to build and run a
35 different example of the use of AnaGram.
36
37 The HTML documentation directory contains introductory material which can be
38 read on line, as well as documentation for the examples.
39
40 The \index{\agfile{classlib}}\agfile{classlib} directory contains
41 class definitions which support the C++ examples provided. The
42 \agfile{classlib} directory has three subdirectories, which contain
43 header files, source files, and documentation files, respectively.
44
45 % XXX this should be pruned. nobody cares about a minimal installation
46 % when drive space is $0.50 per gigabyte.
47 %
48 % also, I suspect the ``PATH command'' bit needs updating somewhere,
49 % but I'm not sure what right now. (and I'm not doing updates on this
50 % pass through the thing.)
51 %
52 % and, s/make file/makefile/. or say ``with \agfile{make}''.
53 %
54 A minimal AnaGram installation requires files: \agfile{ag.exe},
55 \agfile{ag1.dll}, \agfile{AnaGram.cgb}, and \agfile{AnaGram.hlp}.
56 They must all be in the same directory.
57 \index{PATH command}
58 If any of these files is missing, AnaGram cannot run. If you wish to
59 use the command line version of AnaGram in make files, you also need
60 \agfile{agcl.exe}.
61
62
63 \section{Configuration}
64 \index{Configuration}
65
66 AnaGram has a large number of configuration parameters which control
67 various aspects of its operation. All configuration parameters have
68 default values which are normally acceptable to most beginning users.
69 Configuration parameters can be set either in configuration files,
70 named
71 \index{Configuration file}\index{File}\index{\agfile{AnaGram.cfg}}
72 \agfile{AnaGram.cfg}, or in your syntax files. When AnaGram
73 initializes itself, it checks the AnaGram
74 \index{Directory}\index{AnaGram}directory, the directory that contains
75 the AnaGram executable file. If it finds \agfile{AnaGram.cfg}, it
76 reads it and sets the
77 \index{Configuration parameters}configuration parameters accordingly.
78 It then checks for \agfile{AnaGram.cfg} in your working directory and,
79 if it finds it, reads it in turn, overriding the setting for any
80 parameter which had been set previously. Configuration parameter
81 settings in a syntax file, of course, override any values set in a
82 configuration file.
83
84 The \index{File}configuration files are simple ASCII files so they can
85 be created or modified with any program editor. Neither configuration
86 file is necessary. A complete listing of configuration parameters is
87 given in Appendix A. Specific configuration parameters are discussed
88 in this manual where appropriate.
89
90 \section{Familiarizing Yourself with AnaGram}
91
92 AnaGram has extensive online help, so you should be able to get
93 started without reading much of this manual. Once you have obtained
94 an initial familiarity with AnaGram, you should take another look at
95 the manual since there are a number of features that you may otherwise
96 overlook.
97
98 To help get you started, a number of examples have been provided in
99 the \index{\agfile{examples}}\agfile{examples} directory of the
100 AnaGram distribution disk. These examples range from very elementary
101 to quite complex. The elementary examples are intended to give you a
102 quick understanding of how to use AnaGram. The complex examples are
103 intended to demonstrate the capabilities of AnaGram. All of the
104 examples are complete working programs. Many example grammars are
105 provided with sample input files so you can use AnaGram's \agmenu{File
106 Trace} command to see how the parsing is controlled by the grammar.
107 The \agwindow{File Trace} facility is described in Chapter 5.
108
109 % For some reason I don't understand this paragraph doesn't fold
110 % correctly. (It looks ugly with the explicit break, but it's worse
111 % hanging out into the margin, which is what happens otherwise. XXX)
112 The examples are documented in the HTML documentation directory.
113 Point your web browser at\\
114 \agfile{html/start.html}.
115
116 The best way to learn AnaGram is by using it. Start by looking at the
117 examples provided in the \agfile{examples} directory. Once you have
118 looked over a file to get an idea of what it is about, you should run
119 \agmenu{File Trace} to see how it works. You might then want to build
120 a parser for one of the examples, compile it, and try running it. You
121 can also try modifying the examples before starting to write grammars
122 of your own.
123
124 To investigate a syntax file select the \agmenu{Analyze Grammar}
125 command from the \agmenu{Action} menu. After this command has run you
126 can run the \agwindow{File Trace} or \agwindow{Grammar Trace} to see
127 how the grammar works. You may also look at any of a number of
128 windows listed in the \agmenu{Browse} menu to investigate various
129 aspects of the grammar.
130
131 To build a parser file that you can compile with your C or C++
132 compiler, select the \agmenu{Build Parser} command. If you have
133 already analyzed a grammar, the \agmenu{Build Parser} command will
134 simply build a parser for the grammar you have already analyzed. If
135 you have already built a parser for the grammar you presently have
136 loaded, the \agmenu{Build Parser} command will offer you the option of
137 loading a new file.
138
139 When AnaGram analyzes a grammar, it creates a number of tables.
140 Windows displaying these tables can be opened from the \agmenu{Browse}
141 menu. AnaGram's windows are described in Chapter 3, Running AnaGram.
142
143 \section{Guide to this Manual}
144
145 Chapter 3, \textit{Running AnaGram}, describes AnaGram's on-line
146 features and how to use them.
147
148 Chapter 4, \textit{Introduction to Syntax Directed Parsing}, provides
149 a general introduction to parsing and an introduction to AnaGram
150 syntax files. In particular, it introduces important terminology used
151 throughout the manual.
152
153 Chapter 5, \textit{Exploring Your Grammar I: Trace Functions},
154 explains the usage of the \agwindow{File Trace} and the
155 \agwindow{Grammar Trace} in exploring and understanding your grammar.
156
157 Chapter 6, \textit{Exploring Your Grammar II: Grammar Tables},
158 describes the use of the principal tables AnaGram provides to
159 summarize your grammar.
160
161 Chapter 7, \textit{Exploring Your Grammar III: Diagnostic Windows},
162 describes the use of the tables AnaGram provides to help you
163 investigate error conditions in your grammar.
164
165 Chapter 8, \textit{Syntax Files}, describes the rules for writing
166 syntax files. This chapter is meant to be used largely for reference.
167
168 Chapter 9, \textit{Programming with AnaGram}, describes how you
169 interface a parser to the rest of your program. In particular, it
170 describes your options for naming and calling your parser, providing
171 input, and dealing with errors.
172
173 Appendix A, \textit{Configuration Parameters}, explains how to use
174 configuration files and configuration parameters. It also lists each
175 configuration parameter and explains the options available.
176
177 Appendix B, \textit{Warning Messages}, explains the various warnings
178 AnaGram creates when it finds errors or other anomalies in your syntax
179 file.
180
181 Appendix C, \textit{Alphabetic Listing of Windows}, provides a quick
182 overview of the various windows AnaGram uses to display the results of
183 analyzing a grammar.
184
185 Appendix D, \textit{Syntactic Building Blocks}, provides examples of
186 AnaGram syntax for the most common elements of any grammar: end of
187 file, end of line, comments, numbers, names, quoted strings, character
188 constants and simple expressions.
189
190 Appendix E, \textit{Parser Control Block}, provides a summary of
191 fields in the parser control block which you may need to inspect or
192 use from time to time.
193
194 Appendix F, \textit{Glossary}, explains some of the terminology of
195 syntax directed parsing.
196
197 \section{Examples}
198
199 The \index{\agfile{examples}}\agfile{examples} directory contains a
200 number of examples of programs written using AnaGram. Each example is
201 in a subdirectory by itself. Where necessary, each directory also
202 contains supporting modules in C or C++, depending on the example, to
203 build a complete working program. The C++ examples also use
204 supporting modules found in
205 \index{\agfile{classlib}}\agfile{classlib}. Documentation for the
206 examples may be found in the HTML directory. Begin with
207 \agfile{html/start.html}.
208
209 If you are not already familiar with AnaGram you should take a look at
210 the examples. The purpose of the examples is twofold: to provide a
211 quick introduction to AnaGram, and to suggest methods of using AnaGram
212 to solve problems. The examples are provided as is, with no
213 guarantees of any sort. You may freely copy portions of these
214 examples for your own use. However, in doing so, you assume the
215 responsibility of verifying their performance and reliability.
216
217 The following list gives a brief description of some of the example
218 programs to be found in the \index{\agfile{examples}}\agfile{examples}
219 directory.
220
221 \paragraph{Hello, World!}
222 The \agfile{hw} directory contains two versions of the traditional ``Hello,
223 world!'' One version, \agfile{hw1.syn}, uses C. The other,
224 \agfile{hw2.syn}, uses C++. These programs are utterly trivial, but
225 useful for getting started with the mechanics of using AnaGram. They
226 illustrate AnaGram's default settings using an absolutely minimal
227 grammar.
228
229 \paragraph{Fahrenheit-Celsius Conversion.}
230 The \agfile{fc} directory contains a graded sequence of very simple
231 examples. Each example is a complete working program. These programs
232 introduce a number of the most important features of AnaGram. The
233 documentation is designed to be a tutorial, to lead you into using
234 AnaGram by simple steps. It includes an example of how to find and
235 fix the conflicts in an ambiguous grammar. All of these examples use
236 C.
237
238 \paragraph{Roman Numeral Calculator.}
239 \agfile{rcalc.syn} is a simple four function desk calculator
240 that takes its input and displays its output using Roman numerals.
241 \agfile{rcalc} uses C.
242
243 \paragraph{Four Function Calculator.}
244 \agfile{ffcalc} is intended to provide an example of how
245 to parse simple expressions. A companion program, \agfile{ffcalcx},
246 demonstrates the use of precedence statements to resolve a
247 deliberately ambiguous grammar.
248
249 \paragraph{DOS Script Language.}
250 \agfile{dsl.syn} is meant more as an illustration of what can be
251 done with AnaGram than as an ideal design of a script language. In
252 particular, \agfile{dsl} is largely composed of grammar elements
253 copied from other programs. \agfile{dsl} uses C++.
254
255 %
256 %\paragraph{Spreadsheet Formula Evaluators.}
257 %This is a collection of grammars which you
258 %can use to replace the formula evaluation in the TCALC spreadsheet
259 %distributed as an example with Borland C and C++ compilers. Modify these
260 %grammars to make a spreadsheet that calculates according to your own
261 %specifications.
262 %
263 %\paragraph{Simple Spreadsheet.}
264 %This is a complete working spreadsheet program, modeled
265 %after TCALC. It uses two grammars, one for keyboard control and one for
266 %evaluating expressions.
267 %
268 %
269 %\paragraph{Pascal Grammar.}
270 %This is a complete grammar for Turbo Pascal, version 5. It
271 %demonstrates the use of semantically determined productions to distinguish
272 %various categories of identifiers. Add reduction procedures to make your
273 %own compiler.
274 %
275 %
276 %
277 %\paragraph{Data Base Query example.}
278 %The purpose of this grammar is simply to
279 %demonstrate some of the techniques you might use to create a very nearly
280 %natural language query system. DBQ illustrates methods for parsing a number
281 %of unconventional (to programmers, anyway) syntaxes. Think of it as a
282 %source of ideas and techniques rather than as a specific query language.
283 %
284 %For example, it shows how to parse inequalities as represented by
285 %mathematicians:
286 %$0 < x < y < 1$
287 %It also shows how to parse inequalities as expressed in ordinary speech:
288 %``Sales over \$500 and under \$2,000 during March''.
289 %
290 %
291
292 \paragraph{Macro Preprocessor with C Grammars.}
293 \agfile{mpp} is the biggest and most complex example provided. This
294 example provides a complete macro preprocessor with your choice of two
295 C grammars. By adding reduction procedures to one of the C grammars
296 you can build yourself a syntax checker, a compiler, an analysis tool
297 or whatever you choose.
298
299 The preprocessor uses four distinct AnaGram grammars and illustrates
300 many of the ways you can interface parsers to other modules. For an
301 overview of the macro preprocessor and how it works, read
302 \agfile{html/macproc.html}. Each grammar and each support module
303 is separately described in its own documentation file.
304
305 %
306 % XXX perhaps note that this cpp is not standards-compliant.
307 %
308 % actually this whole section should probably be moved to an appendix,
309 % especially as it's likely to grow.
310 %