Chapter 3

Writing UserTalk Scripts

This chapter discusses the process of creating, storing, running and debugging UserTalk scripts.

Where do I put my Scripts?

Like everything else in the Frontier environment, UserTalk scripts reside in the Object Database. Although your scripts can be put almost anywhere, it's best to stay organized right from the start. In the previous chapter we learned about the People table; let's go there now. From the UserLand menu, select Jump to Cell. (You will probably use the command often, so you may want to remember the keyboard equivalent, Cmd-J.) In the dialog that appears, type "People.ME" (though use your initials instead of "ME").

We recommend putting most your scripts here, unless there is a compelling reason to do otherwise. Experience has shown that storing such personal-use information in your people table has two distinct advantages. First, it makes it easier to remember where you put things when you try to find them later. Second, if a new version of Frontier is shipped and it has a new version of the root file, you won't have to rummage around your old root looking for things you don't want to lose when you upgrade.

The Frontier website contains additional documentation, including step-by-step instructions for taking advantage of specific features. If the instructions are specific about where to put your scripts, please follow them! For example, many of the new web publishing features depend on scripts that you add to a specific table within the "user" table.

Frontier has a number of special tables that are appropriate for storing certain kinds of scripts. See Chap 5, Object Database.

Structuring a UserTalk Script

The most important thing to remember about the structure of a UserTalk script in a script editing window is that indentation is significant. Just as the Pascal language uses BEGIN/END and the C language uses curly braces, UserTalk uses outline indentation to delimit the beginning and end of various blocks and structures. Loops and conditional branches should be arranged so that the lines you expect to execute repeatedly (using "loop", "for" or "while") or under some defined circumstance (with "if" or "case") are indented under the line that defines the structure. Each of these language elements is explained in DocServer.

A UserTalk script is a special type of outline in Frontier. Whether reviewing your own script or reading someone else's, you can collapse groups of lines to provide a high-level view of the script's structure. You can also expand certain portions that you wish to view in detail. The ability to expand and collapse is one of the most powerful aspects of using an outline as a scripting tool.

In addition to the standard loops & branches, UserTalk has many language elements that make use of indentation, including comments, "local", "with" and "bundle." Comments are covered next; the other items appear later in the chapter.

Comments in UserTalk Scripts

Comments are easy to include in your UserTalk scripts and we encourage you to use them extensively. They don't affect the speed of your scripts, take up relatively little room in the Object Database and make it much easier to maintain and share your scripts. UserTalk supports two kinds of comments: line-ending comments and outline comments.

A line-ending comment generally appears on the same line as executable code. Click at the end of a line then type UserTalk's comment character « (hold down the Option key and press the backslash key -- located just above the Return key on most Macintosh keyboards) and the text of your comment. When the UserTalk compiler encounters a line-ending comment, it stops parsing the line. (In case you are curious, the comment character is variously known as the "chevron", "left guillemot", "left angle quote" or "double angle bracket.")

To convert a line of your script into an outline comment, hold down the Command key and press backslash. The item marker changes into a «, converting this line and all lines indented under it as comments. If the headings below a comment heading are collapsed, the comment character is emboldened. You can toggle the outline comment off and on by selecting "Toggle Comment" in the "Script" menu, or using the keyboard equivalent noted above. To enter a new line that is automatically a full-line comment, pressing Shift-Return.

Figure 6-1 shows a script fragment that demonstrates all of these facts about comments in UserTalk scripts. If you like, jump to people.ME, create a new script, type in this example and experiment.

Figure 6-1. Script Fragment Showing Comment Usage

Frontier is quite intelligent about how it deals with comments and executable lines of code. For example, if you enter a line of executable code and then indent it under a comment line, it will turn into a comment. If you move that line back to its previous level, it "remembers" that it is executable and toggles itself out of comment mode.