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

comparison doc/manual/winsum.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{Alphabetic Listing of Windows}
2
3 \index{Windows}
4 The following paragraphs summarize the windows AnaGram provides. More
5 detailed descriptions may be found in Chapters 5, 6 and 7. In addition
6 to these windows AnaGram always provides a window to allow you to
7 inspect your syntax file. It is always listed in the \agmenu{Browse}
8 menu.
9
10 \index{Trace}\index{Auxiliary Trace}\index{Window}
11 \paragraph{Auxiliary Trace.}
12 \agwindow{Auxiliary Trace} windows may be accessed through the
13 \agmenu{Auxiliary Windows} popup menu for most windows which display
14 parser state information. The \agwindow{Auxiliary Trace} is a
15 prebuilt \agwindow{Grammar Trace} showing one of perhaps many ways to
16 get to the state identified by the cursor bar in the active window.
17
18 When obtained from the \agwindow{Parser Stack} pane of the
19 \agwindow{File Trace} or \agwindow{Grammar Trace}, the
20 \agwindow{Auxiliary Trace} is simply a copy of the current status of
21 the trace so you can explore alternatives while still retaining the
22 status of the original trace for reference.
23
24 \index{Window}\index{Character Map}
25 \paragraph{Character Map.}
26 The \agwindow{Character Map} table shows you the mapping of input
27 characters to token numbers. The \agcode{ag{\us}tcv} table in your
28 parser is based on the information in this table.
29
30 \index{Character Sets}\index{Window}
31 \paragraph{Character Sets.}
32 This table lists all of the distinct character sets which you defined,
33 implicitly or explicitly, in your grammar. Each line in the table
34 describes one such set.
35
36 \index{Window}\index{Configuration Parameters}
37 \paragraph{Configuration Parameters.}
38 The \agwindow{Configuration Parameters} window lists the configuration
39 parameters AnaGram accepts with their current values, as set by the
40 configuration files it has read and by the most recent syntax file it
41 has analyzed. This window does not include the color settings for the
42 screen, which are controlled separately by the \agwindow{Set Colors}
43 window.
44 % XXX should expand that to say it doesn't include the user interface
45 % preferences, because it's not just colors but fonts and other things.
46
47 \index{Trace}\index{Window}\index{Conflict Trace}
48 \paragraph{Conflict Trace.}
49 You may select a \agwindow{Conflict Trace} window from the
50 \agmenu{Auxiliary Windows} menu of either a \agwindow{Conflicts} or
51 \agwindow{Resolved Conflicts} window. The \agwindow{Conflict Trace}
52 is a ready-made \agwindow{Grammar Trace} which shows you one of
53 perhaps many ways to get to the state which has the conflict you
54 selected. The use of this window is explained more fully in Chapter
55 7.
56
57 \index{Conflicts}\index{Window}
58 \paragraph{Conflicts.}
59 The \agwindow{Conflicts} window lists the conflicts which AnaGram
60 found in your grammar. The table identifies the parser states in which
61 it found conflicts, the reducing tokens for which it had more than one
62 option, and the marked rules which characterize each such option. If
63 AnaGram was able to resolve a conflict by using
64 \index{Precedence declarations}\agparam{precedence} or
65 \index{Sticky declaration}\agparam{sticky} declarations, the conflict
66 will be listed in the
67 \index{Resolved Conflicts}\index{Window}\agwindow{Resolved Conflicts}
68 window instead.
69
70 % XXX that should be ``Conflicts window'', not ``menu'', right?
71 The \agmenu{Auxiliary Windows} menu for the Conflicts menu includes a
72 number of options specially designed to help in identifying the source
73 of conflicts. These are the \agwindow{Conflict Trace}, the
74 \agwindow{Reduction Trace}, the \agwindow{Expansion Chain}, the
75 \agwindow{Rule Derivation} and the \agwindow{Token Derivation}
76 windows. The use of these windows is explained more fully in Chapter
77 7.
78
79 \paragraph{Control Panel.}
80 The \agwindow{Control Panel} is the main AnaGram window. It contains
81 pull down menus to provide access to AnaGram functionality. In
82 addition there is a panel of buttons to invoke the most frequently
83 used AnaGram functions. A text box can be used to enter text to
84 search for. Next to the text box are buttons that implement forward
85 and reverse searching. Searching is always in the most recently
86 active AnaGram window.
87
88 \index{Trace}\index{Window}\index{Error Trace}
89 \paragraph{Error Trace.}
90 If you (1) turn on the
91 \index{Error trace}\index{Configuration switches}\agparam{error trace}
92 configuration switch for your grammar, (2) build a parser from your
93 grammar, (3) run the parser and encounter a syntax error, your parser
94 will checkpoint the parser stack to a file. If you then run AnaGram
95 again and analyze the grammar, AnaGram will read the checkpoint file
96 and prepare a pre-built \agwindow{Grammar Trace} (see below) which
97 shows how your parser got to the state where it encountered the error.
98 % XXX get rid of ``(see below)'', or maybe change it to ``window''
99
100 \index{Expansion Chain}\index{Window}
101 \paragraph{Expansion Chain.}
102 The \agwindow{Expansion Chain} window is available in the
103 \agmenu{Auxiliary Windows} menu from any window that contains
104 expansion rules. Its purpose is to show how a particular expansion
105 rule in a particular state derives from a characteristic rule for that
106 state. The first rule in the window is a characteristic rule for the
107 given state. Each subsequent rule is produced by the marked token in
108 the preceding rule. The last rule is the rule selected by the cursor
109 bar in the parent window.
110
111 \index{Expansion Rules}\index{Window}
112 \paragraph{Expansion Rules.}
113 The \agwindow{Expansion Rules} window is available in the
114 \agmenu{Auxiliary Windows} menu from any window that identifies
115 tokens. It displays a complete left expansion of the selected token
116 if the token is nonterminal. That is, it is a list of rules that
117 begins with all the rules produced by the token followed by all the
118 rules produced by the first token of any rule in the list.
119 % XXX ...clear as mud.
120
121 \index{Trace}\index{Window}\index{File Trace}
122 \paragraph{File Trace.}
123 Select the \agwindow{File Trace} window from the \agmenu{Action} menu.
124 The \agwindow{File Trace} window lets you see precisely how your
125 grammar parses a test file. You can see the contents of the parse
126 stack at any point in the parse. You can watch the parse progress at
127 any level of detail you choose. If you wish, you may back up and try
128 again. When AnaGram runs the \agwindow{File Trace} it also builds a
129 \index{Trace Coverage}\index{Coverage}\agwindow{Trace Coverage} table.
130
131 Note that AnaGram normally uses a number of short-cut parsing actions.
132 To make the parse look like a textbook parse, set the
133 \index{Traditional engine}\index{Configuration switches}
134 \agparam{traditional engine} configuration parameter in your syntax file.
135
136 \index{Trace}\index{Window}\index{Grammar Trace}
137 \paragraph{Grammar Trace.}
138 The \agwindow{Grammar Trace} facility of AnaGram allows you to examine
139 the workings of your parser in detail. Using the various options
140 associated with this window you can set up a representation of the
141 parser state stack and parser state as they might appear in the course
142 of execution of your parser. You can then examine the possible inputs
143 and the changes to the state and the state stack caused by any input
144 you choose.
145
146 You can select input options interactively and see how the parser
147 stack changes. You can back up and try other options. You can also
148 enter text directly in the text entry field. By selecting an
149 \agwindow{Auxiliary Trace} from the popup menu in the \agwindow{Parser
150 Stack} pane, you can compare the results of different sequences of
151 input starting at the same point. You may bypass AnaGram's parser
152 optimization by setting the
153 \index{Traditional engine}\index{Configuration switches}
154 \agparam{traditional engine}
155 configuration switch in your syntax file. When AnaGram runs the
156 \agwindow{Grammar Trace} it also builds a \agwindow{Trace Coverage}
157 table or updates the existing one if one already exists.
158
159 The use of the \agwindow{Grammar Trace} is described in detail in
160 Chapter 5.
161
162 \index{Help}\index{Help Topics}\index{Window}
163 \paragraph{Help Topics.}
164 The \agwindow{Help Topics} window is an alphabetical list of all the
165 help topics in AnaGram's help file. Some help topics can be accessed
166 by more than one key word, so there are actually a few more entries in
167 this table than there are help topics.
168
169 There is an entry for the \agwindow{Help Topics} window in the
170 \agmenu{Help} menu.
171
172 \index{Keyword Anomalies}\index{Window}
173 \paragraph{Keyword Anomalies.}
174 This window is available only if your grammar has keyword anomalies.
175 Each entry in the \agwindow{Keyword Anomalies} window consists of two
176 lines. The first line identifies the parser state in which the
177 anomaly occurs and the offending keyword. The second line identifies
178 the grammar rule which the keyword may erroneously reduce.
179
180 \index{Trace}\index{Window}\index{Keyword Anomaly Trace}
181 \paragraph{Keyword Anomaly Trace.}
182 The \agwindow{Keyword Anomaly Trace} window is a prebuilt
183 \agwindow{Grammar Trace} accessible through the \agmenu{Auxiliary
184 Windows} menu from the
185 \index{Keyword Anomalies}\index{Window}\agwindow{Keyword Anomalies}
186 window. This trace shows one of perhaps many ways to get to the state
187 which has the keyword anomaly selected in the \agwindow{Keyword
188 Anomalies} window.
189
190 \index{Keywords} \index{Window}
191 \paragraph{Keywords.}
192 A \agwindow{Keywords} window is accessible from the
193 \agmenu{Auxiliary Windows} popup menu of any window that identifies
194 parser states. It displays all the keywords the parser will recognize
195 in that state, regardless of whether they are used as shift or as
196 reducing tokens.
197
198 \index{Partition Sets}\index{Window}
199 \paragraph{Partition Sets.}
200 In the \agmenu{Browse} menu, \agwindow{Partition Sets} lists all the
201 partition sets that cover the character universe. In an
202 \agmenu{Auxiliary Windows} menu, \agwindow{Partition Sets} shows the
203 partition sets that cover the character set identified in the parent
204 window.
205
206 \index{Window}\index{Previous States}
207 \paragraph{Previous States.}
208 A \agwindow{Previous States} window can be accessed via the
209 \agmenu{Auxiliary Windows} menu from any window which identifies
210 parser states. It shows the defining rules for all the states which
211 jump to the specified state.
212
213 \index{Window}\index{Productions}
214 \paragraph{Productions.}
215 The \agwindow{Productions} window can be accessed using the
216 \agmenu{Auxiliary Windows} menu from any window that identifies
217 tokens. If the selected token is a nonterminal, the
218 \agwindow{Productions} window will display all the grammar rules it
219 produces.
220
221 \index{Reduction Procedures}\index{Window}
222 \paragraph{Reduction Procedures.}
223 The \agwindow{Reduction Procedures} window lists all of the reduction
224 procedures you have defined in your grammar. Each line of the table
225 gives the C/C++ function prototype. When this window is active, the
226 syntax file window is synchronized with the cursor to show you the
227 text of the reduction procedure.
228
229 \index{Window}\index{Reduction States}
230 \paragraph{Reduction States.}
231 A \agwindow{Reduction States} window can be accessed via the
232 \agmenu{Auxiliary Windows} popup menu from most windows which display
233 marked rules with a specified state. In this case, if the highlighted
234 rule is complete, that is, there is at is no marked token, the
235 \agwindow{Reduction States} window will show you all the possible
236 states the parser could go to on reducing the rule.
237 % XXX ``is at is no''?
238 % XXX s/on reducing/upon reducing/
239
240 \index{Reduction Trace}\index{Trace}\index{Window}
241 \paragraph{Reduction Trace.}
242 A \agwindow{Reduction Trace} window can be requested using the
243 \agmenu{Auxiliary Windows} popup menu from a \agwindow{Conflicts}
244 window or a \agwindow{Resolved Conflicts} window. The
245 \agwindow{Reduction Trace} is coordinated with the \agwindow{Conflict
246 Trace} window, so that the \agwindow{Reduction Trace} shows the result
247 of reducing the selected rule in the \agwindow{Conflict Trace} window.
248
249 \index{Resolved Conflicts}\index{Window}
250 \paragraph{Resolved Conflicts.}
251 AnaGram creates the \agwindow{Resolved Conflicts} window only when the
252 grammar it is analyzing has conflicts and when some of those conflicts
253 have been resolved by precedence rules or by use of the
254 \agparam{sticky} directive. In this case, it will list, in the
255 \agwindow{Resolved Conflicts} window, the conflicts that were resolved
256 and the way in which they were resolved. Rules which your parser will
257 observe are marked with asterisks. Those which your parser will
258 ignore will not be so marked. Any unresolved conflicts will be listed
259 in the \agwindow{Conflicts} window.
260
261 \index{Rule Context}\index{Window}
262 \paragraph{Rule Context.}
263 A \agwindow{Rule Context} window can be requested using the
264 \agmenu{Auxiliary Windows} menu from any window that identifies
265 grammar rules. It shows the usage of all tokens that produce the
266 selected rule.
267
268 \index{Rule Coverage}\index{Window}\index{Coverage}
269 \paragraph{Rule Coverage.}
270 If you have enabled the
271 \index{Rule coverage}\index{Configuration switches}\agparam{rule coverage}
272 configuration switch, your parser will have the capability of counting
273 the number of times each rule in the grammar is reduced during
274 execution of your parser. The \agwindow{Rule Coverage} option on the
275 \agmenu{Browse} menu will be enabled so you can select a rule count
276 file.
277 % XXX s/execution of your parser/execution/
278 % XXX s/have the capability of counting/will be able to count/
279
280 % XXX s/menu, from the/menu of the/ ?
281 \index{Rule Derivation}\index{Window}
282 \paragraph{Rule Derivation.}
283 You may select a \agwindow{Rule Derivation} from the \agmenu{Auxiliary
284 Windows} menu, from the \agwindow{Conflicts} window, the
285 \agwindow{Resolved Conflicts} window, or the \agwindow{Keyword
286 Anomalies} window. The purpose of this window is to show how a
287 particular conflict or ambiguity arises in your grammar. AnaGram
288 develops this window in conjunction with the \agwindow{Token
289 Derivation} window which you may also select.
290
291 Position the cursor bar on a
292 \index{Completed rule}\index{Rule}\agterm{completed rule},
293 that is, one with no marked token. If you don't, AnaGram will scan
294 down the table for the next completed rule. The \agwindow{Rule
295 Derivation} and the \agwindow{Token Derivation} show you two sequences
296 of productions, both deriving from one original rule, which
297 demonstrate how the conflict arises. One sequence of productions, the
298 \agwindow{Rule Derivation}, shows how the completed rule derives from the
299 original rule. The other sequence of productions, the \agwindow{Token
300 Derivation}, shows how the reducing token derives from the original
301 rule. These derivations are discussed in greater detail in Chapter 7.
302
303
304 \index{Set Elements}\index{Window}
305 \paragraph{Set Elements.}
306 The \agwindow{Set Elements} window can be accessed through the
307 \agmenu{Auxiliary Windows} menu in a window that identifies a
308 character set, a partition set, or a terminal token. The
309 \agwindow{Set Elements} window shows the numeric code and screen
310 representation for each element of the set. In the case of a terminal
311 token, the character set displayed is the character set corresponding
312 to the terminal token. If you select \agwindow{Set Elements} in a
313 window that identifies tokens, and the selected token is nonterminal,
314 AnaGram will simply beep.
315
316 \index{State Definition}\index{Window}
317 \paragraph{State Definition.}
318 The \agwindow{State Definition} window can be accessed through the
319 \agmenu{Auxiliary Windows} menu in any window that identifies a state
320 but does not provide its characteristic rules. The format is the same
321 as that in the \agwindow{State Definition Table}, except that it is
322 limited to a single state.
323
324 \index{State Definition Table}\index{Window}
325 \paragraph{State Definition Table.}
326 The \agwindow{State Definition Table} lists, for each parser state,
327 all of the characteristic rules which define that state. The rules are
328 displayed with the marked token in a distinctive font.
329 \index{Rule}\index{Completed rule}\index{Rule}If there is no
330 marked token, the rule is complete. Otherwise, the marked token found
331 to continue the match.
332 % XXX ``the marked token found to continue the match''?
333 % (yes, this is how it is in the wordperfect version)
334 % it also said ``with a the marked token'' but I fixed that.
335
336 Each line contains the state number, the rule number, and finally the
337 rule itself. The state number field is blank if it is the same as the
338 state number on the previous line. The cursor bar is synched with the
339 syntax file to show the grammar rule in context.
340
341 \index{State Expansion}\index{Window}
342 \paragraph{State Expansion.}
343 The \agwindow{State Expansion} window may be accessed using the
344 \agmenu{Auxiliary Windows} menu from any window that identifies a state.
345 It shows the complete set of expansion rules for the state, consisting
346 of the union of the set of characteristic rules and the sets of
347 expansion rules for the token to the right of the mark in each
348 characteristic rule. The \agwindow{State Expansion} window shows all
349 possible legal input to your parser in the given state.
350
351 % XXX \index{Show statistics} ?
352 \paragraph{Statistical Summary.}
353 While your grammar is being analyzed, a \agwindow{Statistical Summary}
354 window pops up to show the progress of the analysis. Unless you have
355 turned off the \agparam{show statistics} switch on the
356 \agmenu{Options} menu, this window will remain on-screen for
357 reference. Among other things it shows you the number of rules and
358 states in your grammar, and the number of conflicts and warnings, if
359 any.
360
361 Note that if your grammar is small and you have the \agparam{show
362 statistics} switch disabled, the appearance of this window on your
363 monitor may be exceedingly brief - you may just see a flash.
364 % XXX or nothing at all.
365
366 If the window is turned off or you have closed it, you can get it from
367 the \agmenu{Browse} menu.
368
369 \index{Symbol Table}\index{Window}
370 \paragraph{Symbol Table.}
371 The \agwindow{Symbol Table} lists all the symbols you used in your
372 grammar. Symbols may be used, of course, to identify tokens,
373 definitions, or virtual productions or to provide alternative names
374 for tokens.
375
376 Each line in this table identifies a single symbol. The first field
377 is the token number, if any. This is followed by the name. If the
378 name identifies a set expression or virtual production, it is followed
379 by an equal sign and the expression or virtual production.
380
381 \index{Token Derivation}\index{Window}
382 \paragraph{Token Derivation.}
383 See \agwindow{Rule Derivation}.
384
385 \index{Token Table}\index{Window}
386 \paragraph{Token Table.}
387 The \agwindow{Token Table} lists all the tokens of your grammar. The
388 first field is the token number. It is followed by a flag field which
389 is ``zl'' if the token is a nonterminal token and is zero length. If
390 the token is nonterminal and not zero length, the flag field contains
391 ``nt''. If the token is a terminal token, the field is blank. The
392 next field is blank unless the token has been declared
393 \agparam{sticky} or has had a precedence level assigned. If the token
394 is sticky, this field will contain ``s''. If a precedence level has
395 been assigned, this field will contain the letter ``l'', ``r'', or
396 ``n'' to indicate associativity followed by the precedence level.
397 Finally there is the data type of the semantic value of this token and
398 the token representation.
399
400 \index{Token Usage}\index{Window}
401 \paragraph{Token Usage.}
402 You may access a \agwindow{Token Usage} window from the
403 \agmenu{Auxiliary Windows} menu of any window that identifies a
404 token. It shows all grammar rules which use the token. In each rule
405 the marked token, if any, will follow the selected token, so that
406 further \agwindow{Auxiliary Windows} menu choices will refer to the
407 marked token rather than the selected token.
408
409 \index{Trace Coverage}\index{Window}\index{Coverage}
410 \paragraph{Trace Coverage.}
411 When you run a \agwindow{File Trace}, AnaGram automatically counts the
412 number of times each rule in your grammar is reduced. You may inspect
413 these counts using the \agwindow{Trace Coverage} window. Unless you
414 have set the \agparam{rule coverage} switch, certain optimizations in
415 AnaGram's tables will cause some null productions and rules consisting
416 of a single token to not be counted.
417
418 \index{Warnings}\index{Window}
419 \paragraph{Warnings.}
420 If while analyzing your syntax file, AnaGram finds something
421 suspicious, it issues a warning, regardless of the severity of the
422 problem. The \agwindow{Warnings} window will pop up automatically
423 when the analysis has been completed. If the warning is for a
424 \index{Errors}syntax error in your input file, you will have to fix
425 it, because AnaGram cannot successfully interpret your syntax file.
426 Otherwise, no matter how serious the warnings may be, AnaGram will
427 create a parser if it is instructed to do so. Thus if you decide the
428 warnings are of no consequence, you may choose to ignore them. Note
429 that AnaGram will resolve \index{Conflicts}shift-reduce conflicts by
430 choosing the shift action. It will resolve
431 \index{Conflicts}reduce-reduce conflicts by choosing the rule that
432 occurred first in the grammar.
433
434 If you have syntax errors, AnaGram will synchronize the cursor in the
435 syntax file window with the cursor in the warning window so that as
436 you move through the warning messages, the cursor in the syntax file
437 window will move to the point of the error.