Chapter 6: The Object Database

This chapter describes the Frontier Object Database in detail, including:

• how it's organized
• how to address objects stored in it
• how to find objects stored in it
• variables and the Object Database
• how to export information from it and import information into it
• how to use it for personal information and make it your own.

Introduction

Few scripting or programming environments have anything like the Object Database. It stores data permanently, can contain scripts and data, is hierarchic, is easily accessed interactively and thru scripts, can store huge amounts of data, and it's fast.

The object database is at the heart of the Frontier enviroment.

It's a table

The Object Database is a table that can hold many different types of information, including other tables. Here's a picture of the top-level table in Frontier as we ship it:

Object types

The most common and important datatypes are defined on the "Kind" popup menu in the lower left corner of each table window. They are:

Boolean, Character, Number, Float, Date, Direction, String, String4, Enumerator, File Specifier, Alias, Object Specifier, Address, Table, WP-Text, Picture, Outline, Script, MenuBar, List, Record and Binary.

This list is actually incomplete. Frontier can create other types, they are accessible thru The Table Menu, which is in Frontier's menu bar when a table window is frontmost.

Organization of the database The outline at the right shows you the top part of the hierarchy that makes up the Frontier Object Database as delivered by UserLand. When you use this database, import scripts and other objects into it, and otherwise customize it, this organization changes, of course. The base table in the Object Database is called root, like the root of an upside-down tree. It contains eight sub-tables. Each of the tables, in turn, has one or more elements, some of which may be tables. This nesting of sub-tables can continue up to 25 levels deep in the database. The Workspace table is new in Frontier 4.1. It's the easiest place for new Frontier users to put their scripts. In the following sections we highlight the most important places for newcomers. If you want to view any of these tables, choose the Jump command from the Open menu, and enter the address of the table.

suites.samples

Many new example scripts are in the samples table, a sub-table of the suites table (described shortly). Samples in turn has sub-tables, organized by topic or application. When you are learning Frontier, you might want to go through a few of these scripts every day or week. Even as you become comfortable with Frontier, look back occassionally; you may be surprised at what new things you discover.

scratchpad

This table is intended as a temporary storage area, although like all Frontier table entries, it is saved to disk and remembered from session to session. You'll probably find frequent use for the scratchpad table, particularly during development and testing of reasonably complex Frontier scripts and suites. It's an easy place for scripts to store preferences. We use this location in some of the example scripts in the documentation as well.

workspace

This table belongs to you. Put your personal scripts and data here. You can build out structures of tables and sub-tables to organize your work, much as you would use the file system to store your programs and data. Many of the examples in this manual build sample scripts in the workspace table.

people

In versions of Frontier prior to 4.1, the people table was considered the primary place for new users to add their scripts and data. Now we recommend using the workspace table, described above.

When you run Frontier for the first time, it asks you for your name and initials. Among other initializations it performs at that point, Frontier creates a new entry in the people table with your initials. For example, if your name is Xenophanes Xerxes Xenophon, and if you enter your initials as "XXX," Frontier creates a table entry called people.XXX. The People table is a primary place where you can add your own scripts and data.

Frontier also registered your People table in its paths table, so you refer to any object it contains by cell name without the people.XXX portion of your address. This approach is recommend to simplify sharing your scripts with others.

helptext

In earlier versions of Frontier this table contained outlines and word processing text explaining the program itself. With better user interface tools, and the web, this table simply contains a pointer to the web-based documentation.

suites

Suites are collections of related scripts and data, usually attached to one or more private menus. See Chapter 10 for details.

user

This top-level table stores information about you, and information for suites and other scripts. It's important that scripts store their data separately. By storing data in sub-tables of the user table, authors can update the scripts and not overwrite your personal data. This table is a very important place especially if you use Frontier's web authoring features. Check out the Web Authoring Navigator accessible thru Frontier's Open menu.

system

The system table is one of the most important sub-tables in Frontier. Like the System Folder in the Macintosh Operating System, it's where the Frontier system itself is defined. Also like the System Folder, it has places for you to add scripts that run when Frontier starts up and shuts down. It has some things the OS doesn't have, like agent scripts that run continuously in the background and outlines of scripts that appear in the menu bars of applications that support a special protocol.

system.verbs

All of the verbs in Frontier are defined in system.verbs and its many sub-tables. If you peruse this sub-table, particularly the sub-table called builtins, you may be surprised to find that a great many Frontier verbs are defined in scripts that use other verbs in the language. Whenever you see a reference to the "kernel," you are looking at a direct call to the Frontier program.

system.misc.menubar

Frontier's menubar is stored in the system table. Choose Menu Editor from the Open menu to view it. You may customize it, as we create new versions of Frontier, new versions of system.misc.menubar are optional.

