OS/2 Shareware BBS: 10 Tools/10-Tools.zip/ssvpar.zip/SSVPARSE.HLP

OS/2 Help File | 1994-11-19 | 24KB | 670 lines

ΓòÉΓòÉΓòÉ 1. General Description ΓòÉΓòÉΓòÉ

Welcome to the Visual Parse++ development system from SandStone Technology. You
are now in possession of the most sophisticated lexical analyzer and parser
generator available. Using this tool will save you countless hours of
programming effort.  You can now take advantage of the power of lexical
analysis and parsing technology for applications you may not have considered
before.  It is a trivial programming task to make anything from simple keyword
file parsers to the most advanced programming language.

The user interface is used to debug your language specification, also known as
a rule file.  It has all the capabilities of modern graphical debuggers such as
stepping through test data and setting breakpoints.  You can see exactly what
is occurring in the lexical analysis and parsing phases at each step.

This guide describes the Visual Parse++ user interface.  It assumes you are
familiar with the information in the Visual Parse++ Programmer's Guide.


ΓòÉΓòÉΓòÉ 2. Main Window ΓòÉΓòÉΓòÉ

The main window consists of 5 areas:

 1. A menu bar.

    See Menu Bar for more information.

 2. A test data area below the menu bar about the height of a status bar. The
    width is the entire window.  It is composed of 3 areas.

   o The left text marquee, which shows text processed by Visual Parse++.

   o An expandable entry field used to enter text.

   o The right text marquee, which shows text about to be processed by Visual
     Parse++.

    See Test Data Area for more information.

 3. An area below the test data area with the height of a status bar and width
    of the entire window.  It has 2 areas of interest.

   o The current lexeme is shown in the center of the window below the entry
     field.

   o A state indicator is located on the right side of the area above the
     stack.

    See Status Area for more information on Visual Parse++ states.

 4. The rule file area occupying the left portion of the window. This contains
    the rule file being tested.

    See Rule File Viewport for more information.

 5. The contents of the parse stack are on the right side of the screen. The
    split bar separating the viewport and stack is moveable.

    See Stack Display for more information.


ΓòÉΓòÉΓòÉ 3. Menu Bar ΓòÉΓòÉΓòÉ

File
 Open
 Refresh
 Exit
Debug
 Open Test File
 Run
 Step
 Animate
 Halt
 Reset
 Set Animate Delay
Breakpoint
 Clear
 Change Token
Options
 Generate Files
 Tab
Help
 General Help
 Keys Help
 Help Index
 Programmer's Guide
 About


ΓòÉΓòÉΓòÉ 3.1. File ΓòÉΓòÉΓòÉ

The file menu is used to open and refresh rule files.  It also has an exit
option.


ΓòÉΓòÉΓòÉ 3.1.1. File/Open ΓòÉΓòÉΓòÉ

Open rule file.  A file dialog is displayed with all the '.ycc' files in the
current directory.  The selected rule file will replace any rule file currently
in use.


ΓòÉΓòÉΓòÉ 3.1.2. File/Refresh ΓòÉΓòÉΓòÉ

Refresh rule file.  The current rule file is refreshed.  This is useful if
changes were made to the rule file (to fix the grammar, for instance). The rule
file is recompiled and displayed in the rule file window.


ΓòÉΓòÉΓòÉ 3.1.3. File/Exit ΓòÉΓòÉΓòÉ

Exit Visual Parse++.


ΓòÉΓòÉΓòÉ 3.2. Debug ΓòÉΓòÉΓòÉ

The debug menu holds the debug options, such as stepping through test data or
animating a test cycle.


ΓòÉΓòÉΓòÉ 3.2.1. Debug/Open Test File ΓòÉΓòÉΓòÉ

Open a test file.  The file dialog is displayed.  The selection becomes the
current test data.  The beginning of the test file is displayed in the right
text marquee.

The associated accelerator key is F2. See Test Data Area for more information
on the right text marquee.


ΓòÉΓòÉΓòÉ 3.2.2. Debug/Run ΓòÉΓòÉΓòÉ

The run option runs through test data until a breakpoint, error, conflict, or
end of file is detected. Typing data in the entry field or selecting Halt from
the Debug menu also interrupts a Run.

The test data used is either data typed in the entry field or an Open Test
File.  If there is both data in the entry field and a test data file,  the
entry field data is used first.  If neither is present,  the Open Test File
file dialog is displayed to get some test data.

