view doc/misc/html/gtrace.html @ 8:ec2b657edf13

Add explicit lint-comment-style fallthrough annotations. GCC now assumes that if you don't have these you're making a mistake, which is annoying. XXX: This changeset updates the AG output files only (by hand) and is XXX: abusive - rebuilding them will erase the change. However, I need XXX: to get things to build before I can try to get AG to issue the XXX: annotations itself, so this seems like a reasonable expedient.
author David A. Holland
date Mon, 30 May 2022 23:51:43 -0400
parents 13d2b8934445
children
line wrap: on
line source

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>AnaGram's Grammar 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 Grammar Trace</H2>
<IMG ALIGN="bottom" SRC="images/rbline6j.gif" ALT="----------------------"
      WIDTH=1010 HEIGHT=2 >

<P>

The Grammar Trace facility lets you examine the workings of your
parser in detail, <ITALIC>interactively</ITALIC>. You can use Grammar Trace even
<ITALIC>before</ITALIC> you
write any code to attach to the rules of your grammar, and before actually
building a parser. If you have a test file available, you may prefer to use <A
HREF="ftrace.html"><STRONG>File Trace</STRONG></A>.
<P>
Using the various options associated with this trace
you can set up a representation of the parser state stack and parser
state as they might appear in the course of execution of your
parser. You can then examine the allowable input tokens and the
changes to the state and the state stack caused by any input tokens you
choose.

<IMG ALIGN="right" SRC="gramtr6g.gif" ALT="sample Grammar Trace window"
      WIDTH=489 HEIGHT=338 VSPACE=8 HSPACE=8 >


<P>
AnaGram now provides a combo box where you can enter input characters
for a Grammar Trace, in addition to choosing tokens. This means you can
run a Grammar Trace like a <A
HREF="ftrace.html">File Trace</A> where the test file is replaced
by the combo box characters you type. This is a very convenient way
to check out your grammar.
</P>

<BR>

<H3>  Starting Grammar Traces:</H3>

A Grammar Trace can be selected from either the Action Menu or the
Control Panel toolbar once your grammar has been analyzed. There are
also prebuilt grammar traces like the Conflict Trace and the
Auxiliary Trace, which can be selected from the Auxiliary Windows
popup menu for certain AnaGram windows or panes.
<P>
Like File Trace, a Grammar Trace presents three principal panes. These
are a Parser Stack pane on the left, an Allowable Input pane on the
right, and a Rule Stack pane at the bottom.
<P>
Initially, the Parser Stack will consist of a single line, which
represents the initial configuration of your parser. The first column
will show zero, which is the value of the parser stack
index. The second column will show the state number of the parser,
initially S000. The third column of the Parser Stack, which shows the
token seen at that state, is initially blank. The Rule Stack will
likewise be at level 0, state 000.  The active pane of the Grammar
Trace will be the Allowable Input pane, ready for you to choose a
token.
<BR>

<H3>  Using Grammar Trace </H3>

At any stage, the Parser Stack pane represents a parse
in progress. It shows the sequence of tokens that have
been input so far and the states in which they were
seen. When a production is complete and the grammar rule
is reduced, the tokens that make up the rule are removed
from the stack and replaced by the token on the left
side of the production. The Rule Stack pane shows you all
the grammar rules that are currently active
at any level in the stack.
<P>

To explore your grammar, choose a token from the Allowable Input
pane.  This pane shows the tokens allowable at the current state of the
grammar, and the actions that result when the tokens are chosen.
The Action field for each token shows whether it
would cause a shift or a reduction, and the new state or the rule
reduced. It is blank if the parser action is a compound action.

<P>
Select a token by double-clicking it with the left mouse button or by
positioning the cursor bar on the token and pressing Enter.
Then the Parser Stack and Rule
Stack will be modified to reflect the input choice you made.  Note
that the panes in the Grammar Trace window are synched with each
other and also with your syntax file window if it is on-screen. The
Rule Stack is particularly useful for seeing the relationship between
the Parser Stack contents and your grammar.

<P>
You may now continue stepping through your grammar. At any time, as an
alternative to choosing tokens in the Allowable Input pane, you may
type text in the combo box at the bottom of the Grammar Trace
window and either press Enter or select the Proceed button to parse
the text. The Single Step button will accept the combo box input one
step at a time if the combo box is active, or the highlighted token
if Allowable Input is active.

<P> You can back up the parse by
moving the cursor bar in the Parser Stack window to the desired level
and double-clicking the highlighted token in Allowable Input. You can
reset the trace to the beginning with the Reset button.

<P>
If you are using semantically determined productions, a Reduction
Choices pane will appear to the left of the Rule Stack when it is
time to reduce such a production. Select the desired reduction token
from the pane before continuing with the parse.

<P>
All Grammar Trace activity updates the trace coverage counts.
<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>
<ADDRESS><FONT SIZE="-1">
                  AnaGram parser generator - documentation<BR>
                  Grammar Trace<BR>
                  Copyright &copy; 1993-1999, Parsifal Software. <BR>
                  All Rights Reserved.<BR>
</FONT></ADDRESS>

</BODY>
</HTML>