Visual Parse++ Demo Version
Copyright (c) 1994 SandStone Technology Inc.
(800) 988-9023 or (702) 896-7623
Compuserve: 71332,2577
Internet: 71332.2577@compuserve.com

The demo version has been updated to include the programming 
interfaces. You can now write small complete examples in C,
C++, or REXX. We added the programming interfaces because of
numerous requests by users. You are still limited to 32 regular
expressions and 32 productions.

The demo version of Visual Parse++ is different from the production version
in the following ways:

1. The demo version will except 32 regular expressions for developing a
   lexical analyzer and 32 productions in a grammar.  There are no limits
   in the production version.
2. Not all the rule files are distributed.  For instance, there is a Modula 2
   rule file and an IPF rule file that are only in the production version.
   These are complete, prebuilt lexical analyzers and parsers.
3. There are complete applications like a command line parser and
   a validator application, both with C and C++ interfaces, that are
   not provided.

The are 2 make files that you can use to compile the small
calculator example included with the demo. The names are all
prefixed with 'sscalc'. The make file for IBM C/Set++ is 
'sscalcio.mak', and for Borland C++ 1.5, it is 'sscalcbo.mak'.
They both generate 2 'exe' files, 'sscalcc' (the C version)
and 'sscalccc' (the C++ version). There is also a REXX version
called 'sscalcrx'. They all accept an expression on the command
line ending in a semicolon, like '2+3*4;'. The value is printed
as a decimal and hexidecimal number. You can use these makefiles
and examples to build your own applications.



This file contains a 15-30 minute tutorial to familiarize 
yourself with Visual Parse++. It is the same information included 
in Chapter 1 of the Visual Parse++ Guide and Reference, which is 
not included in the demo.

There are 2 online manuals, both included in the demo version. They
are the Visual Parse++ Programmer's Reference (ssparse.inf), and the 
Visual Parse++ User's Reference (ssvparse.inf). Use the VIEW command
to examine these files. You can also access both of these documents
from the Help menubar selection.


Starting Visual Parse++:

1. From the directory where you unzipped Visual Parse++, 
   enter SSVPARSE. 

   If Visual Parse++ does not start, look in 'ssvparse.out'. 
   The most likely cause of the error is not having the '.' 
   directory in LIBPATH. Try issuing the command 
   'sssetprf BinDirectory currentdir', where the current directory
   is the Visual Parse++ directory (BinDirectory is case sensitive),
   and reissue the command.

Running Visual Parse++ Example:

1. Click on the File menu bar selection and choose Open.
   An open file dialog is displayed.

2. Select "sstutor.ycc" and click OK.

3. The "sstutor.ycc" rule file appears in the window.

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 directly above the stack.  It says
"Ready" showing that the rule file is ready to test.

4. Press the F2 key (Debug/Open Test File). The 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.  The area to the right of the edit
field is data that is waiting to get processed by Visual
Parse++. The data to the left of the edit field has been
processed by Visual Parse++.

You can expand the edit field by moving the split bars on
either side if you wish to enter data in the middle of the
current stream.  Any data entered in the edit field is
processed next.

6. Press F4 (Debug/Step). The "a" is a match for the
   regular expressions highlighted.

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
edit field is the current lexeme, which contains an "a".

7. Press F4 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" and
is highlighted in green.

8. Press F4. The state is now "Shift", and the stack is
   updated with the shifted lexeme "abcd".
9. Press F4 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. Press F4 two more times. The current lexeme is "+" and
    is highlighted in green.

11. Press F4. 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. Press F4.  The highlighted elements on the stack are
    popped, and the leftside of the production, "expr" is
    now on the top of the stack. The state is now
    "Reduced".

The italics on the stack indicate that the element is a
nonterminal.

13. Press F4. The "+" is shifted onto the stack.

14. Press F4 two more times.  This is another ignored
    lexeme (white space).

15. Press F4 twice. The "a" has been recognized.

16. Press F4. The "a" is shifted.

17. Press F4 twice. The end of statement lexeme, ";", has
    been "Recognized".

18. Press F4. A reduction is about to occur.

19. Press F4. The reduction is completed.

20. Press F4. Another reduction is about to occur.

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

21. Press F4. The reduction is complete.

We will now show how to set a breakpoint.

22. Using your mouse, scroll up to the entry in the
    %expression list that looks like
    "[a-z_A-Z][a-z_A-Z0-9]* Name, name;". Click once on
    this line.

The line is highlighted in red to indicate that a breakpoint
has been set.

23.Press F3 (Debug/Run).

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 that the background is
magenta, indicating that the line has a match plus a
breakpoint.

24. Scroll down using the mouse to the production with
    label "ExprMult". Click once on this line to set the
    breakpoint.

25. Press F3.

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

26. Go to the Breakpoint menubar selection and choose
    Clear.

This clears all the breakpoints. Note the color change from
magenta to blue, because the line no longer contains a
breakpoint.

27. Press F5 (Debug/Animate).

Animate is a combination of Run and  Step. You can watch as
the data is processed. This particular instance will stop
when the error is detected is detected. 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.

30. An error has been detected. Press F4 (Debug/Step).

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.

31. Press F4 three times.

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

32. Press F4 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++.

33. Press F4. The ";" is shifted onto the stack.

34. Press F4 three times.

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

35. Continue pressing F4 until the file has been Accepted.
    You will here a beep.

36. 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 to step 43.

To add conflicts to this rule file, use your favorite editor
and add comment indicators, "//", to the %prec statement and
the five following statements in file 'sstutor.ycc'. This 
removes the precedence information from the rule file. Be 
sure to save the file.

37. Go back to Visual Parse++, and select the File menu bar
    selection and choose Refresh.

The new rule file appears in the window in the "Conflicts"
state. This shows that the rule file contains conflicts.
Visual Parse++ allows you to test a file with conflicts. This
can be very useful for gaining intuition into what is causing
the conflict, and repairing the conflict. In all other
respects, the "Conflicts" state is equivalent to "Ready".

38. Use the mouse to expand the edit field in the test data
    marquee by dragging either of the split bars that
    separate the fields.

Dragging the split bar is just like dragging a window border.

39. Enter "a + ab * a;" into the edit field.

40. Press F3 (Debug/Run).

A Run will terminate when an abnormal condition results (like
a shift/reduce conflict), when the data is accepted, or if
you press F6 (Debug/Halt).

In this case, a shift/reduce conflict on the "*" token will
halt the run. The shift is indicated with the darker shade of
cyan.

Visual Parse++ cannot 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" production to be reduced first. This will
happen later.

41. To take the shift, click once on the production with
    the darker shade of cyan.

The "*" is shifted on the stack.

42. Continue pressing F4 until the data is accepted.

43. Go to the Options menu bar selection and choose
    Generate Files.

This starts the generate files dialog.  After you have tested
your rule file, you need to generate the tables and bindings
so you can write your application.

44. In the Set General Options notebook page, click on the
    C file, C++ file, and REXX file check boxes.

This will generate the C, C++, and REXX bindings. The file
names can be overridden by editing the field next to the
check boxes if desired, but the defaults should be fine. You
can look in the Lex and Yacc pages if you wish, but the
defaults should be satisfactory there as well.

45. Click the Generate button.

The files are written to disk.

You are now finished! You can write your application
according to the directions in the Visual Parse++ Guide and
Reference.




SandStone Technology Inc.
70 Tidwell Lane
Henderson NV, 89014

(800)988-9023 (Voice)
(702)896-7623 (Voice)
(702)896-6932 (Fax)
