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

comparison doc/misc/html/ftrace.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>AnaGram's File Trace Facility</TITLE>
5
6 </HEAD>
7
8 <BODY BGCOLOR="#ffffff" BACKGROUND="tilbl6h.gif"
9 TEXT="#000000" LINK="#0033CC"
10 VLINK="#CC0033" ALINK="#CC0099">
11
12 <P>
13 <IMG ALIGN="right" SRC="images/agrsl6c.gif" ALT="AnaGram"
14 WIDTH=124 HEIGHT=30>
15 <BR CLEAR="RIGHT">
16 </P>
17
18 <P>
19 Back to <A HREF="index.html">Index</A>
20
21 <IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------"
22 WIDTH=1010 HEIGHT=2 >
23
24 <H2>AnaGram's File Trace</H2>
25 <IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------"
26 WIDTH=1010 HEIGHT=2 >
27
28 <P>
29
30 AnaGram's File Trace facility allows you to try out your
31 grammar interactively on a test file and see how your grammar works
32 <I>before</I> you even build a parser or write code to attach to your
33 grammar rules. You can observe how the
34 parser stack changes as you single-step, fast forward, or back up. You
35 can also view the relationship between elements of the stack, sections
36 of your test file, and your syntax file. If you do not have a test file handy,
37 you may prefer to use <A HREF="gtrace.html"><STRONG>Grammar Trace</STRONG></A>.
38 </P>
39
40 <IMG ALIGN="right" SRC="filetr6d.gif" ALT="sample File Trace window"
41 WIDTH=518 HEIGHT=357 VSPACE=8 HSPACE=8 >
42
43 <BR>
44
45 <H3> Starting File Trace:</H3>
46 <P>
47 File Trace can be selected from either the Action Menu or the Control
48 Panel toolbar once your grammar has been analyzed. A file dialog will
49 be presented to allow you to choose a test file. The files shown in the
50 dialog are determined by the setting of the test file mask
51 configuration parameter, which defaults to *.*.
52 <P>
53 File Trace presents three principal panes: a Parser Stack pane
54 on the left, a Test File pane on the right, and a Rule Stack pane
55 at the bottom.
56 <P>
57 In the Test File pane, you can distinguish text that has been parsed
58 from unparsed text because it is shown in a different color (the
59 default background color for parsed text is lighter). Initially no text
60 has been parsed, and the caret is positioned at the beginning of the
61 file. The Parse Location box at the lower left of File Trace will
62 show 1:1 for line 1, column 1. The Parse Status box next to it will say
63 "Ready".
64 </P>
65
66 <BR>
67
68 <H3> Parsing Through Your Test File:</H3>
69
70 To advance the parse to a desired location, just double-click the left
71 mouse button at that spot in the file. You can also use the cursor
72 keys. Either the Enter key or the single-step button will single-step
73 the parse forward. You will see the changes in the Rule Stack and
74 Parser Stack as your test file characters are shifted in and
75 reductions occur.
76 <P>
77 If there is a syntax error in the test file, the parse will not advance
78 beyond that point and "Syntax error" will appear in the status box.
79
80 <P>
81 When you have parsed the whole test file, the words "Parse complete"
82 will appear in the Parse Status box.
83 <P>
84 Back up the trace to a previous position by double-clicking at the
85 desired location. You
86 can also reset to the beginning with the "Reset" button, or reload the
87 test file with "Reload". To parse the whole file (or up to a syntax
88 error if there is one) just press "Parse File".
89 <P>
90 If the parse position is not the same as the caret position, the
91 "Single Step" button will read "Synch Parse" instead. Pressing this
92 button will move the parse position to the caret; i.e. it will "synchronize"
93 the parse with the caret.
94 <P>
95 As you parse through the test file, you can observe how the Parser
96 and Rule Stacks change. Notice that the Test File, Parser Stack and Rule
97 Stack panes are synched with each other and with your syntax file
98 window. By left-clicking on the stack panes, you can also see which
99 parts of the test file are associated with each level of the stack.
100 </P>
101 <BR>
102
103 <H3> Reduction Choices pane:</H3>
104
105 If your grammar contains any semantically determined productions
106 (those with more than one reduction token on the left hand side),
107 whenever your test file invokes one of them a Reduction Choices
108 pane will appear in the File Trace window to the left of the
109 Rule Stack. When you select a reduction token, the parse will continue.
110 </P>
111 <BR>
112
113 <H3> Further Information:</H3>
114
115 When you run File Trace, AnaGram counts the number
116 of times each rule is reduced. You may inspect these
117 counts by opening the Trace Coverage window.
118 <P>
119 You can have any number of File Traces operating
120 simultaneously. You may also select the Auxiliary
121 Trace window in the Auxiliary Windows popup menu for the Parser Stack pane. It will
122 give you a prebuilt <A HREF="gtrace.html">Grammar Trace</A> with the same parser
123 stack contents as your File Trace. This is convenient if, for example,
124 you wish to see the effect of modifying the test data somewhat.
125 <P>
126 Normally, File Trace reads test files in "text" mode,
127 discarding carriage return characters. If your parser
128 needs to recognize carriage return characters
129 explicitly, you should turn the <STRONG>test file binary</STRONG>
130 configuration switch on.
131 <P>
132 AnaGram uses short-cut parsing actions in some cases. If you wish to
133 see just the standard four actions, you may want to set the
134 <STRONG>traditional engine</STRONG> switch. Then you will notice that you have to
135 press the Single Step or Enter keys more often to advance the parse
136 past the current character.
137
138 <BR>
139 <P>
140
141 <IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------"
142 WIDTH=1010 HEIGHT=2 >
143 <P>
144 <IMG ALIGN="right" SRC="images/pslrb6d.gif" ALT="Parsifal Software"
145 WIDTH=181 HEIGHT=25>
146 <BR CLEAR="right">
147 <P>
148 Back to <A HREF="index.html">Index</A><P>
149 <P>
150 <ADDRESS><FONT SIZE="-1">
151 AnaGram parser generator - documentation<BR>
152 File Trace<BR>
153 Copyright &copy; 1993-1999, Parsifal Software. <BR>
154 All Rights Reserved.<BR>
155 </FONT></ADDRESS>
156
157 </BODY>
158 </HTML>
159
160