Show Program Structure:
A Brief Manual


Table of Contents


Introduction

The Show Program Structure program is intended to help you discover small, but nagging, syntax errors in your programs. Some of these errors cause your program to have different control structures than you think it has, giving it unexpected run-time behavior. Others cause your program to have compilation-time errors, but it is hard to pin-point the source of these errors.

You can also use Show Program Structure to edit your programs and to compile them, but not to run them; however, Xemacs is better at indenting your programs and highlighting Resolve/C++ keywords.


Setup for Use on the CSE Sun Systems

To use Show Program Structure, you must be subscribed to JDK-CURRENT. You can check your subscription, and change it, if necessary, with the "subscribe" command. If there is an asterisk ('*') associated with JDK-CURRENT, then you are subscribed; 'q' <Enter> will exit the "subscribe" program. Otherwise, enter the appropriate number to subscribe to JDK-CURRENT, then press <Enter> ("return") to continue, and 'q' <Enter> 'y' <Enter> to complete the subscription process; then, open a new terminal window to use in the following instructions.

Launching and Using

In a terminal window, type "show-" <Tab> '&' <Enter> to display "show-program-structure &" on the command line and launch Show Program Structure. (You'll see that the program is actually called "jGRASP", but we didn't think that name would do much to attract you toward using this tool.) You can find a file to edit either using the "Browse" tab or a nice open-file dialog box available from "Open File . . ." in the "File" menu of the control panel.

After you have opened a file, you can maximize the editing window. (Of course, you can also maximize the main jGRASP window.) To get the following process to work if your file is not a main program file, you will need to first change each occurrence of "case_select" to "switch" and comment out each line that begins with "#include". Now you can see why you might actually want to go to all this trouble. From the "View" menu of the Edit window, select "Generate CSD". (You may also want to find the "Generate CSD" button on the toolbar.) Note how control structures ("if" and "while" statements together with their bodies) are marked in the left margin. Find one of these statements, and insert a semicolon (';') in the worst possible place, changing, say, "if (large < small)" to "if (large < small);". Generate CSD again to see how this statement is marked now. (By the way, "CSD" means "Control Structure Diagram".) Try removing or inserting a single brace ('{' or '}') and generating CSD to see what happens. (A parse error is noted in "jGRASP Messages"; knowing that a particular file has syntax errors is better than just knowing that a whole program, with all its included files, has them.) Hopefully, these displays will prove helpful to you.

You may want to close your jGRASP edit session without saving the file because jGRASP can disturb some of the indentations that you prefer. Xemacs will continue to respect the indentations that you (and/or we) have already established in the file. Also, you'll probably note that Xemacs is a lot faster at scrolling; jGRASP runs on the Java virtual machine (thus the 'j' in "jGRASP"), and Java's display methods (constituting Swing) are still somewhat slow.

On the other hand, if the indentation and speed issues don't bother you and you wish to use jGRASP to edit and compile your programs, you can. After saving the file, a choice of "Make" from the "Compiler" menu will compile your program. (There is also a "Make" button on the toolbar.) Compilation-time errors will be highlighted in the Edit window. You can click on error messages in the "Compile Messages" window, and the corresponding location in the Edit window will be highlighted. Note that you can remove CSD; this can make editing a bit easier. Also note that "Run" doesn't work because our executables are not named "a.out"; you can run the program from a terminal window (or from xemacs).


Custom Setup (Needed Only When Using jGRASP to Compile Your Programs)

This installation has been configured so that jGRASP can find most of the files that are #included into your program; however, we don't know how correctly to express two important directories: the directory of the current project, and the user's home directory.  To express the directory of the current project, we have used the dot character (the period, point, or full stop ".").  To express the user's home directory, we have used the tilde character, "~".  You may change these to particular values that work for your own account and for your current project.  The following instructions indicate how.

First, you need to learn the current actual path to your account's home directory.  In a terminal window, type "cd" <Enter> "pwd" <Enter> to display this path.  It may look something like "/home/4/leia".

You may or may not be using a personal component catalog, but the compiler is already configured to try and look there.  You can also configure jGRASP to find #included files there; here's how.  In the control panel's "Settings" menu, choose "Global CSD Window Settings . . .".  In the "Languages" tab, make sure the Language chosen is C++.  In the "Environment" sub-tab, select "local: Resolve/C++".  Click on the "Copy" button.  Click on the "Parsing" tab.  Replace the tilde character, "~", with the current actual path to your account's home directory (e.g., "/home/4/leia").  Click the "Save" button.  Click the "OK" button.  With "user: Resolve/C++" selected, click the "Use" button, and notice how the "Current Environment" selection changes.  Click the "OK" button.  Now jGRASP will also look in your personal component catalog (if you set it up and use it) for #included files.

jGRASP may not find all #included files located in your current project's catalog unless you take the following steps.  In the control panel's "Settings" menu, choose "Global CSD Window Settings . . .".  In the "Languages" tab, make sure the Language chosen is C++.  In the "Environment" sub-tab, select "user: Resolve/C++".  Now, here's a difference from the directions given above: click on the "Copy" button.  In the top edit window, change "Copy of Resolve/C++" to the name of your current project, say "Lab02".  Now click on the "Parsing" tab.  Replace the dot character, ".", with the current actual path to your project's directory (e.g., "/home/4/leia/Lab02").  Click the "Save" button.  Click the "OK" button.  With "user: Lab02" selected, click the "Use" button, and notice how the "Current Environment" selection changes.  Click the "OK" button.  Now jGRASP should find all #included files located in your current project's catalog.


Getting Help

Choosing items from the Help menus will result in the default browser (in this case, Netscape) displaying pages in the hypertext help system. Doing so can help you become a better jGRASP user.
Last modified: Thu Jan 31 10:42:32 EST 2008