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

comparison doc/manual/ra.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{Running AnaGram}
2
3
4 \section{Overview}
5
6 AnaGram's main window is a small
7 \index{\agwindow{Control Panel}}\agwindow{Control Panel}
8 with menus, a toolbar, a status indicator, and a simple search
9 facility. Its default position is at the upper right of your screen.
10 AnaGram's two basic commands,
11 \index{Analyze Grammar}\agmenu{Analyze Grammar}
12 and
13 \index{Build Parser}\agmenu{Build Parser},
14 are available from the \agmenu{Action} menu of the \agwindow{Control
15 Panel}.
16
17 % XXX remove the stuff about time; nowadays it's all instantaneous
18 The commands take as input a syntax file containing the specifications
19 of your grammar. \agmenu{Build Parser} creates a parser file, in C or
20 C++, and a header file. \agmenu{Analyze Grammar} does not write any
21 \index{Output files}\index{File}output files, and therefore takes a
22 little less time than \agmenu{Build Parser} to run. Normally you
23 would use \agmenu{Build Parser} when you are ready to start compiling
24 and testing your parser. You would use \agmenu{Analyze Grammar} while
25 you are working on the grammar itself.
26
27 % XXX s/build/create/
28 Both of these commands cause AnaGram to build a number of tables
29 describing your grammar. These tables, accessible from the
30 \agmenu{Browse} menu, will interest you mainly when you are debugging
31 your grammar. These tables and their use are described in Chapters 6
32 and 7. An alphabetic listing of the tables with summaries of their
33 content may be found in Appendix C.
34
35 The primary purpose of AnaGram's user interface is to enable you to
36 inspect the grammar tables, and to use the \agwindow{Grammar Trace}
37 and \agwindow{File Trace} facilities to study, at any level of detail
38 you wish, how your parser analyzes any sequence of input characters or
39 tokens.
40
41 AnaGram is documented with an extensive, hypertext \agwindow{Online
42 Help} system in addition to this User's Guide. Supplementary
43 documentation in browser-readable format can be found in the
44 \agfile{html} directory distributed with AnaGram.
45
46
47 \section{Executables}
48 \index{Executables}
49
50 % XXX s/make files/makefiles/
51 % (better do a global search and replace)
52
53 \index{Make files}\index{\agfile{ag.exe}}\index{\agfile{agcl.exe}}
54 AnaGram has two executables: one interactive, \agfile{ag.exe}, and
55 one, \agfile{agcl.exe}, for use in make files.
56
57 \index{Command line}
58 If you provide \agfile{ag.exe} with a syntax file name on the command
59 line, AnaGram will load the file and do either \agmenu{Analyze
60 Grammar} or \agmenu{Build Parser}, depending on the setting of the
61 \index{\agoption{Autobuild}}\agoption{Autobuild} option.
62
63 The command line version, \agfile{agcl.exe}, builds a parser for the
64 syntax file specified on the command line. Warning and error messages
65 from \agfile{agcl.exe} are directed to \agcode{stdout}.
66
67 \index{File extension}\index{syn}\index{.syn}
68 The default extension for syntax files appearing on the command line
69 is \agfile{.syn}.
70
71
72 \section{Input Files}
73 \index{Input Files}\index{Files}\index{File}
74
75 Input files for AnaGram are called syntax files and usually have the
76 \index{File extension}\index{syn}\index{.syn}
77 extension \agfile{.syn}.
78 \index{Syntax file}\index{File}
79 Syntax files are written in a variant
80 of
81 \index{Backus-Naur form}Backus-Naur form,
82 and may include reduction procedures written in C or C++ as well as
83 other embedded C or C++ code. The general theory of syntax files is
84 given in Chapter 4. The rules for writing syntax files are given in
85 Chapter 8.
86
87 When you run AnaGram and analyze a grammar, the syntax file you have
88 chosen will appear in the \agmenu{Browse} menu under the heading
89 \agmenu{Syntax File} followed by the file name. It will also appear
90 in a window on your screen unless you have turned the
91 \index{Show Syntax}\agoption{Show Syntax} option off.
92
93
94 \section{Output Files}
95 \index{Output Files}\index{Files}\index{File}
96
97 % XXX s/parser file/source file/
98 When you choose the \agmenu{Build Parser} command, AnaGram builds two
99 output files: a header file and a parser file. Normally these files
100 have the same name as your syntax file and the \index{File
101 extension}extensions \agfile{.h} and \agfile{.c}, respectively. You
102 may change the names or the extensions by use of the
103 \index{File name}\index{Header file name}\agparam{header file name}
104 and
105 \index{File name}\index{Parser file name}\agparam{parser file name}
106 \index{Configuration parameters}configuration parameters
107 (see Appendix A). If you are using C++, you will probably wish to set
108 % XXX s/in your configuration file/accordingly/
109 the \agparam{parser file name} parameter in your configuration file.
110 Include the following line in your configuration file or section:
111
112 % This is really part of the preceding paragraph and latex won't
113 % space it accordingly even if you don't have any line breaks in
114 % between. This looks unsightly at first glance but it makes things
115 % clearer when actually reading.
116 \vskip -1.25ex
117
118 % This was 1 inch, but wp2latex must have made that up out of thin air
119 \begin{indentingcode}{0.4in}
120 parser file name = "\#.cpp"
121 \end{indentingcode}
122
123 The \index{Header file}\index{File}header file contains typedef
124 statements and macro definitions which are needed by the parser and
125 which you may need to use in other modules to interface your parser to
126 the rest of your program.
127
128 The \index{Parser file}\index{File}parser file contains the reduction
129 procedures and embedded C or C++ code that AnaGram finds in your
130 syntax file, a number of tables which summarize your grammar, and a
131 parsing engine customized to your requirements. The
132 \index{Parsing engine}parsing engine
133 is written in C. Care has been taken to assure that it can be
134 compiled by almost any C/C++ compiler. The content of the header file
135 and the parser file is described in Chapter 9.
136
137
138 \section{AnaGram's Help}
139 \index{Help}\index{Online help}
140
141 There are three main ways to access AnaGram's \agwindow{Online Help}:
142
143 \begin{itemize}
144 \item Press F1 for context-sensitive help from most windows and menu
145 items.
146 \item Similarly, use the \agwindow{Help Cursor} on the
147 \agwindow{Control Panel} toolbar (described below) from most windows
148 and menu items.
149 \item From the \agmenu{Help} menu on the \agwindow{Control Panel}, you
150 can bring up a complete list of help topics and choose a topic.
151 \end{itemize}
152
153 You can also get fly-over help for the toolbar buttons on the
154 \agwindow{Control Panel}. \agwindow{File} and \agwindow{Grammar
155 Traces} have a \agmenu{Help} button.
156
157 AnaGram's \agwindow{Help} windows remain on-screen until you dismiss
158 them. This means you can refer to several topics at once. They have
159 hypertext links to other Help topics. Also, right-clicking the mouse
160 on a \agwindow{Help} window or pressing F1 will pop up an Auxiliary
161 Windows menu of all linked topics in the window. ``Using Help'' is
162 always available from this popup menu.
163
164 % XXX s/that,/that/
165 Note that, for the \agwindow{Warnings}, \agwindow{Configuration
166 Parameters} and \agwindow{Help Topics} windows, F1 will give you help
167 for the item on the highlighted line, whereas the \agwindow{Help
168 Cursor} allows you to select any line by clicking on it.
169
170 AnaGram also has browser-readable documentation of examples, a
171 glossary, brief descriptions of the \agwindow{File} and
172 \agwindow{Grammar Traces}, and some further topics in the
173 \agfile{html} directory distributed with AnaGram.
174
175
176 \section{Control Panel Components}
177 \index{Control Panel}
178
179 \index{Action Menu}\index{Menu}\subsection{Action Menu}
180 In addition to the basic \agmenu{Analyze Grammar} and \agmenu{Build
181 Parser} commands, the \agmenu{Action} menu provides some variations on
182 these commands for your convenience:
183
184 \begin{itemize}
185
186 \item If a grammar has already been analyzed, but not yet built, there
187 will also be an extra \agmenu{Build} command with the name of your
188 syntax file.
189
190 \item The \agmenu{Reanalyze} and \agmenu{Rebuild} commands are
191 initially greyed out. They become available if the current syntax
192 file is changed externally by another program.
193
194 \item At the bottom of the menu is a list of up to six recently used
195 syntax files. Clicking on one of these gives the same effect as
196 \agmenu{Analyze Grammar}, or if the
197 \index{\agoption{Autobuild}}\agoption{Autobuild} option
198 is on, the same effect as \agmenu{Build Parser}.
199
200 \end{itemize}
201
202 Before executing an \agmenu{Analyze Grammar} or \agmenu{Build Parser}
203 command, AnaGram closes all windows related to the current syntax
204 file, if any, and resets
205 \index{Configuration parameters}configuration parameters to their initial
206 values, as determined by the built in defaults and the configuration
207 files read at program initialization.
208
209 The \agmenu{Action} menu also lets you select a \agmenu{File Trace} or
210 \agmenu{Grammar Trace}, and if the
211 \index{error trace}\agparam{error trace}
212 \index{Configuration parameters}configuration switch is
213 enabled, an \agmenu{Error Trace}. The traces are covered in Chapter
214 5.
215
216
217 \subsection{Browse Menu}
218 \index{Menu}\index{Browse Menu}
219
220 Most of the \agmenu{Browse} menu entries are tables describing your
221 grammar which become available as soon as you analyze it. The tables
222 are described in Chapters 6 and 7. The tables themselves often have
223 associated tables available via an
224 \index{Auxiliary Windows}\agmenu{Auxiliary Windows}
225 menu which pops up when you right-click on a highlighted
226 line.
227
228 A window showing your syntax file is also available from this window.
229 Do not overlook the
230 % noindex (XXX?)
231 \agmenu{Configuration Parameters}
232 entry. AnaGram has a great many parameters available so you can make
233 AnaGram behave in a variety of ways and produce parsers with the
234 features you want. Configuration parameters are documented in
235 Appendix A.
236
237
238 \subsection{Options Menu}
239 \index{Options Menu}\index{Menu}
240
241 Items you set from the \agmenu{Options} menu will be saved in the
242 Windows Registry so they can be restored every time you start AnaGram.
243
244 \paragraph{Fonts and Colors.}
245 \index{Fonts}\index{Colors}
246 You can set AnaGram's fonts and colors to suit your own tastes. Make
247 sure that the \agmenu{Marked Tokens} font is very distinctive so these
248 tokens show up clearly even if they are only one or two characters
249 long. Try an underlined font for them if you like. Notice also that
250 the \agwindow{Test File} pane requires three different sets of text
251 and background colors. You should make sure that the backgrounds, at
252 least, can be easily distinguished from each other so the trace
253 information can be properly displayed. You also want to take care
254 that an active pane in a \agwindow{File} or \agwindow{Grammar Trace}
255 can be distinguished from inactive panes.
256
257 Color changes pertain only to the client areas of AnaGram windows.
258 The remaining parts of your windows will have the customary colors you
259 have chosen for your system.
260
261 \paragraph{Autobuild.}
262 \index{Autobuild}
263 When \agoption{Autobuild} is checked, selecting a file from the list
264 of most recently used files on the \agmenu{Action} menu invokes the
265 \agmenu{Build Parser} command. Otherwise, the \agmenu{Analyze
266 Grammar} command is invoked.
267
268 \index{Show Statistics}\index{Statistics}
269 \paragraph{Show Statistics.}
270 If this entry is checked, AnaGram will leave the \agwindow{Statistical
271 Summary} window on the screen after it has analyzed your grammar. If
272 the entry is not checked or you have closed the window, you can select
273 it from the \agmenu{Browse} menu.
274
275 \paragraph{Show Syntax.}
276 \index{Show Syntax}\index{Syntax}
277 If this entry is checked, AnaGram will display the syntax file when it
278 has analyzed your grammar. If this entry is not checked or you have
279 closed the syntax file window, you can select the window from the
280 \agmenu{Browse} menu.
281
282 \paragraph{Stay On Top.}
283 \index{Stay On Top}
284 This entry allows you to specify whether the \agwindow{Control Panel}
285 stays on top of other AnaGram windows.
286
287
288 \subsection{Windows Menu}
289 \index{Windows Menu}\index{Menu}
290
291 In addition to the list of open (including hidden) windows, this menu
292 has the customary \agmenu{Cascade}, \agmenu{Close}, \agmenu{Hide} and
293 \agmenu{Restore Windows} commands. A \agmenu{Copy} feature lets you
294 copy the currently active table or \agwindow{Help} topic to the
295 \index{Copy}\index{Clipboard}clipboard.
296
297
298 \subsection{Help Menu}
299 \index{Help Menu}\index{Menu}
300
301 The \agmenu{Help} menu has \agmenu{Getting Started}, \agmenu{Using
302 Help}, and \agmenu{What's New} entries, all of which you will probably
303 want to take a look at when you begin using AnaGram. In the long
304 term, you will probably find
305 \index{Help}\index{Help Topics}\agmenu{Help Topics} to be the most
306 useful item in this menu. It provides a complete list of
307 \agwindow{Help Topics} titles. You can bring up the window for a
308 highlighted topic by double-clicking with the left mouse button,
309 pressing F1, or using the \agwindow{Help Cursor}. You may want to use
310 the \agmenu{Search} facility in this window.
311
312
313 \subsection{Control Panel Toolbar}
314 \index{Control Panel}\index{Toolbar}
315
316 The first four toolbar buttons provide quick access to the
317 \agmenu{Analyze Grammar}, \agmenu{Build Parser}, \agmenu{File Trace}
318 and \agmenu{Grammar Trace} commands. Two more buttons bring up the
319 \agwindow{Warnings} and \agwindow{Conflicts} windows if they have any
320 entries.
321
322 The last button, with a question mark, enables a \agwindow{Help
323 Cursor}, which is convenient for getting help on warnings,
324 \agmenu{Browse} tables, menu items, and so on. Once enabled, the
325 \agwindow{Help Cursor} can be dragged with the mouse. A further mouse
326 click will provide help for the item under the cursor. Note that
327 AnaGram also has F1 help which you may find simpler and faster than
328 the \agwindow{Help Cursor}.
329
330
331 \subsection{Status Indicator}
332 \index{Status Indicator}\index{Indicator}
333
334 The status indicator at the right of the \agwindow{Control Panel} has
335 six possible states: Ready, Loaded, Error, Parsed, Analyzed, and
336 Built. ``Ready'' appears only when no grammar has been selected.
337 ``Loaded'' and ``Parsed'' should be transitory. If ``Error'' appears,
338 one or more syntax errors have been found in your grammar and AnaGram
339 cannot continue its analysis. Check the Warnings window to determine
340 the nature of the problem. ``Analyzed'' means that analysis of the
341 grammar has been completed. ``Built'' means the analysis has been
342 completed and also output files have been written.
343
344
345 \subsection{Search}
346 \index{Search}
347
348 \index{Searching for text}AnaGram has a simple search facility to let
349 you search for text strings in AnaGram windows. A text entry field on
350 the \agwindow{Control Panel} is provided for you to enter text.
351 Left-clicking on the neighboring \agmenu{Find Next} and \agmenu{Find
352 Previous} buttons lets you search either forward or backward for a
353 line in the active window which contains at least one instance of the
354 text.
355
356 Note that the search begins at the next line after the highlighted
357 line for forward search; at the line preceding the highlighted line
358 for backward search.
359 \index{Case sensitivity}Searches are not case sensitive.
360
361
362 \section{Statistical Summary}
363 \index{Statistical Summary}\index{Summary}
364
365 While your grammar is being analyzed, a \agwindow{Statistical Summary}
366 window pops up to show you the progress of the analysis. Unless you
367 have turned off \agmenu{Show Statistics} on the \agmenu{Options} menu,
368 this window will remain on-screen for your reference. Among other
369 things, it shows you the number of rules and states in your grammar,
370 and the number of conflicts and warnings, if any.
371
372 Note that if your grammar is small and you have \agmenu{Show
373 Statistics} turned off, the appearance of this window on your monitor
374 may be exceedingly brief -- you may just see a flash.
375
376 If this window is turned off or you have closed it, you can select it
377 from the \agmenu{Browse} menu.
378
379
380 \section{Auxiliary Windows Popup Menu}
381 \index{Auxiliary Windows}\index{Popup Menu}\index{Menu}
382
383 For many tables you can get more detailed information keyed to the
384 highlighted item by right clicking the mouse to pop up the
385 \agmenu{Auxiliary Windows} menu.
386
387 Some auxiliary windows are keyed simply to a state number, a token
388 number, a rule number, a character set number, or a partition set
389 number identified by the highlighted item. Others are keyed to some
390 combination of these numbers. If the cursor bar is highlighting a
391 marked rule, the \index{Marked Token}\index{Token}marked token is the
392 token to which the auxiliary window is keyed. The key, whether it is
393 a state number, token number, or other identifier, is always displayed
394 on the title bar of the window.
395
396 Help windows also have popup \agmenu{Auxiliary Windows} menus. For a
397 Help window, the popup menu shows all linked topics in the window.
398
399
400 \section{Keyboard Control}
401 \index{Keyboard}
402
403 AnaGram can be controlled entirely from the keyboard. In the
404 \agwindow{Control Panel}, you can tab to any button and press Enter to
405 select it. In addition to the conventional Windows keyboard
406 functions, the following keys have been implemented:
407
408 % XXX this doesn't look so great
409 \index{Escape}\index{F8}\index{F10}\index{F10}
410 \begin{tabular}{rll}
411 $\bullet$&Escape&Closes any AnaGram window except the Control Panel.\\
412 $\bullet$&F8&Toggles between an active AnaGram window and the Control Panel.\\
413 $\bullet$&F10&Accesses the Control Panel menu from any AnaGram Window.\\
414 $\bullet$&Shift F10&Pops up the Auxiliary Windows menu.\\
415 \end{tabular}