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

<!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 &copy; 1993-1999, Parsifal Software. <BR>
                  All Rights Reserved.<BR>
</FONT></ADDRESS>

</BODY>
</HTML>
author	David A. Holland
date	Sun, 26 Apr 2009 17:58:26 -0400
parents	13d2b8934445
children