Chapter 3: continued

Editing a UserTalk Script

As we saw in the previous chapter, Frontier scripts are edited as outlines. Use tab to indent a line and shift-tab to move it back. Double-click on the item marker on the left to expand or contract any lines that are at a lower "level" -- i.e. indented underneath. Click on the item marker to select a line at the lowest level (i.e. with no lines indented underneath). Cut, copy and paste work as expected. Click to select a line at a higher level; cut, copy and paste now work on the whole "block". Click on a "summit" line (i.e. one that is at the far left), choose "Select All" from the edit menu, then copy; you will get the entire script. These basics should get you started; the outline-based editor is covered in more detail in Chapter 7, The Frontier Environment.

Indentation is used to group UserTalk statements. For example, here's a simple "if" statement, properly formatted:

This script fragment looks at a variable called answer. If it holds a value of 6 or larger, the script displays one message; if the number is less than 6, it displays a different message. Note that Frontier uses the "greater than or equal to" sign; you can type it by holding Option and pressing the comma key, much like Shift and comma will type the "greater than" sign. This example shows one line indented under "if" and one under "else"; UserTalk supports any number of lines in either block.

When a block includes multiple lines, it's often convenient to collapse them to hide the detailed behavior. Users who don't want or need to understand detailed levels of processing in a script can look only at the level in which they're interested. Comments can summarize the result of the actions that are hidden. Here is the same script fragment, collapsed and with added comments:

Here's a simple "for" loop, properly formatted:

Only the second line, window.msg (i), is indented under the "for" loop header, so it's the only line that gets executed 100 times. Note that window.msg() is similar to the msg() verb, but displays into the message area at the lower left corner of the script window (i.e. the window that holds this particular script) instead of into the main Frontier window.

Here's an example of a "local" block, with a formatting error:

The "local" keyword defines variables as local to the script; see the next Chapter for details on UserTalk variables. Only lines that consist of variable names or variable assignments may be indented as part of a "local" block. Because the structure of a script as reflected in its levels of indentation is significant, the msg (x + y / z) line is a syntax error. If you try to compile this script, Frontier will present an error dialog. Simply click on the Go To button and the cursor will be placed on the line that contains the error. To fix this script, type shift-tab; the msg line will move out one level where it belongs.

Turning a Script Into a Verb

You may think of "verbs" as functions that are built into Frontier, and "scripts" as functions that you write. In reality, there is no essential difference! Many of Frontier's verbs are implemented as scripts, and all of them live in the Object Database. As seen in Chapter 2, scripts that you create in your People table can be called from the Quick Script window, a menu script or from any script anywhere in the Object Database.

Nevertheless, there is a recommended way to design your scripts so that they can be called from other scripts. This design is required when your script accepts parameters, so it's a good idea to get in the habit of using it all the time. Here are the details.

Since a script is stored in the Object Database, it must have a name. The name should suggest or describe what the script does. Inside the script, UserTalk uses the "on" keyword followed by the exact name of the script to define what actions will be performed when the script is executed. One way to understand the keyword is to think of the script definition as "on the occurance of this script name and (optionally) these parameters, perform the following actions". Some scripting languages refer to verbs or scripts as "handlers", and the definition as an "on handler".

Here's an example. Go to your people table (with Cmd-J or from the Custom menu). In the Table menu, select "New Script". Type "demoFormat" and click OK. Note that Frontier does the work for you! Your new script will look something like the following (with an extra line indented underneath):

Note that if you create the script using a method other than the "New Script" menu command, you must type "on" and the script name yourself. Don't forget the parentheses! When you create a script that has parameters, they will go between the parentheses; but parentheses still required for scripts that have no parameters.

As we shall see when we cover debugging later in this chapter, there is one slight complication to this structure. Even after you add executable lines indented under the "on" line, clicking the "Run" button will just give an error. Why? The script contains only a definition of a verb, and the definition can't be executed directly. Fortunately, there's a very easy solution. You can call your new verb (script) from anywhere in Frontier -- including from inside the script itself! If you are still following along, type return to get a new line in the script, and shift-tab to bring the line back to the left edge (i.e. make it a "summit"). Now type the name of the verb, followed by parenthesis. The script will now contain:

on demoFormat ()
   « a blank line unless you typed something here
demoFormat ()

Click the "Run" button. It works! It doesn't do anything at all, but it no longer gives an error. Again, this form is optional for simple verbs, but required for scripts that have parameters. One note:

Menubar scripts should not be structured with an "on" definition. Their purpose is to call other scripts; they are executed from the menu but cannot otherwise be called by scripts.

The "on" keyword is also used to define local scripts, i.e. scripts that live inside another script. These scripts must be defined before they are called, so they are often placed at the very beginning of the script. They can also occur in any almost any UserTalk "block" structure (covered in the next chapter). The xx keyword is used to return control and send a value back to the main script. Parentheses are optional. Here's a simple example.

on demoFormat ()
   msg ("part of the main script")
   on squareIt (n)
      return n*n
   msg ( squareIt(3) ) « result will be 9
demoFormat ()

Compiling a UserTalk Script

All UserTalk scripts exist in two forms. The first is source code that you create, view and edit. The second is an internal "compiled" version, a compact "tokenized" format that executes very quickly.

In general, Frontier creates the compiled version automatically when necessary, so you don't have to worry about it. If you make a change in an open script window and close it without clicking the Compile (or Run) button, Frontier will if you want your changes to be compiled (see Figure 6-2).

Figure 6-2. Dialog Confirming Desire to Automatically Compile Script Changes

Unless you are an advanced UserTalk script writer and have a specific reason for leaving the compiled version as is, just click on the "Yes" button in this dialog. The circumstances under which you would wish to say "No" are rare.

Note that Frontier's compiler is quite fast. When you click on Compile, you might think that nothing happened!