Chapter 4: continued

Variables in UserTalk

As with most programming or scripting languages, UserTalk supports two types of variables: local and global. Local variables are those that occur temporarily within a script, local script or block and exist only within that context.

Although UserTalk does not require that you specifically declare local variables, it's a very good idea and can save you hours of debugging that would otherwise be required to track certains kinds of errors. Declaring local variables is a good habit in general and particularly important in scripts that can be called from other UserTalk scripts.

A local structure is used to declare (define) one or more variables as local. A script may contain more than one local structure; all the variables are local to the block in which the declaration appears. (This context is often referred to as the "scope" of the variable.)

You can also set the initial value of one or more variables within a local block, and include end-of-line comments (but not outline comments):

local
   x = 3
   y = 4 « blah, blah, blah
   z

UserTalk often provides more than one way to accomplish the same result, accomodating different styles. With some extra punctuation, you can create locals all on one line:

local (x)

Setting the initial value is also possible:

local (x = 3)

Multiple variables are supported:

local (x, y)

One or more variables can also include values:

local (x = 3, y = 4)

Note that these alternate forms make "local" look somewhat like a verb; if you find that confusing, just use the indented form! Even if you choose one form for your own scripts, be sure to learn to recognize the other form as both are quite common.

Global variables are those that are permanently stored in the Frontier Object Database and have cell addresses there. Frontier's global variables are also "persistent," i.e. they retain their value even after the script finishes. As long as you save the Object Database before quitting Frontier, the value is still there when you open Frontier again. These "persistent" variables are completely separate from scripts that use them, so their value is not altered or destroyed by changing and "compiling" a script. Because they live in a table in the Object Database, you can view and edit them on their own, independent of any script. Persistent global variables are a major benefit of Frontier and its Object Database.

UserTalk Verbs

The vocabulary of UserTalk consists of several hundred verbs. These verbs are identical to functions in conventional programming languages. Various computer languages call these elements by different names, including subroutines, procedures and handlers. We refer to them as verbs because they are most often used to direct Frontier or some other program with which Frontier is interacting to do something. Action is the province of verbs in human speech.

The most important verbs in UserTalk can be divided into 23 categories. (There are additional categories, and may be additional verbs not included in the verb count for each category. Every verb is documented in DocServer, described later in this chapter.)

Table 4-1. Summary of UserTalk Verbs

Category     Qty.  Uses, Comments and Notes
--------  -------  -------------------------------------------------
Basic          29  Handle numbers, datatypes, objects, etc.
Clock           7  Set and get system clock values. 
                   Time-stamp documents. Pause execution.
Date            2  Get and set date values
Dialog         10  Display and return results from dialog boxes
EditMenu       14  Emulate behavior of Frontier's Edit Menu, including
                   fonts and styles
File           64  All file operations, including copy, delete,
                   move, create, and rename. Looking at file and folder
                   contents, read and write text files, deal with
                   volumes, parse path names, lock and unlock files,
                   handle Macintosh aliases, etc.
FileMenu        9  Emulate behavior of the Frontier File Menu
Finder         23  Manage and manipulate the Macintosh Finder,
                   including windows, views, files, and folders
Frontier        5  Turn agents on and off, make Frontier the active
                   application, and get information about Frontier
Keyboard        4  Determine if the Command, Control, Option, and/or
                   Shift key is down
Launch          5  Open applications, control panels, documents, and
                   code resources
Main Window     6  Control Frontier's Main Window
Menu            9  Manage and manipulate the Frontier menubar and
                   menubar objects
Mouse           2  Find out where the mouse is and if the button is
                   being pressed
Outline Proc.  32  Edit, navigate in, rearrange, expand, collapse,
                   retrieve information from and otherwise manipulate
                   Frontier outline objects
Search          6  Handle Frontier's internal find-and-replace
                   operations
Speaker         2  Define the sound the internal speaker will make and
                   activate it
String         25  Manage and manipulate string objects, including
                   fields, word and sentences.
System          4  Deal with external applications and find out what
                   version of the Operating System is in use
Table          13  Manipulate and interact with Frontier Object
                   Database tables and their contents
Target          3  Determine the Frontier object that will receive the
                   next action(s) taken in the environment
Window         21  Manage and manipulate Frontier windows
Word Proc.     25  Handle word processing objects and their contents,
                   including setting properties, controlling the
                   selection, formatting the appearance of text and
                   changing its content
--------------------------------------------------------------------

As discussed earlier in the manual, the full name of a verb is composed of its category, followed by a period, followed by the name of the verb. (When you want to run the verb, you must include parentheses, and parameters if required.) For example, string.upper operates on a string, converting it to upper case.

allCaps = string.upper ("Hello world!")

Every verb returns a value, either status (true or false to indicate success or failure) or some piece of information. Verbs can be "nested" one inside another, passing the value from the innermost script to the outer script:

dialog.alert (string.upper ("Hello world!"))

In many cases, it's useful to know both the status (true or false) and one or more other pieces of information. For example, you might want to ask someone a question by presenting a dialog. If they cancel (status is false) your script will take one action, if they enter information, it will do someting else. As with many programming languages, Frontier supports two kinds of parameters:

1. passing a value (either a literal or the value of a variable or expression)
2. passing an address or reference to a variable (including a local variable or a global stored in the Object Database)

When it gets an address, the verb can directly modify the variable that exists at that address -- and is free to use the return value for status (true or false). The "@" operator converts a variable into an address.

if dialog.ask ("Who are you?", @scratchpad.who)
   dialog.notify("You are " + scratchpad.who)
else
   msg ("user cancelled")

Some verbs set multiple variables. For example, to get the position of a specific Frontier window:

window.getPosition("examples", @horiz, @vert)

If the "examples" window is not open, the verb will return false (and leave the horiz and vert variables unchanged). Note that horiz and vert should be declared as local variables prior to the above.

Whether a verb should return status or a value depends partly on how the verb is likely to be used, and partly on the preferences of the script writer! The advantage of returning a value is that the verb can be nested inside other verbs. If you prefer this approach, use it for scripts that you write. How? When there is only one key piece of information (in addition to status), simply return that information. If there is more than one key piece of information to return, create a list (or possibly a record) and return that. Since you can no longer return false to indicate lack of success, use:

scriptError("optional error message here")

The script that calls your script can trap the error in a "try" statement, preventing the script from halting.