Visual Parse++ for Windows Demo
Tutorial, and Information


Information on SandStone Technology Inc.

If you have any questions, e-mail 71332,2577 on 
CompuServe, 71332.2577@compuserve.com on the 
internet, or call 1-800-988-9023 or 1-702-896-7623.

The online documentation for Visual Parse++ is 
in the 'sspdf.zip' file. It is on the diskette (if
we mailed you the demo) or in another file, usually
in the same forum. Read the 'readpdf.txt' file for
more information.

Starting Visual Parse++

1. Go to the File Manager and open the directory 
you unzipped sswpar.zip in, and double click on 
ssvparse.exe.



Tutorial

1. Click on the Open File button. It looks like 
an open book. An open file dialog is displayed.

2. Select sstutor.ycc and click OK.

3. The sstutor.ycc rule file appears in the window. 
Click on the Compile button in the ribbon bar. It looks 
like a green fire extinguisher.

Rule files are the Visual Parse++ term for the 
specification describing the lexer and/or parser. 
They use a familiar regular expression and 
BNF-like notation. In this case, the rule file 
describes a simple expression  
grammar.

Note the state located above the stack. It says 
Ready showing that the rule file is ready to test.

4. Click on the Open Test File button. It looks 
like a microscope. An open file dialog is displayed.

5. Select sstutor.tst and click OK. The beginning 
of the test file appears in the test data marquee.

You can see exactly where you are in the test file 
at all times. As you step through the test data, it moves 
across the screen from right to left.


6. Click the Step button twice. It looks like a foot.

Note that the position in each regular expression 
is highlighted in red. You can watch the operation 
of your lexical analyzer in great detail, to verify 
that it is behaving as expected. The state is now 
Lexing. Below the test data marquee in the center 
of the screen is the current lookahead symbol, which 
contains an a.

The first Step processed the beginning of file indicator, 
which is required for some, but not most regular 
expressions. It can usually be ignored.

7. Click the Step button until the state is Recognized 
(four more times).

The highlighting accurately matches the current lexeme. 
The state is now Recognized. The current lexeme 
is abcd.

8. Click the Step button. The state is now Shift and 
the stack is updated with the shifted lexeme abcd.

9. Click the Step button twice. The current lexeme 
is white space, which is ignored.

Note the %ignore keyword associated with the regular 
expression. This is one of the many convenient features 
implemented by Visual Parse++. You can ignore things 
like white space with no additional effort. Other 
tools require the application programmer to write code 
for each lexical analyzer to handle this case.

10. Click the Step button two more times. The current 
lexeme is +.

11. Click the Step button. The state is Reducing.

A production is about to be reduced. The production 
is highlighted in the rule file window. The stack 
elements that relate to the reduce (in this case abcd) 
are in reverse video. The reduction is broken down 
into two steps, Reducing and Reduced, so that you 
can see exactly what happens when each production is 
reduced.


12. Click the Step button. The highlighted elements 
on the stack are popped, and the leftside of the 
production, expr, is now on top of the stack. The 
state is now Reduced.

13. Click the Step button. The + is shifted on the stack.

14. Click the Step button twice. This is another 
ignored lexeme (white space).

15. Click the Step button twice. The a has been recognized.

16. Click the Step button. The a is shifted.

17. Click the Step button twice. The end of statement 
lexeme, ;, has been recognized.

18. Click the Step button. A reduction is about to occur.

19. Click the Step button. The reduction is complete.

20. Click the Step button. Another reduction is about to occur.

The advantages of highlighting the stack are more apparent 
in this case, because the production is larger.

21. Click the Step button. The reduction is complete.

22. Scroll to the entry in the %expression list that looks 
like [a-z_A-Z][a-z_A-Z0-9]*   Name, name;.  If you are 
using the mouse, you may have to move the parse stack, 
just drag it out of the way. Make sure the cursor is on 
the line and then click on the Toggle button in the ribbon 
bar. It looks like two blue outward pointing arrows.

The line is highlighted in red to indicate that a 
breakpoint has been set. You can toggle breakpoints on 
and off by placing the cursor on the line and hitting 
the Toggle button.

23. Click on the Run button. It is the magenta silhouette 
that looks like a runner.