The associated accelerator key is F3. See Test Data Area for more information
on the entry field.


ΓòÉΓòÉΓòÉ 3.2.3. Debug/Step ΓòÉΓòÉΓòÉ

The step option single steps through test data.  The Status Area, Rule File
Viewport, and Stack Display are updated with the results of the step.  The data
in the Test Data Area moves across the screen from right to left by 1
character.

The test data used is either data typed in the entry field or a previously
selected Open Test File. If there is both data in the entry field and a test
data file,  the entry field data is used first.  If neither is present,  the
Open Test File file dialog is displayed to get some test data.

The associated accelerator key is F4. See Test Data Area for more information
on the entry field.


ΓòÉΓòÉΓòÉ 3.2.4. Debug/Animate ΓòÉΓòÉΓòÉ

The animate option is a combination of Run and Step.  The data is consumed
until interrupted as in Run and the display is updated after each iteration as
in Step.

The test data used is either data typed in the entry field or a previously
selected Open Test File. If there is both data in the entry field and a test
data file,  the entry field data is used first.  If neither is present,  the
Open Test File file dialog is displayed to get some test data.

The associated accelerator key is F5. See Test Data Area for more information
on the entry field.


ΓòÉΓòÉΓòÉ 3.2.5. Debug/Halt ΓòÉΓòÉΓòÉ

The halt option stops a Run or Animate.

The associated accelerator key is F6.


ΓòÉΓòÉΓòÉ 3.2.6. Debug/Reset ΓòÉΓòÉΓòÉ

The reset option stops a Run or Animate and resets the main window to its
initial state.

The associated accelerator key is F7.


ΓòÉΓòÉΓòÉ 3.2.7. Debug/Set Animate Delay ΓòÉΓòÉΓòÉ

Opens the Set Animate Dialog which displays a slider with which you can select
the animate delay.  The slider range is between 0 and 1 second in 1/10 second
increments.


ΓòÉΓòÉΓòÉ 3.3. Breakpoint ΓòÉΓòÉΓòÉ

The breakpoint menu contains options related to breakpoints.


ΓòÉΓòÉΓòÉ 3.3.1. Breakpoint/Clear ΓòÉΓòÉΓòÉ

Clear removes all breakpoints from the rule file area. See Rule File Area for
more information on setting breakpoints.


ΓòÉΓòÉΓòÉ 3.3.2. Breakpoint/Change Token ΓòÉΓòÉΓòÉ

Change token is used to alter the token when Visual Parse++ is in the
Recognized state.  The main use of this option is for applications that may
need to alter a token after it has been recognized but before it is passed to
the parser.  Normally, this would be done in the application code (as in a
symbol table lookup). This is the way to simulate this behavior with the
debugger.

The C language typedef problem is a typical use for this option.  When a token
is recognized, the lexer can't determine if it is a name or a typedef.  In the
application code, there will be some logic, probably a table lookup, for
resolving this dilemma.  But in the debugger, you need this option to manually
change the token.

See Status Area for more information on Visual Parse++ states.


ΓòÉΓòÉΓòÉ 3.4. Options ΓòÉΓòÉΓòÉ

The options menu contains display and file generation options.


ΓòÉΓòÉΓòÉ 3.4.1. Options/Generate Files ΓòÉΓòÉΓòÉ

This option starts the Generate Files dialog.  Use this selection after you
have tested your rule file and need to generate the language bindings or other
information files for you application. See Generate Files for more information.


ΓòÉΓòÉΓòÉ 3.4.2. Options/Tab ΓòÉΓòÉΓòÉ

The tab option allows you to set the tab amount if hard tabs ('\t') characters
are used in the rule files.  The default tab amount is 3.


ΓòÉΓòÉΓòÉ 3.5. Help ΓòÉΓòÉΓòÉ

The help menu is used to select the help options.


ΓòÉΓòÉΓòÉ 3.5.1. Help/General Help ΓòÉΓòÉΓòÉ

Displays the Visual Parse++ User's Guide (this guide).


ΓòÉΓòÉΓòÉ 3.5.2. Help/Keys Help ΓòÉΓòÉΓòÉ

Displays the help describing the accelerator keys that can be used.


ΓòÉΓòÉΓòÉ 3.5.3. Help/Help Index ΓòÉΓòÉΓòÉ