system.menubars

Many scriptable applications support menu-sharing. Their custom menus are stored in the system.menubars table. The names correspond to the 4 character application ID (also known as the application's "creator" code). As with Frontier's main menu, feel free to change them.

system.verbs.traps

This table is central to Frontier's role as a CGI scripting environment running behind web server software. It contains scripts that respond to Apple Events sent to Frontier.

Each sub-table of system.verbs.traps has a four-character name, corresponding to a class of Apple Events. Each sub-item is a script with a four-character name that corresponds to the "id" of the Apple Event. The parameters to the script are the parameters to the Apple Event, the returned value of the script is the value that Frontier returns to the Apple Event caller.

Other system places

The Main Navigator, accessible thru the Navigators sub-menu of the Open menu, can take you to many of the important places mentioned above.

Changes to UserLand-supplied scripts

One word of caution: although sometimes there is no good alternative, we recommend that you do not edit Frontier's built-in verbs, suites or application "glue" scripts. If you write other scripts that depend on the changes and then we release a new version, you must either make your changes again or stick with the old version and miss out on improvements.

Further, if you want to distribute your scripts, you would force everyone else to make the same changes. Instead of modifying the original, create your own version in your a sub-table of the suites table. If you want to distribute your scripts to others, just include these extra scripts.

Information for each object

Every object in the Frontier Object Database, regardless of type, has three pieces of information stored, corresponding to the three columns in the table:

• name
• value (or contents)
• kind (datatype)

Every object must have a name. You normally use the name of an object to access its contents, although as we will see in the next section you can use its relative position in the table when that information is known and useful. A Frontier object's name must not be longer than 32 characters. While most of the names you'll see in the Object Database are one word, this is not mandatory. Multi-word names are legal. As we'll see in the next section, they add special addressing requirements for scripts but nothing insurmountable.

What is displayed in an object's value column depends on two factors: the kind of data involved and, if it is non-scalar, whether it has been loaded from the disk during the present session. For example, take a look at Figure 6-1, which is part of the root.examples table as it is shipped by UserLand.

Figure 6-1. Partial Listing of examples Table

Notice that the objects called list1 and list2 are outlines and are stored on disk. The object lunchReminder is a word processing text object that is also on disk. But mouseat is a scalar object, a point, and its value is reflected directly in its entry in the table. Similarly, name is a scalar object, a string, so its value is shown in the table. (Note that the item markers for scalar objects are gray.)

Double-click the item marker beside list1 to open it. Now look at its entry in the examples table. It indicates the contents of the outline as far as Frontier knows them at this point, namely that the outline has five lines.

Accessing the object database from scripts

To retrieve or change the contents of the Frontier Object Database you need a means of addressing objects in the database. The basic approach is to specify the full name of the object, with each sub-table of which it is a member appearing in order from the root level down to the object, and each sub-table's name separated from the others by a period. (The "root" prefix is not required.)

When you want the value of an object, just use its name, e.g.

msg (user.initials)

When a verb or script needs to act on the object itself, rather than just the value of the object, you specify the address by including the "@" character, e.g.

edit (@user.initials)

When you can use partial object names

Type the following line into the Quick Script window and execute it:

edit (@notepad)

How does Frontier know to open the notepad that is in your people table?

For the answer, type the following line into the Quick Script window and execute it:

edit (@system.misc.paths)

The result should look something like Figure 6-2. Examine this table and you'll quickly discover that it is a series of pre-defined paths to tables in the Frontier Object Database. Any object whose full name begins with any of these paths will be found if you supply only the remainder of its name (i.e., the part that would be appended to the end of one of these known paths).

Figure 6-2. Table of Pre-Defined Object Database Partial Paths

It is possible that two of these tables will contain an item that has the same name. Frontier searches this table from top to bottom, using the first match that it finds. For example, if there were two objects called notepad, one in people.DGS and one in root.system, the one in the people table would essentially override the other unless a complete path to the latter was provided.

We recommend that you do not edit this table unless you are an experienced script writer and are sure there is not a better way to accomplish your goal. If you change the table and your scripts depend on the change, they will be harder to share with others.

Names containing special characters

In the examples table, there are three sample outlines that are used in DocServer. They are called Sample Outline 1, Sample Outline 2, and Sample Outline 3. If you try to type the name of one of these objects into the Quick Script window, an error condition will result.

edit (@examples.Sample Outline 1)

If you click on the "Go To" button in the Error Info, you'll find the cursor flashing after the word "Outline." UserTalk sees this text as a script containing three consecutive table identifiers - "Sample", "Outline", and "1" - with no operators between them. This is an illegal script.

To access such objects in UserTalk, you must enclose the multi-word name in quotation marks and then you must enclose the entire quoted string in square brackets:

edit (@examples.["sample outline 1"])

This syntax is actually a special case of the use of square brackets to force UserTalk to evaluate the expression contained between them and to use the result of that evaluation as an identifier (the name of a single table or cell). This somewhat advanced technique can be used to create generic scripts that would otherwise have to be customized for a particular user or configuration.

For example, if you want a general purpose script that will refer to a value in the user's people table, you need to a way to include the user's initials. Frontier stores the initials at user.initials, the square brackets can evaluate (or "lookup") the value.

msg (people.[user.initials].favoriteColor)

As a reminder, the user's people table is global -- i.e. the exact path usually is not required. Unless there was another "favoriteColor" cell in a different "global" table, the following script is equivalent:

msg (favoriteColor)

Also note that "msg" uses the value of favoriteColor whereas "edit" needs the address of an object, i.e. the "@" prefix.

Relative addressing

The objects in a Frontier Object Database table can be referenced by their relative positions in the table. This approach permits you to deal with a Frontier table exactly like an array in other programming languages. The first entry in the table can be addressed as:

table.name [1]

All other entries are similarly addressed. The 12th item is addressable as:

table.name [12]

Let's look at an example. Open the Examples table and sort by Kind (click on the "Kind" label at the top of the table so that it is underlined). Open the Quick Script window, type and run the following:

examples [1]

Assuming the first entry in your Examples table is "nextchar" with a value "M", that's what you'll see in the result portion of Quick Script.

The Jump Command

The fastest way to locate an object in Frontier is with the Jump command from The Open Menu, also accessible by Cmd-J from the keyboard.

Command-double-click

If you are looking at some information in a script (or any other object), you can hold down the Command key and double-click on any Frontier term (object database address) and be taken directly to its definition (location) if it can be found. This technique is often the quickest way to navigate from a script to another script it calls.

Find and Replace

Frontier includes built-in find-and-replace capability (see The Main Menu for details). You can use this feature to locate any piece of information you want to find in the Object Database -- though it may take some time.

Variables and the database

You can create new entries in the Object Database interactively, as described in Chapter 2 or from a script.

From the Quick Script window, you create a new variable in the Object Database simply by assigning it a value. For example, scratchpad.y does not exist when you installed Frontier. But if you type this line into the Quick Script window, you can then examine the scratchpad table and confirm that it now has an entry called y with a value of 13.04 and a type of double (floating point):

scratchpad.y = 13.04

Objects that have their own editing window can be created with the "new" verb, e.g.

new (outlineType, @scratchpad.partyList)

Local variables

When you create local variables in your scripts, the variables only last as long as the script is running, they are not stored as a permanent part of the Object Database.

As noted in Chapter 3, Frontier creates a temporary series of tables representing a dynamic "stack" while the script is running.

When you are debugging a script, this location is accessible through the Object Database structure at location system.compiler.stack.

Exporting Objects

You can export any Frontier object to the desktop for import to another copy of Frontier or back into your original Frontier root file. For details see the Export section on The Main Menu page.

You can also copy Frontier objects and paste them into other applications via the Clipboard, just as you are used to doing with other Macintosh applications. You can select text from a word processing text object, and paste it into a document in another application. You can do the same with individual headings of Frontier outline objects, with scalars, and with individual names of table entries.

Importing Objects

You can import Frontier objects into any Frontier.root file. If the object was exported from Frontier to a file using the Export command from the Main menu, you can import it into a Frontier.root file one of two ways: by double-clicking on it in the Finder, with or without Frontier running (Frontier will be launched if it is not running); or from within Frontier, choosing Open... from the File menu and then choosing the file.

If the object you wish to import into Frontier is a desktop script, you can hold down the Command key when you double-click its icon in the Finder and continue to hold the Command key down until the script's editing window opens in Frontier.

Using the Clipboard, you can bring text information from other applications into Frontier. Select some text in an application window, copy it, then switch to Frontier. Paste the text.

Personal use of the database

Aside from its value and importance in scripting, the Frontier Object Database is a powerful storage system in its own right. Because it can search in the text of any item, it may be convenient storing notes to yourself, electronic mail messages, organized outlines of electronic mail accounts, records of users on a local area network, outlines of projects, reminders about appointments, and a host of other items that may or may not be related to a script.

Feel free to make extensive use of the database for such things. We recommend that you use your Workspace table as the storage starting point. You can build sub-tables, word processing text entries, and a host of other database entities in this table.

---

© Copyright 1996-97 UserLand Software. This page was last built on 5/7/97; 1:08:40 PM. It was originally posted on 9/24/96; 9:41:54 AM. Internet service provided by Conxion.