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

comparison doc/manual/xg-i.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{Exploring Your Grammar I: Traces}
2
3 \section{Introduction}
4
5 AnaGram provides two important facilities to help you become familiar
6 with the workings of your parser: the File Trace and the Grammar
7 Trace. The File Trace takes its input from a test file and, under
8 your control, parses the input in accordance with your grammar. The
9 Grammar Trace is completely interactive. In each state it presents
10 you with a list of acceptable tokens and lets you select the one you
11 wish. The File Trace lets you see how your grammar will deal with a
12 specific input file. The Grammar Trace lets you answer ``what if?''
13 questions.
14
15 AnaGram also provides several ready-made traces to help you deal with
16 specific problems. The
17 \index{Error Trace}\index{Trace}\index{Window}\agwindow{Error Trace}
18 can show you why your parser has diagnosed a syntax error. The
19 \index{Conflict Trace}\index{Trace}\index{Window}\agwindow{Conflict
20 Trace} and
21 \index{Reduction Trace}\index{Trace}\index{Window}\agwindow{Reduction
22 trace} can help you identify the sources of ambiguities in your
23 grammar. The
24 \index{Keyword Anomaly Trace}\index{Trace}\index{Window}\agwindow{Keyword
25 Anomaly Trace} can help you understand the genesis of a keyword
26 anomaly in your grammar. In addition, the
27 \index{Trace}\index{Auxiliary Trace}\index{Window}\agmenu{Auxiliary Trace}
28 selection in the
29 \agmenu{Auxiliary Windows} popup menu enables you to get a trace to
30 any state you wish or to transmute a File Trace into a Grammar Trace.
31
32 The trace functions serve several purposes. They are an ideal way to
33 learn how syntax directed parsing works since they make each step
34 clearly visible. They are also useful in determining whether your
35 grammar works as you wish it to. You can try your grammar out on real
36 data before you actually build a parser. If your grammar has
37 problems, such as conflicts, you can use the trace functions to track
38 down the problems, to understand them, and to verify your corrections.
39
40 You may have any number of File and Grammar Traces active
41 simultaneously.
42
43 Remember that AnaGram usually uses short-cut parsing actions whenever
44 possible. If you wish to see just the standard four parsing actions,
45 you may want to set the \agparam{traditional engine} switch. This
46 will, however, substantially increase the size of your parser and
47 reduce its performance.
48
49 \section{Trace Windows}
50
51 The \agwindow{File} and \agwindow{Grammar Trace} windows normally each
52 contain three panes: the \agwindow{Parser Stack} pane, an input pane,
53 and the \agwindow{Rule Stack} pane. If your grammar uses semantically
54 determined productions, the Reduction Choices pane will appear when
55 necessary to allow you to select a reduction token.
56
57 % XXX s/some point/a point/
58 In the File Trace, the input, or \index{Test File pane}\agwindow{Test
59 File}, pane displays the test file. You need only double click on
60 some point in the pane to test your grammar up to that point in the
61 file. Differently colored backgrounds are used to distinguish the
62 part of the file that has been parsed from the part that has not yet
63 been parsed.
64
65 In the Grammar Trace, the input, or \index{Allowable Input
66 pane}\agwindow{Allowable Input}, pane displays a list of tokens which
67 are allowable input in the current state of the parser. You may
68 select tokens from the \agwindow{Allowable Input} pane, one by one, or
69 use the text entry field to type input to be parsed.
70
71 The active pane has a distinctively colored title panel and cursor
72 bar, except for the \agwindow{Test File} pane in the \agwindow{File
73 Trace} which has no cursor bar. You can use the tab key to tab among
74 the panes. The function of other keyboard keys depends on which pane
75 is active.
76
77 Along the bottom of the trace windows is a toolbar which provides
78 status information as well as control buttons.
79
80 \subsection{Parser Stack Pane}
81
82 The \index{Parser Stack pane}\agwindow{Parser Stack} pane, the upper
83 left pane of the \agwindow{File Trace} and \agwindow{Grammar Trace}
84 windows, displays the parser stack for the current trace.
85
86 Each line corresponds to one level in the parser state stack, showing
87 the stack index, the parser state for that level, and the token which
88 was seen at that state. The last line of the stack, the lookahead
89 line, corresponds to the current state of the parser. Since no input
90 has yet been processed for this state, the token, if any, which
91 appears at this level is a lookahead token.
92
93 In the File Trace, the token on the lookahead line corresponds to the
94 character at the parse location in the Test File pane. In the Grammar
95 Trace, the lookahead line is empty whenever all previous input to the
96 parser has been completely parsed, otherwise it will display the most
97 recently selected input token.
98
99 If you move the cursor in the Parser Stack pane of a File Trace, the
100 text that makes up the selected token will be highlighted in the Test
101 File pane. You can back the parse up to any desired stack level by
102 double clicking at the beginning of the token text in the Test File
103 pane.
104
105 Similarly, if you move the cursor bar in the Parser Stack pane of a
106 Grammar Trace, the \index{Allowable Input pane}\agwindow{Allowable
107 Input} pane will change to display the allowable tokens in the
108 selected state. The previously selected token will be highlighted.
109 Then, double click on any token in the Allowable Input pane to back
110 the parse up and choose a token a second time.
111
112 The \index{Rule Stack pane}\agwindow{Rule Stack} pane (see below) of
113 the \agwindow{File} or \agwindow{Grammar Trace} is also synched to the
114 \agwindow{Parser Stack} pane. If the syntax file window is visible,
115 it will be synched to show the rule currently selected in the
116 \agwindow{Rule Stack} pane. Note that rules that have been
117 automatically generated by the expansion of virtual productions cannot
118 be synched, so the top line of the syntax file will be highlighted
119 instead.
120
121 If you right-click on a highlighted line in the Parser Stack pane, you
122 will get a pop-up menu to give you more information. In particular
123 you can get an \agwindow{Auxiliary Trace} starting at the current
124 point in your \agwindow{File} or \agwindow{Grammar Trace}, so you can
125 explore various possibilities without losing your position in the old
126 trace.
127
128 \subsection{Rule Stack Pane}
129
130 The \index{Rule Stack pane}Rule Stack pane appears across the bottom
131 of a \agwindow{Grammar Trace} or \agwindow{File Trace} window. It
132 provides an alternate view of the parser stack for the trace, showing,
133 for each state, rules instead of the tokens that you see in the
134 \agwindow{Parser Stack} pane. Because it is synched with the syntax
135 file window, the \agwindow{Rule Stack} makes it easy to see the
136 relationship between the trace and your grammar.
137
138 For each level of the parser stack, the \agwindow{Rule Stack} shows
139 the parser state number and all the active rules. The active rules at
140 any state consist of all the expansion rules for the state that are
141 consistent with the input at all subsequent states.
142
143 Except for the last level of the stack, each rule has a
144 \index{Token}\agterm{marked token}, which in the default
145 configuration is displayed in bold, italic type. The significance of
146 the marked token is that all tokens in the rule to the left of the
147 marked token have already been matched in the input, and the input in
148 subsequent levels is consistent so far with the marked token. As more
149 input is processed, rules that are inconsistent with the new input are
150 deleted from the display.
151
152 The last level of the stack shows the current state of the parser and
153 the rules against which the lookahead token will be matched. At this
154 level, there may be rules with no marked tokens. These are rules
155 which have been matched exactly in the input. If there is more than
156 one such rule, at the next parser step the parser will use the
157 lookahead token to determine which rule to reduce.
158
159 In the last level of the stack, marked tokens represent the input the
160 parser expects to see next.
161
162 The \agwindow{Rule Stack} pane is synched with the syntax file window
163 if it is visible so that the rule highlighted in the \agwindow{Rule
164 Stack} can be seen in context in the syntax file. For rules that
165 AnaGram generated automatically to implement virtual productions or
166 the disregard statement, the cursor bar will move to the top of the
167 syntax file window.
168
169 The \agwindow{Rule Stack} pane is also synched with the other panes in
170 the trace. As you move the cursor bar in the \agwindow{Rule Stack},
171 the cursor bar in the \agwindow{Parser Stack} pane will track the
172 stack level in the \agwindow{Rule Stack}. In a \agwindow{File Trace},
173 text will be highlighted in the \agwindow{Test File} pane
174 corresponding to the selected token in the \agwindow{Parser Stack}
175 pane. In a \agwindow{Grammar Trace}, the marked token in the
176 highlighted rule will be highlighted in the \agwindow{Allowable Input}
177 pane.
178
179 Clicking the right mouse button in the \agwindow{Rule Stack} pane pops
180 up an \agmenu{Auxiliary Windows} menu to give you more information
181 about the highlighted rule. The \agmenu{Auxiliary Windows} menu
182 offers four choices keyed to the marked token: \agmenu{Expansion
183 Rules}, \agmenu{Productions}, \agmenu{Set Elements} and \agmenu{Token
184 Usage}. The \agmenu{Keywords}, \agmenu{State Definition} and
185 \agmenu{State Expansion} options are keyed to the state number. The
186 \agmenu{Expansion Chain} and \agmenu{Rule Context} options are keyed
187 to the highlighted rule. Note that by the very nature of the rule
188 stack, a completed rule may occur only at the last level.
189
190 \subsection{Reduction Choices Pane}
191 \index{Reduction Choices pane}
192
193 The \agwindow{File Trace} and \agwindow{Grammar Trace} display a
194 \agwindow{Reduction Choices} pane when they need to reduce a
195 semantically determined production. The rule to be reduced is
196 highlighted in the \agwindow{Rule Stack} pane. The syntax file
197 window, if visible, will show this rule highlighted if it is one that
198 appears directly in your grammar.
199
200 The \agwindow{Reduction Choices} pane lists all possible reduction
201 tokens for the specified rule. The first reduction token that is
202 admissible in the current context is highlighted and it appears as the
203 lookahead token in the \agwindow{Parser Stack} pane. In the
204 \agwindow{File Trace}, text that comprises the entire rule is
205 highlighted in the \agwindow{Test File} pane.
206
207 Select the desired reduction token before continuing with the parse.
208
209 If you select a token and it does not appear as the lookahead token,
210 it is not syntactically correct in the current context. If you try to
211 proceed with the parse, you will get a selection error.
212
213 \subsection{Parse Status}
214 \index{Parse Status}
215
216 Both the \agwindow{File} and \agwindow{Grammar Trace} have a
217 \agwindow{Parse Status field} on the toolbar at the bottom of the
218 window to indicate the current state of the parser. The possible
219 values are as follows:
220 \begin{itemize}
221 \item \agmenu{Ready}: The parser is ready for input.
222 \item \agmenu{Running}: The parser is processing input.
223 \item \agmenu{Parse Complete}: According to the grammar, no further
224 input is expected. Click on reset or reload to restart the parse.
225 \item \agmenu{Syntax error}: A syntax error has been encountered. The
226 parser cannot go any further.
227 \item \agmenu{Unexpected end of file}: The parser has reached the end
228 of the actual input but the grammar still expects more.
229 \item \agmenu{Select reduction token}: The parser encountered a
230 semantically determined production. Select a reduction token from the
231 \agwindow{Reduction Choices} pane.
232 \item \agmenu{Selection error}: The reduction token selected from the
233 Reduction Choices pane was not allowable input in the present
234 state. Select another reduction token.
235 \end{itemize}
236
237
238 \section{File Trace}
239 \index{File Trace}\index{Trace}\index{Window}
240
241 \subsection{Starting File Trace}
242
243 To do a \agwindow{File Trace} you must first analyze the grammar you
244 wish to use. Then select \agmenu{File Trace} from the \agmenu{Action}
245 menu. Select a file for parsing and the trace will begin. If you
246 have not analyzed a grammar or if your grammar does not accept ASCII
247 characters the \agmenu{File Trace} option will be grayed out. You may
248 provide a mask for the test file name by setting the
249 \index{Test file mask}\index{Configuration parameters}\agparam{test
250 file mask} configuration parameter in your syntax file (see Appendix
251 A, Configuration Parameters). AnaGram normally reads test files in
252 text mode, that is, carriage return characters are stripped. If you do
253 not want carriage return characters removed, you should set the
254 \index{Test file binary}\index{Configuration switches}\agparam{test
255 file binary} configuration switch.
256
257 \subsection{Test File Pane}
258
259 The file under test is displayed in the input pane in the upper right
260 of the \agwindow{File Trace} window. To parse to a specific point in
261 the file, double click at that point. If you double click at a point
262 that precedes the current parse location, the parse will back up to
263 that point. You may also use the cursor keys to control the parse.
264 As long as the parse location and the cursor are synchronized the
265 parse will track the cursor when you move the cursor using the cursor
266 keys.
267
268 If the parse encounters a syntax error, it will not be able to go
269 beyond the location of the error. In this situation, moving the
270 cursor right or down will cause the cursor position to differ from the
271 parse location. The parse and cursor positions can also differ if you
272 single click anywhere in the Test File pane.
273
274 If the parse location and the cursor are thus not synchronized, the
275 \agmenu{Single Step} button will be replaced with a \index{Synch
276 Parse}\agmenu{Synch Parse} button. Click on the \agmenu{Synch Parse}
277 button to get the cursor and the parse back in synch. Of course, the
278 parse will still not be able to proceed past a syntax error.
279
280 In the \agwindow{Test File} pane, you can distinguish text that has
281 been parsed from unparsed text because it is shown in a different
282 color. (The default background color for parsed text is lighter.)
283 Initially no text has been parsed, and the caret is positioned at the
284 beginning of the file. The \index{Parse Location}\agwindow{Parse
285 Location} box at the lower left of \agwindow{File Trace} will show
286 \textit{1:1} for line 1, column 1. The \agwindow{Parse Status} box
287 next to it will say \agmenu{Ready}.
288
289 If your grammar uses semantically determined productions, the parse
290 will halt when one is encountered and the \agwindow{Reduction Choices}
291 pane will be displayed so you may select the appropriate reduction
292 token.
293
294 % XXX index Reload?
295 At any time you can click on the \index{Reset}\agmenu{Reset} button to
296 reset the parse to the beginning of the test file. If you modify the
297 test file, you can click on the \agmenu{Reload} button to load the
298 modified file and reset the parse.
299
300 Normally, AnaGram reads test files in ``text'' mode, discarding
301 carriage return characters. If your parser needs to recognize carriage
302 return characters explicitly, you should turn the \index{test file
303 binary}\agparam{test file binary} configuration switch on.
304
305 \subsection{File Trace Toolbar}
306
307 The File Trace window has a toolbar at the very bottom of the window
308 which provides parse status information as described above and
309 contains buttons to help control the parse. The buttons are as
310 follows:
311
312 \begin{itemize}
313 \item \index{Single Step}\agmenu{Single Step}: Advances the parse one
314 parser action at a time.
315 \item \index{Synch Parse}\agmenu{Synch Parse}: Replaces the \agmenu{Single
316 Step} button when the blinking cursor and the parse location do not
317 coincide. Clicking on the \agmenu{Synch Parse} button will cause the
318 parse to back up to the blinking cursor, if the blinking cursor
319 precedes the parse location, or parse to the blinking cursor
320 otherwise. If the parser encounters a syntax error before reaching
321 the cursor, the parse will stop at the error and the parse will still
322 not be in synch with the cursor.
323 \item \index{Parse File}\agmenu{Parse File}: Parses all the way to the
324 end of file. The parse will not stop until it encounters a syntax
325 error, a semantically determined production, or the end of file.
326 \item \index{Reset}\agmenu{Reset}: Resets the parse to its initial
327 state.
328 \item \index{Reload}\agmenu{Reload}: Reloads the test file from
329 disk. This is useful if you have edited the test file since you last
330 loaded it into the \agwindow{File Trace}.
331 \end{itemize}
332
333
334 \section{Grammar Trace}
335 \index{Grammar Trace}\index{Trace}\index{Window}
336
337 A \agwindow{Grammar Trace} can be selected from either the
338 \agmenu{Action} menu or the \agwindow{Control Panel} toolbar. With
339 it, you can examine the workings of your parser in detail. Using
340 various options, you can set up representations of the
341 \index{Parser state stack}\index{State stack}\index{Stack}parser state
342 stack and parser state as they might appear in the course of execution
343 of your parser. You can then examine the possible inputs and the
344 changes to the state and the state stack caused by any input you
345 choose.
346
347 Several of AnaGram's debugging facilities employ a ready-made
348 \agwindow{Grammar Trace} to direct you to the source of trouble.
349 These are the \agwindow{Conflict Trace}, the \agwindow{Reduction
350 Trace}, the \agwindow{Error Trace}, the \agwindow{Keyword Anomaly
351 Trace}, and the \agwindow{Auxiliary Trace}.
352
353 AnaGram now provides a text entry field where you can enter input text for a
354 \agwindow{Grammar Trace}, in addition to choosing tokens from
355 \agwindow{Allowable Input}. This means
356 you can run a \agwindow{Grammar Trace} like a \agwindow{File Trace}
357 where the test file is replaced by text you can type in. This is a
358 very convenient way to check out your grammar.
359
360 \subsection{Allowable Input Pane}
361 \index{Allowable Input pane}
362
363 The upper right pane of the \agwindow{Grammar Trace} window lists the
364 allowable input tokens for the current state of the grammar. The
365 current state is the state selected by the cursor bar in the
366 \agwindow{Parser Stack} pane.
367
368 The tokens in the \agwindow{Allowable Input} pane are listed in two
369 groups: first, the terminal tokens allowable in this state, and
370 second, the nonterminal tokens. Between these two groups of tokens is
371 inserted a line which is either an option for a default reduction, or
372 declares that there is no default action.
373
374 Double click, press Enter, or click the \agmenu{Proceed} button to
375 parse the highlighted token. When all parse actions triggered by the
376 highlighted token have been completed, all panes of the trace will be
377 redrawn to show the new state of the parser.
378
379 If you wish to see the results of a single parser action, click on the
380 \agmenu{Single Step} button. The parser will perform a single parser
381 action. If the token you selected was not shifted in, it will now be
382 displayed as the lookahead token on the last line, the lookahead line,
383 in the \agwindow{Parser Stack} pane, and will be preselected in the
384 \agwindow{Allowable Input} pane. Because AnaGram, by default, uses a
385 number of compound parser actions, this situation does not arise very
386 often unless you have set the
387 \index{traditional engine}\agparam{traditional engine} switch or reset
388 the \index{default reductions}\agparam{default reductions} switch.
389 Usually you will want to select the same token to proceed, but it is
390 not necessary.
391
392 % XXX the << and >> render really poorly. They should be italic, too,
393 % but I can't get them to set that way.
394 The \agwindow{Allowable Input} pane also displays the parser action
395 associated with a specific token, and its result, provided it is not a
396 compound action. The parser action field for a token may be
397 interpreted as follows: If this token would cause a shift to a new
398 state, the action field is $>>$ followed by the new state number. If
399 the token would cause a reduction, the action field is $<<$ followed
400 by a rule number to show the rule reduced. If the parser action is a
401 compound action, the action field is blank. If the token would cause
402 the grammar to be accepted, the action field is \textit{Accept}.
403
404 If a parser action requires the reduction of a semantically determined
405 production, the \agwindow{Reduction Choices} pane will open. Select a
406 reduction token to continue.
407
408 Note that selecting a token in \agwindow{Allowable Input} can cause a
409 syntax error under certain circumstances. This can happen only if the
410 following conditions are all true:
411
412 \begin{itemize}
413 \item the indicated operation is a reduction,
414 \item the reduction token for the rule being reduced has been used in
415 several different contexts in the grammar,
416 \item and the specified token may follow it in some contexts and not
417 in others.
418 \end{itemize}
419
420 \subsection{Text Entry Field}
421 \index{Text Entry field}
422
423 It is sometimes more convenient to enter text in the text entry field
424 on the \agwindow{Grammar Trace} toolbar than to select individual
425 tokens from the \agwindow{Allowable Input} pane. By entering text you
426 can proceed quickly to the state you want without having to choose
427 each individual token en route.
428
429 After entering text, press Enter or click on the \agmenu{Proceed}
430 button to parse the text. The text will be parsed in its entirety
431 unless a syntax error or semantically determined production is
432 encountered.
433
434 Click on the \agmenu{Single Step} button to work slowly through the
435 text step by step.
436
437 \subsection{Grammar Trace Toolbar}
438
439 The Grammar Trace window has a toolbar at the very bottom of the
440 window which provides parse status information as described above and
441 contains buttons to help control the parse. The buttons are as
442 follows:
443
444 \begin{itemize}
445 \item \index{Proceed}\agmenu{Proceed}: Parses the token selected in
446 \agwindow{Reduction Choices} if that pane is active, or the token
447 selected in \agwindow{Allowable Input} if that pane is active, or the
448 content of the text entry field if that is active. The parse
449 continues until the input has been entirely shifted in, a semantically
450 determined production has been encountered, or a syntax error has
451 been encountered.
452 \item \index{Single Step}\agmenu{Single Step}: Advances the parse one
453 parser action at a time. Input is taken as for the \agmenu{Proceed}
454 button.
455 \item \index{Reset}\agmenu{Reset}: Reset the parse to its initial
456 state. This is especially useful if the \agwindow{Grammar Trace} is
457 one of the pre-built traces discussed below. In such a trace the
458 initial state can be quite complex.
459 \end{itemize}
460
461
462 \section{Other Traces}
463
464 \subsection{Error Trace}
465 \index{Error Trace}\index{Trace}\index{Window}
466
467 An \agwindow{Error Trace} is a preset \agwindow{Grammar Trace}
468 designed to help you deal with errors your parser encounters during
469 operation. If the
470 \index{Error trace}\index{Configuration switches}\agparam{error trace}
471 configuration switch is set when AnaGram builds a parser, whenever the
472 parser detects:
473 \begin{itemize}
474 \item a \index{Syntax error}\index{Errors}syntax error
475 \item a parser stack overflow, or
476 \item a reduction token error
477 \end{itemize}
478 it will write the current state stack to a file with the extension
479 \index{etr}\index{File extension}\agfile{.etr} and the name of the
480 parser file. If such a file already exists, it will be overwritten.
481
482 When you analyze the grammar, AnaGram will enable the \agmenu{Error
483 Trace} option in the \agmenu{Browse} menu. When you select the
484 \agmenu{Error Trace} option, you can select an error trace file.
485 AnaGram will use it to create a grammar trace which reproduces the
486 state of the parser at the time of the error. You may then work with
487 the trace as with any other grammar trace. The \agmenu{Reset} button
488 will restore the trace to its initial condition.
489
490 Note that when the syntax file is modified, an error trace file may
491 become invalid. If you try to load an error trace file that is older
492 than the syntax file, AnaGram will pop up a message box to warn you.
493
494 \subsection{Conflict and Reduction Traces}
495 \index{Conflict Trace}\index{Trace}\index{Window}
496 \index{Reduction Trace}\index{Trace}\index{Window}
497
498 The \agwindow{Conflict Trace} and its companion, the
499 \agwindow{Reduction Trace}, are ready-made \agwindow{Grammar Traces}
500 which can be invoked from a \agwindow{Conflicts} window or a
501 \agwindow{Resolved Conflicts} window using the \agmenu{Auxiliary
502 Windows} menu. The \agwindow{Conflict Trace} shows one way out of
503 perhaps many ways to get to the conflict state highlighted in the
504 \agwindow{Conflicts} window. The \agwindow{Reduction Trace}
505 progresses one step farther than the \agwindow{Conflict Trace},
506 showing the result of selecting a reduce action in the conflict state.
507 You can manipulate both traces just as you would a regular grammar
508 trace. The \agmenu{Reset} button will reset the trace to its original
509 condition.
510
511 \agwindow{Conflict} and \agwindow{Reduction Trace} windows may be
512 obtained only from the \agwindow{Conflicts} window or the
513 \agwindow{Resolved Conflicts} window using the \agmenu{Auxiliary
514 Windows} popup menu. For more information see the section on
515 conflicts in Chapter 7.
516
517 \subsection{Keyword Anomaly Trace}
518 \index{Keyword Anomaly Trace}\index{Trace}\index{Window}
519
520 The \agwindow{Keyword Anomaly Trace} is another ready-made grammar
521 trace which is invoked from a \agwindow{Keyword Anomalies} window
522 using the \agmenu{Auxiliary Windows} popup menu. It shows one way out
523 of perhaps many to get to the anomaly highlighted in the
524 \agwindow{Keyword Anomalies} window. You can manipulate the
525 \agwindow{Keyword Anomaly Trace} in the same way that you would a
526 regular grammar trace. The \agmenu{Reset} button will restore the
527 trace to its original configuration.
528
529 The \agwindow{Keyword Anomaly Trace} may be obtained only from the
530 \agmenu{Auxiliary Windows} popup menu in the \agwindow{Keyword
531 Anomalies} window. For more information see the section on keyword
532 anomalies in Chapter 7.
533
534 \subsection{Auxiliary Trace}
535 \index{Auxiliary Trace}\index{Trace}
536
537 For many AnaGram windows, an \agwindow{Auxiliary Trace} is one of the
538 options on the right mouse button pop up menu. In most cases this is
539 simply a pre-built \agwindow{Grammar Trace} that leads to the state
540 specified by the highlighted line in the window. In the case of the
541 \agwindow{File} and \agwindow{Grammar Traces}, selecting an
542 \agwindow{Auxiliary Trace} from the \agwindow{Parser Stack} pane popup
543 menu gives you a \agwindow{Grammar Trace} with the same
544 \agwindow{Parser Stack} pane as the original \agwindow{Trace}.
545
546 When using a \agwindow{File} or \agwindow{Grammar Trace}, an
547 \agwindow{Auxiliary Trace} can be useful for comparing the results at
548 a particular point of diverging input streams.
549
550
551 \section{Trace Coverage}
552 \index{Trace Coverage}\index{Window}\index{Coverage}
553
554 When you run either \agwindow{File Trace} or \agwindow{Grammar Trace},
555 AnaGram counts the number of times each rule is reduced. You can
556 display these counts by selecting the \agmenu{Trace Coverage} window
557 in the \agmenu{Browse} menu. The window displays all of the rules in
558 your grammar in the order in which they were encountered in your
559 syntax file. The window is synched to your syntax file window so that
560 you can easily see each rule in context. The first column of the
561 table gives the number of times this rule has been reduced by the
562 \agwindow{File Trace} process since you last analyzed your grammar.
563 Note that if, when tracing a file, you back up and try a portion of
564 input over and over, the counts for the rules involved will be
565 inflated relative to the other rules in the grammar. Thus, the
566 primary use of the \agwindow{Trace Coverage} table is to determine
567 whether there are rules that are not tested at all. Because AnaGram
568 normally uses a number of short-cut actions in its parsing tables,
569 some rules will not be counted even though they are obviously found in
570 the grammar. These rules all have length zero or one and have no
571 reduction procedures. If you set the
572 \index{rule coverage}\index{configuration parameters}\agparam{rule coverage}
573 configuration switch, AnaGram will turn off some of the optimization
574 so that you will get a more accurate count.
575 % XXX shouldn't ``found in the grammar'' above be ``found in the input''?