Displays the help index.


ΓòÉΓòÉΓòÉ 3.5.4. Help/Programmer's Guide ΓòÉΓòÉΓòÉ

Displays the Visual Parse++ Programmer's Guide.


ΓòÉΓòÉΓòÉ 3.5.5. Help/About ΓòÉΓòÉΓòÉ

Displays information about SandStone Technology and this product.


ΓòÉΓòÉΓòÉ 4. Test Data Area ΓòÉΓòÉΓòÉ

The test data area (directly below the Menu Bar) contains a visual indication
of your data being tested. The data moves from the right side of the window to
the left as it is consumed.  The data on the right side of the entry field is
about to be processed by Visual Parse++.  When it passes the entry field, it is
consumed by Visual Parse++, and the results are dispalyed in the Rule File
Viewport and Stack Display.

The entry field is used to enter test data.  Just enter the data in the field
and use the debug options Step or Run.  The split bars bounding the entry field
are moveable, allowing expansion of the field.  Entering data in the field will
interrupt a Run or Animate.

You can use the Menu Bar Debug options to select a test file for processing.
The beginning of the test file is displayed to the right of the entry field.
Any data in the entry field is consumed first.


ΓòÉΓòÉΓòÉ 5. Status Area ΓòÉΓòÉΓòÉ

Description
States
 Ready
 Compiling
 Running
 Lexing
 Recognized
 Shift
 Reducing
 Reduced
 Error
 Recovering
 Recovered
 RecoveryFailed
 Conflicts
 ShiftReduce
 AcceptReduce
 Accept


ΓòÉΓòÉΓòÉ 5.1. Description ΓòÉΓòÉΓòÉ

The status area (directly below the Test Data Area) shows the current lexeme
and the Visual Parse++ state.

The current lexeme is in the middle of the area (below the entry field) and
highlighted in green if the lexeme is Recognized.


ΓòÉΓòÉΓòÉ 5.2. States ΓòÉΓòÉΓòÉ

There are different states that Visual Parse++ may be in during the lexing and
parsing process.  The current state is provided on the right side of the window
above the stack.


ΓòÉΓòÉΓòÉ 5.3. Ready ΓòÉΓòÉΓòÉ

A rule file is open in the Rule File Viewport and Ready to test.  This state is
also reached when you select Reset from the Debug menu.


ΓòÉΓòÉΓòÉ 5.4. Compiling ΓòÉΓòÉΓòÉ

A rule file is being prepared for processing. You selected Open or Refresh from
the File menu or supplied a rule file name on the command line.


ΓòÉΓòÉΓòÉ 5.5. Running ΓòÉΓòÉΓòÉ

Run was select from the Debug menu. A run will terminate when an error occurs,
a breakpoint is hit, or Halt is selected from the Debug menu.


ΓòÉΓòÉΓòÉ 5.6. Lexing ΓòÉΓòÉΓòÉ

The lexical analyzer is processing a character. All matching %expression list
entries are highlighted in the Rule File Viewport. The position in each
matching regular expression is highlighted in red .


ΓòÉΓòÉΓòÉ 5.7. Recognized ΓòÉΓòÉΓòÉ

The lexical analyzer has recognized the token.  The matching %expression list
entry is highlighted in the Rule File Viewport.  The current lexeme is changed
to green.


ΓòÉΓòÉΓòÉ 5.8. Shift ΓòÉΓòÉΓòÉ

The current lexeme was shifted on the stack.  The Recognized lexeme is pushed
on top of the Stack Display.


ΓòÉΓòÉΓòÉ 5.9. Reducing ΓòÉΓòÉΓòÉ

Visual Parse++ has recognized a production and is about to reduce. The entry in
the %production list is highlighted in the The Rule File Viewport. The
associated symbols on the stack are highlighted on the Stack Display.


ΓòÉΓòÉΓòÉ 5.10. Reduced ΓòÉΓòÉΓòÉ

Visual Parse++ has reduced a production. The highlighted symbols in the Stack
Display are popped off the stack.  The production leftside symbol is pushed on
the top of the Stack Display.


ΓòÉΓòÉΓòÉ 5.11. Error ΓòÉΓòÉΓòÉ

Visual Parse++ has detected an error while processing the test data.

If the error was detected in the lexical analysis phase, the invalid lexeme is
highlighted in red.  If you continue, (via Step, Animate, or Run) the lexeme is
discarded.

