3
The Database
Accompanying the Frontier application is a database file called Frontier.root . Whenever Frontier is started up, it automatically opens the copy of Frontier.root that is in the same folder with itself. It is possible to close a database; it is possible to open a second database (see Chapter 30, Multiple Databases ). But in general, any running copy of Frontier will have exactly one database open: the Frontier.root that is shipped by UserLand.
Most of the features that give Frontier its actual behavior are located here: its menus, its scripts, its ability to interpret those scripts, and all the tools and features that make Frontier useful. Without a database open - without this database open - Frontier will be virtually incapable of doing anything. It is for this reason that we speak in the singular of "the database." (It is referred to sometimes as the database, sometimes as the root ; these terms are interchangeable. It is also sometimes referred to by Frontier mavens as the odb, for "online database.")
In this chapter, the database is introduced. There is some discussion of its contents, though the details are left to the rest of the book (by the book's end, there will be scarcely a cranny of the database left unexplored); and there is considerable discussion of how to navigate the database. After studying this chapter, the reader will be comfortable with the nature and presence of the database, and will be ready to explore and modify it.
WARNING Be very, very careful with the database! If you read nothing else in this book, read the next few paragraphs. Remember, and obey!
This is your database. You are free to explore it, and you are expected to do so; Frontier is an "open system," so the database is deliberately exposed to your gaze, and studying it and tracing its workings is one of the chief ways of learning about Frontier. You are free to store things in the database, and you are expected to do so; you will need to do so if you wish to liberate Frontier's full potential.
Nevertheless, it is also Frontier's database, and you can bring the program completely to its knees by making wanton changes. A single false move, such as deleting the system entry from the root table, will cause Frontier to choke completely, and you may have to download a fresh copy of the database to get it working again. More subtle changes could cause specific tools to break, or make Frontier behave unpredictably, and since it has great power over things you value, such as what's on your hard disk, that could be disastrous.1
To minimize risks, I suggest you follow two simple rules:
- Make frequent backups of the database. You do this by choosing Backup from the Main menu; Frontier maintains a Backups folder for this purpose. For safety, Frontier does not overwrite earlier backups when you make a new one, so after a while you will probably want to delete or compress some older backups manually in the Finder, as they are rather large.
- As my father said to me when he first taught me to use an electric saw: "Never Stop Being Careful." 2 This chapter will describe what parts of the database are yours to play with (within reason) and which parts are crucial to Frontier's basic functionality. Know what you are doing at all times! If you don't know that what you are doing is safe, don't do it.
If, despite your best efforts, you think you've screwed something up, choose Revert from the File menu, thus fetching the most recently saved changes from disk and reversing recent changes that have not been saved. (It is also possible to quit Frontier without saving the database, by clicking No when you are offered a chance to save it.) To return to a previously backed up version of the database, quit Frontier, rename Frontier.root to something else (or even throw it away), move or copy a backup of the root into same folder as Frontier, and rename it Frontier.root. If the worst comes to the worst, download a new clean root from UserLand's site.
I'm sorry if this little lecture has made you edgy. But Frontier, unlike most other programs, exposes most of its inner workings to you. That gives you a lot of power, which is the point; but that power is accompanied by increased responsibility.
The care and feeding of the database is further discussed in Chapter 29, Import/Export .
Main Window and Root Table
The presence of the database is indicated by the presence of the Main Window. Figure 3-1 shows the Main Window.
If you don't see the Main Window at all, choose the first item in the Window menu. If you don't see the row of buttons, click the "mailbox flag" icon at the right end of the window. If you don't see a status message like the one here, click the triangle at the right end of the window to bring up the popup menu and choose StatusMessage. You can change the font and size of the text in the window. You can widen or narrow the window by dragging the little dark square in the middle of the right edge. You can drag the whole window by its top half.
You can dismiss the main window by clicking in the go-away box at its top left, but if you do, Frontier thinks you wish to close the database - so don't.
The status message tells some useful things. One is how much heap memory Frontier has free (here, 3749K). Experience has shown that it is wise to keep this number large (3000K is a good minimum); to achieve this, you may need to save the database, or quit Frontier and increase its Finder memory allocation using Get Info. This matter is only partly related to the size of the database, which can grow very large without having much effect on Frontier's use of RAM or on the speed with which Frontier can access database entries. But Frontier does need RAM memory as soon as it is called upon to do anything, and it is wise to give it plenty.
From the Main Window, you can access the contents of the database by pressing the Object DB button or hitting Command-Enter. This brings up the root table edit window, showing the top level of the database; you can then "drill down" to any entry in the database, table by subtable by subtable, using the table edit window navigation techniques described in Chapter 2, Edit Windows .
Direct Database Navigation
To reach a desired database entry, it is not actually necessary to "drill down" to it through successive subtables; it is possible to navigate to it directly, because every database entry is uniquely named.
To see that this is so, recall that every table entry is uniquely named within its parent table. By the same token, the parent table is also uniquely named within its parent table, and so on, all the way up to the root table (which has no parent). Therefore, every database entry is uniquely named by the names of all the tables containing it plus its own name. The names are concatenated by means of "dot-notation." For example, in the root table is a table called system, which contains a table called verbs, which contains a table called colors, which contains an entry called blue. The full unique name of this entry is therefore sys-tem.verbs.colors.blue. A full name like this is called a path, and the parts between the dots, such as verbs and colors, are the elements of that path. Notice that the element root may be omitted from the start of a path.
In practice, a number of paths are so commonly referred to that, for the sake of convenience, Frontier makes it possible to refer to their contents without stating the whole path explicitly. For example, it is possible to refer to system. verbs.colors.blue by saying simply blue. After a time, the user tends to internalize a knowledge of which paths these are. The matter is discussed in great detail in Chapter 6, Referring to Database Entries .
To reach any database entry directly by name is called jumping . To jump to a database entry, choose Jump from the Open menu to bring up the Jump dialog, and type the path into the edit field (or choose it from the popup menu, if it is already present), and hit OK.
The popup menu in the Jump dialog remembers the last several jump destinations. You can change the maximum number of remembered destinations by changing the value at user.jump.maxItemsInJumpList. You can introduce permanently preset destinations by inserting them in the list at user. jump.permanentJumpList; they must be literal (double-quoted) strings, separated by commas, between the curly-brace list delimiters, like this:
{"system.verbs.apps", "people.man", "suites.html"}
To jump again to the destination most recently jumped to, without bringing up the Jump dialog, hold the Shift key while choosing Jump, or hit Shift-Command-J.
Another place to store frequent jump destinations is in the Bookmarks submenu of the Open menu. In a table edit window, select the desired jump destination, and choose Add Bookmark from the Bookmarks submenu. From then on, that jump destination will appear as a menu item in the Bookmarks submenu; choosing the item jumps to the destination that it names.
Still another means of jumping is by Command-double-clicking the name of a database entry in the text of any edit window. Basically, if you can see an entry's name, you can jump to it by this method. This is particularly useful when debugging scripts.
In the UserLand Suites submenu of the Suites menu is an item Object Database Map . When you choose it, an outline appears listing all tables in the database; the outline is not "live," but can be rebuilt by choosing Rebuild from the Map menu. Command-double-clicking the name of any table in the outline jumps to that table.
Searching the Database
The database can be searched by choosing the Find & Replace Dialog item of the Find & Replace submenu of the Main menu. This brings up a dialog which works as Find dialogs generally do. The process looks for text within the name or value of any database entry, so searching the whole database can be slow.
The Find dialog gets its context from what is frontmost at the time the dialog is first summoned. So, for example, to search the whole database, have the root table edit window frontmost beforehand; to search the suites table, have the suites table edit window frontmost beforehand. What entry in the table is selected may make a difference, too.
Once a search finds a match, you can continue the same search by hitting Command-g.
If text you wish to search for is already visible within an edit window, you can conveniently search for further instances of that text, without having to copy it into the Find dialog, by selecting the text and hitting Shift-Command-G.
Guide to the Database
Later parts of this book discuss just about every area of the database, so this section provides a mere sketch of the database's contents. If a part of the database is said to "belong to you," it is available for you to store material in. If it "belongs to UserLand," you generally should not store material in it or modify what is there, unless you are very sure of what you are doing. One reason for this is that what you modify might be some crucial link in the chain of a Frontier behavior, so that altering it might break that behavior. Another reason has to do with updates. From time to time, UserLand may update a part of the database that belongs to it, and you will wish to download and install the update into your copy of the database. When you do this, if you have made any changes in that part of the database, they may be overwritten and lost. However, UserLand will never distribute an updater that will overwrite a part of the database that belongs to you. This is discussed further in Chapter 29.
This table belongs to you, absolutely. It is readily available by choosing Workspace from the Open menu. Here you may keep anything, of any description. For instance, this is where I develop scripts, keep notes lying around, and store all kinds of material both temporary and permanent.
This is an outline that you can use for any purpose you like. It is readily available by choosing Notepad from the Open menu.
In the people table there is a table with your initials. This will have been created automatically when you first started up Frontier with a clean root.3 Mine, for instance, is called people.man. This table belongs to you, absolutely. Its most important use is for scripts and other objects to which you wish to refer conveniently in scripts.
This is because (as discussed in Chapter 6, Referring to Database Entries ) anything you place here can be referred to without a complete path. For example, on my machine, a script at people.man.myAmazingScript can be called by saying myAmazingScript(). Or, if I store my favorite color as people.man.myFaveColor, I can refer to it in a script by saying myFaveColor.
This table belongs to everyone, but only for temporary storage. In general, it is meant to be accessed by scripts rather than humans. The idea is that scripts can place anything they like here, secure in the knowledge that they won't be tromping on anything, because whatever is already here was put here on the understanding that it might be tromped on. At any time (unless a script is running) you could delete everything in the scratchpad table and nothing would break.
This table contains the self-contained tools and mini-applications that come with Frontier, as well as the implementation for a number of menu-driven functionalities. On the whole, any existing entry in suites belongs to Frontier; but you are free to write your own suites and place them here, and other users are free to write suites and distribute them. Suites are further discussed in Chapter 26, Menus and Suites .
This table is shared by you and UserLand. Various suites and other functionalities place entries here. But you are allowed and expected to modify certain of those entries, because they will be checked to learn what your wishes are. So you cannot store material freely in the user table, but you can store particular material that Frontier expects to find here.
Thus, you shouldn't modify anything in the user table without knowing what you're doing, but once you do know, there will be lots of things you will in fact modify. Some of these will be small things, such as changing a preference like the value of user.jump.maxItemsInJumpList. Others will be very large, like keeping an entire Web site in user.websites.
This table belongs to UserLand. Here beats the heart of Frontier; the system table holds Frontier's menus, the definitions of UserTalk verbs and constants, "glue" tables for driving other applications, and many other basic functions. On the whole, you should tread warily here; but there are places where you might make modifications. Here are some of the highlights of what's in the system table:
This is the sanctum sanctorum, where UserTalk itself is implemented at the lowest level. On the whole, you should keep out.
system.agents , system.startup, system.suspend, system.resume, and system.shutdown
Scripts here are automatically called periodically in the background or in response to certain external events; you might write a script and put it in one of these places. See Chapter 27, Agents and Hooks .
Scripts here provide access to "language extensions"; you might write or install one of these. See Chapter 23, Extending the Language .
system.misc.menubar and system.menubars
You might customize a menu here. See Chapter 26.
These are "glue" verbs that Frontier uses to communicate with other applications. It is possible that you will "tweak" existing glue, or generate new glue of your own. See Chapter 32, Driving Other Applications .