Mercurial > ~dholland > hg > ag > index.cgi
diff doc/misc/html/ftrace.html @ 0:13d2b8934445
Import AnaGram (near-)release tree into Mercurial.
| author | David A. Holland |
|---|---|
| date | Sat, 22 Dec 2007 17:52:45 -0500 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/misc/html/ftrace.html Sat Dec 22 17:52:45 2007 -0500 @@ -0,0 +1,160 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> +<HEAD> +<TITLE>AnaGram's File Trace Facility</TITLE> + +</HEAD> + +<BODY BGCOLOR="#ffffff" BACKGROUND="tilbl6h.gif" + TEXT="#000000" LINK="#0033CC" + VLINK="#CC0033" ALINK="#CC0099"> + +<P> +<IMG ALIGN="right" SRC="images/agrsl6c.gif" ALT="AnaGram" + WIDTH=124 HEIGHT=30> +<BR CLEAR="RIGHT"> +</P> + +<P> + Back to <A HREF="index.html">Index</A> + +<IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > + +<H2>AnaGram's File Trace</H2> +<IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > + +<P> + +AnaGram's File Trace facility allows you to try out your +grammar interactively on a test file and see how your grammar works +<I>before</I> you even build a parser or write code to attach to your +grammar rules. You can observe how the +parser stack changes as you single-step, fast forward, or back up. You +can also view the relationship between elements of the stack, sections +of your test file, and your syntax file. If you do not have a test file handy, +you may prefer to use <A HREF="gtrace.html"><STRONG>Grammar Trace</STRONG></A>. +</P> + +<IMG ALIGN="right" SRC="filetr6d.gif" ALT="sample File Trace window" + WIDTH=518 HEIGHT=357 VSPACE=8 HSPACE=8 > + +<BR> + +<H3> Starting File Trace:</H3> +<P> +File Trace can be selected from either the Action Menu or the Control +Panel toolbar once your grammar has been analyzed. A file dialog will +be presented to allow you to choose a test file. The files shown in the +dialog are determined by the setting of the test file mask +configuration parameter, which defaults to *.*. +<P> +File Trace presents three principal panes: a Parser Stack pane +on the left, a Test File pane on the right, and a Rule Stack pane +at the bottom. +<P> +In the Test File pane, you can distinguish text that has been parsed +from unparsed text because it is shown in a different color (the +default background color for parsed text is lighter). Initially no text +has been parsed, and the caret is positioned at the beginning of the +file. The Parse Location box at the lower left of File Trace will +show 1:1 for line 1, column 1. The Parse Status box next to it will say +"Ready". +</P> + +<BR> + +<H3> Parsing Through Your Test File:</H3> + +To advance the parse to a desired location, just double-click the left +mouse button at that spot in the file. You can also use the cursor +keys. Either the Enter key or the single-step button will single-step +the parse forward. You will see the changes in the Rule Stack and +Parser Stack as your test file characters are shifted in and +reductions occur. +<P> +If there is a syntax error in the test file, the parse will not advance +beyond that point and "Syntax error" will appear in the status box. + +<P> +When you have parsed the whole test file, the words "Parse complete" +will appear in the Parse Status box. +<P> +Back up the trace to a previous position by double-clicking at the +desired location. You +can also reset to the beginning with the "Reset" button, or reload the +test file with "Reload". To parse the whole file (or up to a syntax +error if there is one) just press "Parse File". +<P> +If the parse position is not the same as the caret position, the +"Single Step" button will read "Synch Parse" instead. Pressing this +button will move the parse position to the caret; i.e. it will "synchronize" +the parse with the caret. +<P> +As you parse through the test file, you can observe how the Parser +and Rule Stacks change. Notice that the Test File, Parser Stack and Rule +Stack panes are synched with each other and with your syntax file +window. By left-clicking on the stack panes, you can also see which +parts of the test file are associated with each level of the stack. +</P> +<BR> + +<H3> Reduction Choices pane:</H3> + +If your grammar contains any semantically determined productions +(those with more than one reduction token on the left hand side), +whenever your test file invokes one of them a Reduction Choices +pane will appear in the File Trace window to the left of the +Rule Stack. When you select a reduction token, the parse will continue. +</P> +<BR> + +<H3> Further Information:</H3> + +When you run File Trace, AnaGram counts the number +of times each rule is reduced. You may inspect these +counts by opening the Trace Coverage window. +<P> +You can have any number of File Traces operating +simultaneously. You may also select the Auxiliary +Trace window in the Auxiliary Windows popup menu for the Parser Stack pane. It will +give you a prebuilt <A HREF="gtrace.html">Grammar Trace</A> with the same parser +stack contents as your File Trace. This is convenient if, for example, +you wish to see the effect of modifying the test data somewhat. +<P> +Normally, File Trace reads test files in "text" mode, +discarding carriage return characters. If your parser +needs to recognize carriage return characters +explicitly, you should turn the <STRONG>test file binary</STRONG> +configuration switch on. +<P> +AnaGram uses short-cut parsing actions in some cases. If you wish to +see just the standard four actions, you may want to set the +<STRONG>traditional engine</STRONG> switch. Then you will notice that you have to +press the Single Step or Enter keys more often to advance the parse +past the current character. + +<BR> +<P> + +<IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > +<P> +<IMG ALIGN="right" SRC="images/pslrb6d.gif" ALT="Parsifal Software" + WIDTH=181 HEIGHT=25> +<BR CLEAR="right"> +<P> +Back to <A HREF="index.html">Index</A><P> +<P> +<ADDRESS><FONT SIZE="-1"> + AnaGram parser generator - documentation<BR> + File Trace<BR> + Copyright © 1993-1999, Parsifal Software. <BR> + All Rights Reserved.<BR> +</FONT></ADDRESS> + +</BODY> +</HTML> + +