If the error is detected by the parser, Stepping will transition Visual Parse++
into either the Recovering state or the RecoveryFailed state.


ΓòÉΓòÉΓòÉ 5.12. Recovering ΓòÉΓòÉΓòÉ

Visual Parse++ is attempting to recover from the parsing error.  This is what
happens:

 1. All valid %expression list entries are highlighted. The valid tokens are
    tokens that can follow a synchronization token (%) or an %error token as
    explained more fully in the Visual Parse++ Programmer's Guide in the Error
    Recovery section.

 2. Visual Parse++ continues Lexing data until one of the valid tokens is
    reached (you watch this process as you would the normal lexing process), or
    until end of data.

 3. If a valid token is located, Visual Parse++ enters the Recovered state and
    normal parsing proceeds.

 4. If end of data is reached, Visual Parse++ could not recover.


ΓòÉΓòÉΓòÉ 5.13. Recovered ΓòÉΓòÉΓòÉ

Visual Parse++ has recovered from the parsing error.


ΓòÉΓòÉΓòÉ 5.14. RecoveryFailed ΓòÉΓòÉΓòÉ

Visual Parse++ could not recover from the parsing error.

If Visual Parse++ enters the RecoveryFailed state, you must select Reset from
the Debug menu to restart the process.


ΓòÉΓòÉΓòÉ 5.15. Conflicts ΓòÉΓòÉΓòÉ

Visual Parse++ has detected a conflict in the rule file.  You can test a rule
file with conflicts.  If a conflict is detected, Visual Parse++ will enter
either the ShiftReduce or ReduceReduce state.  In all other respects, this
state is equivalent to Ready.

Conflicts are discussed in the Visual Parse++ Programmer's Guide in the
Ambiguities section.


ΓòÉΓòÉΓòÉ 5.16. ShiftReduce ΓòÉΓòÉΓòÉ

Visual Parse++ has detected a shift/reduce conflict.  The conflicting
%production entries are highlighted in the Rule File Viewport. The shift is
highlighted in the darker shade of cyan.  You must resolve the conflict by
selecting a production with a mouse click.


ΓòÉΓòÉΓòÉ 5.17. ReduceReduce ΓòÉΓòÉΓòÉ

Visual Parse++ has detected a reduce/reduce conflict.  The conflicting
%production entries are highlighted in the Rule File Viewport. You must resolve
the conflict by selecting a production with a mouse click.


ΓòÉΓòÉΓòÉ 5.18. AcceptReduce ΓòÉΓòÉΓòÉ

Visual Parse++ has detected an accept/reduce conflict.  The conflicting
%production entries are highlighted in the Rule File Viewport. The accept is
always the only choice in this case, so to continue, select Reset from the
Debug menu.


ΓòÉΓòÉΓòÉ 5.19. Accept ΓòÉΓòÉΓòÉ

The test data has been accepted. This also Resets Visual Parse++.


ΓòÉΓòÉΓòÉ 6. Rule File Viewport ΓòÉΓòÉΓòÉ

The rule file viewport displays the current rule file.  As you Step through or
Animate test data,  the rule file viewport is updated with a visual indication
of what just occurred.

The Status Area section describes what occurs in this viewport as Visual
Parse++ processes your test data.

The rule file viewport is used to set breakpoints. A single mouse click on
either an entry in a %expression or %production list toggles the breakpoint on
and off.  The line is highlighted in red when a breakpoint is set.

A breakpoint interrupts a Run or Animate.  If you set a breakpoint in an
%expression list, the breakpoint is triggered when the test data matches the
regular expression (when in the Recognized state).  In a %production list, the
breakpoint is taken when the rule is about to be reduced (when in the Reducing
state).


ΓòÉΓòÉΓòÉ 6.1. Color Summary ΓòÉΓòÉΓòÉ

There are several attributes that can be associated with each line in the rule
file viewport. The background color depends on the attributes attached to the
line. The following is a list of attributes:

Match               A regular expression or production has been matched.

Recover Token       The expression is a valid recovery token.

Breakpoint          A breakpoint is set.

Conflict            A conflict has beed detected.

These are the colors used by Visual Parse++.

Blue                An %expression list match or %production reduction is
                    highlighted in blue.

Yellow              Recovery tokens are highlighted in yellow.

Red                 Breakpoints are highlighted in red.