Visual Parse++ runs until the expression we set the 
breakpoint on in the previous step is matched. In this 
case, the matching lexeme is xyz. Note the background 
is magenta, indicating that the line has a match plus 
a breakpoint.

24. Scroll to the %production with label ExprMult and 
set a breakpoint by clicking the Toggle button.

25. Click the Run button.

Visual Parse++ runs until the production we set the 
breakpoint on in the previous step is about to be 
reduced.

26. Clear both the breakpoints by putting selecting 
the Breakpoint/Clear menubar selection.

Note that the color changes from magenta to blue, 
because the line no longer contains a breakpoint.

27. Go to the Debug menubar selection and click Animate.

Animate is a combination of Run and Step. You watch 
as the data is processed. A Run or Animate will stop 
if an abnormal condition is detected, even if no 
breakpoints are set. In this case, the Animate will 
terminate when the error is detected.

28. An error has been detected. Click the Step button.

The end (;) token is highlighted in yellow. This 
indicates that the end token is a valid recovery token, 
based on information in the rule file. Visual Parse++ 
will attempt to recover.

29. Click the Step button twice.

The end token has been recognized. Note the color, 
yellow (recovery token) plus blue (match) equals 
green.

30. Click the Step button again. 

Visual Parse++ has recovered. In this case, the 
%error token is shifted on the stack. This is one 
form of error recovery provided by Visual Parse++.

31. Click the Step button. The ; is shifted on the stack.

32. Click the Step button four times.

The production containing the  %error token is 
about to be reduced. The application associated 
with this production can take the appropriate 
action, like issuing an error message.

33. Click the Step button until the data has been Accepted.

34. Show Conflicts.

The following steps show one of the advanced features 
of Visual Parse++. If you are not familiar with the 
terminology, you can skip this part.

To add conflicts to this rule file, add comment 
indicators to the %prec statement and the five following 
statements in the rule file. Rule files use C++ like 
comments. Either start each line with a //, or surround the 
lines with a /*...*/. This removes the precedence 
information from the rule file.

35. Save the file by clicking the Save button on the 
ribbon bar. It looks like a dark blue diskette. 

36. Click on the Compile button. It looks like a 
green fire extinguisher.

A Message Window opens up with messages describing 
the conflicts. Just ignore this window and maximize 
the edit window containing the rule file. You may 
have noticed that the parse stack disappeared. To 
show the stack, select the Window/Show Stack menu 
item. Note the state above the stack now says 
Conflicts.

37. Click the Open Test File button. It looks like a microscope. 

38. Choose ssconfct.tst and click OK. The  contents 
of the file appear in the test data marquee.

39. Click the Run button.

In this case, the Run will terminate when the 
shift/reduce conflict has been detected. The reduce 
production is highlighted in the rule file viewport. 
The shift token causing the conflict is the current 
lookahead token.

Visual Parse++ cant decide whether to shift the * 
or to reduce the expr + expr. Taking the reduce is 
equivalent to performing the addition, but this is 
not what normal operator precedence would dictate. We 
want to shift the *, causing the expr * expr to be 
reduced first. This will happen later.

40. To take the shift, double click anywhere in the 
edit window, except on the highlighted line.

The * is shifted on the stack. To choose the reduce, 
you double click on the line that is highlighted.

41. Continue clicking the Step button until the data 
is accepted.

42. To generate the tables and bindings, select 
Options/Generate Files.


Lookahead Feature

One very useful feature that you will probably use once 
you are familiar with Visual Parse++ is the Debug/Show 
Lookaheads feature. There is also a button on the ribbon 
bar that looks like an eagle that toggles this feature 
on and off. Turning on Show Lookaheads will highlight 
all the valid lookaheads in the rule file window as the 
data is processed. This lets you know what your parser 
is expecting at all times. It may be informative to 
restore the rule file to its original state (by removing 
the comments from the %prec section) and going through 
the tutorial again, this time with Show Lookaheads enabled.

Programming Interfaces

None of the programming interfaces are included in the 
demo. But remember, Visual Parse++ has extensive, 
state-of-the-art support for C, C++, and Visual Basic. 
To order, call 800-988-9023. The price is $299 for a 
limited time.
