═══ 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 (702) 896-7623 (800) 988-9023