Green               The Match + Recovery Token combination is highlighted in
                    green.

Magenta             The Match + Breakpoint combination is highlighted in
                    magenta.

Brown               The Recovery Token + Breakpoint combination is highlighted
                    in brown.

Dark Gray           The Match + Recovery Token + Breakpoint combination is
                    highlighted in dark gray. This color can also indicate if a
                    line has the current focus.

Cyan                Conflicts are highlighted in cyan or dark cyan. Dark cyan
                    distinguishes the shift in a shift/reduce conflict.


ΓòÉΓòÉΓòÉ 7. Stack Display ΓòÉΓòÉΓòÉ

The stack display shows the parsing stack.  Each entry has the following
information:

 1. A symbol, either a terminal (token) or nonterminal. Nonterminals are
    italic.

 2. The state.

 3. If this is a nonterminal entry, the production label associated with the
    nonterminal is displayed.

When Visual Parse++ is in the Reducing state,  the symbols in the production
about to be reduced are highlighted in dark gray.


ΓòÉΓòÉΓòÉ 8. Generate Files ΓòÉΓòÉΓòÉ

Description
General
Lex
Yacc


ΓòÉΓòÉΓòÉ 8.1. Description ΓòÉΓòÉΓòÉ

The generate files notebook is used to generate the header files, tables, and
other information files you need to develop your application.

There is a one-to-one correspondence between the Generate Files notebook and
the command line options on the SSPARSE and SSVPARSE commands. See the Visual
Parse++ Programmer's Guide for more information on the SSPARSE and SSVPARSE
command line options.

Each option has 2 parts, a check box which activates or deactivates the option,
and an entry field which contains the option data, usually a name of some sort.

After you have filled in the notebook or accepted the defaults, select the
Generate button to generate the files.


ΓòÉΓòÉΓòÉ 8.2. General ΓòÉΓòÉΓòÉ

The general options are:

   Field               Description

   C file              The C header file name. Corresponds to the /C command
                       line option.

   C++ file            The C++ header file name. Corresponds to the /Cpp
                       command line option.

   Rexx file           The REXX file name. Corresponds to the /Rx command line
                       option.

   Symbol file         The symbol file name. Corresponds to the /Fs command
                       line option.


ΓòÉΓòÉΓòÉ 8.3. Lex ΓòÉΓòÉΓòÉ

The lex options are:

   Field               Description

   Table               The lexical analyzer table name.  Corresponds to the /Lt
                       command line option.

   Class or prefix     The SSLex derived class name.  Corresponds to the /Lc
                       command line option. For C, the name is used as a prefix
                       for functions related to the lexical analyzer. For REXX,
                       the name is used as a prefix for variables and function
                       related to the lexical analyzer.

   Prefix              The lex token prefix.  Corresponds to the /Lp command
                       line option.

   Machine             The lex machine file name. Corresponds to the /Lm
                       command line option.

   Expression List Prefix The lex expression list prefix. Corresponds to the
                       /Le command line option.


ΓòÉΓòÉΓòÉ 8.4. Yacc ΓòÉΓòÉΓòÉ

The yacc options are:

   Field               Description

   Table               The parser table name.  Corresponds to the /Yt command
                       line option.

   Class or prefix     The SSYacc derived class name.  Corresponds to the /Yc
                       command line option. For C, the name is used as a prefix
                       for functions related to the parser. For REXX, the name
                       is used as a prefix for variables and functions related
                       to the parser.

   Prefix              The production prefix.  Corresponds to the /Yp command
                       line option.

   Machine             The yacc machine file name. Corresponds to the /Ym
                       command line option.


ΓòÉΓòÉΓòÉ 9. Keys Help ΓòÉΓòÉΓòÉ

The following list shows the accelerator keys for Visual Parse++.  Each key is
equivalent to a menubar selection.

 Key       Function

 F2        Debug/Open Test File

 F3        Debug/Run

 F4        Debug/Step

 F5        Debug/Animate

 F6        Debug/Halt

 F7        Debug/Reset


ΓòÉΓòÉΓòÉ 10. About ΓòÉΓòÉΓòÉ

Copyright (C) 1994 SandStone Technology Inc.
       All rights reserved

For sales, technical support, or other information, call or write:

SandStone Technology Inc.
70 Tidwell Lane
Henderson, NV 89014
[phone]
[phone]