9.6 Project Scripts

Scripts are an important component of a simulation, especially when things get a bit more complicated than a simple XOR example. They allow you to perform routine actions automatically, which can save a lot of mouse clicks, and makes some things possible that would be prohibitively time-consuming to do by hand (e.g., switching one's environment to use -1 to +1 values instead of 0 to 1 values). Since scripts can be created just by recording actions taken in the GUI, it is relatively easy to get started with them.

A PDP++ Project contains a special place to put different scripts that are associated with a given project. Thus, there is a Script object, which has a corresponding script file that contains CSS script code (see section 7 Guide to the Script Language (CSS)). These Script objects provide a way of managing and running multiple different CSS script files, whereas the script window that is present at startup can only hold one script file at a time.

The script objects are found in the .scripts group on the project. Editing a Script object results in a little "control panel" with several buttons that manipulate the script in different ways. An existing script can also be run directly by selecting that script from the Run menu of .scripts.

The Script object has the following member fields:

taFile script_file
This contains the name of the script file to associate with this object. The name field of the object will automatically reflect the name of the script file selected (minus the .css extension). Note that the script file can be edited by using the Edit menu option, which pulls up the editor given by the EDITOR environmental variable.
String script_string
You can enter an entire script in this string field, and run it instead of reading the script from the script_file. If script_string is non-empty, it is used instead of the file, even if the file is open.
bool auto_run
Check this option if you want the script to be run automatically when the project is loaded. This is can be used for example to automatically build and connect a large network which is saved without units or connections to make things faster and the file smaller. An example script which builds the network is `css/include/build_network.css'. If you startup the pdp++ program with the project name on the command line, then the project will load over and over again if there is an error with a script that is set to run upon loading the project using auto_run. The solution is to load the project from the Root menu, and to immediately move the mouse over the xterminal window, and type a Return into that window when the error occurs. Then, you can debug the problem with the script at the point where the error occurred.
String_Array s_args
These are arguments that the script file can access. The argument values can be set in the script object, and used to modify the way the script behaves, etc. Scripts that use these arguments should have the meaning of the arguments documented near the top of the script file.

The following button actions are available in the edit dialog of the Script object:

Run()
This runs the script. A script must already be loaded and compiled.
Record()
This causes future GUI actions to be recorded to this script. Thus, one can construct a script record of a series of gui actions, and play them back by compiling the resulting script, and running it. The script file can be edited and, for example, a for loop wrapped around a set of actions to perform them multiple times, etc.
StopRecording() (StopRec)
This stops the recording of GUI actions to this script. Only one script can record at a time, so if you press Record on a script, then all others will automatically stop recording.
Interact()
This allows you to interact with the script through the CSS shell window (the one you started the PDP++ program from). The prompt will change to the name of the script you are working with. All of the CSS commands can then be used to debug and run the script (see section 7 Guide to the Script Language (CSS)). Note that to exit out of this css shell, you do a quit in CSS, which will bring you back to the initial PDP++ executable prompt.
Clear()
This clears (empties out) the script file. This cannot be undone, so make sure you are ok losing all of the stuff in the script file! It is primarily used when recording scripts, when you want to start over from the beginning.
Compile()
This will re-compile the script file. Any time you make changes to the .css file associated with the Script object, these changes need to be re-interpreted by CSS into something that can actually be run (see section 7.2.1 Running an Example Program in CSS).

There are a number of useful script files in the `css/include' directory of the PDP++ distribution. These files contain documentation as to what they do.