Mercurial > ~dholland > hg > ag > index.cgi
view doc/misc/html/ftrace.html @ 16:f9e4689b837d
Some minor updates for 15 years later.
author | David A. Holland |
---|---|
date | Tue, 31 May 2022 01:45:26 -0400 |
parents | 13d2b8934445 |
children |
line wrap: on
line source
<!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>