General Information for all Viewers

Lisp Packages

When opening a KB for the first time, you will be asked to enter (or verify) its package. The package name also appears with the KB name on the status line for the hierarchy and relationships viewers. This section is provided for users who may be unfamiliar with the Lisp package system. Experienced Lisp users will recognize this section as greatly oversimplifying the Lisp package system. For more information about the Lisp package system, see the Packages chapter in Guy Steele's Common Lisp the Language, 2nd Edition.

A Lisp package defines a namespace. Within a single package, no two symbols can have the same name. Since frame names are Lisp symbols, no two frames can have the same name (in some frame systems, the same name can be used for both a frame and a slot, but due to the potential confusion that may arise, this practice is not recommended). Lisp has a notion of the current package, such that by default, any symbol you reference is assumed to be in that package. You can still reference symbols in other packages, but you must preface the symbol name with the package name and ::.

For example, suppose there are two packages PKG-X and PKG-Y, and assume there is a symbol A present in both packages. If my current package is PKG-X and I refer to A, then I am referring to the symbol A in PKG-X. To refer to the symbol A in PKG-Y, I must write PKG-Y::A.

When a KB is created or opened, it is important to know which package all its symbols should be in by default. When you first start up Lisp, you will be in some default package, usually CL-USER. When you open or select a KB, that KB's package becomes the current package. This way, when you are asked to enter a frame name, that frame name by default becomes a symbol in the KB's package. (You can still reference symbols in other packages, but you must use the :: notation) You may wish to put each KB in its own package so that you can have multiple KBs open at once without their frame names conflicting. When you type in a package name while opening or creating a KB, and the package does not yet exist, it will be created.

Frame Selection

Many of the menu commands are designed to operate on a particular frame or set of frames. The GKB-Editor allows you either to select the frame(s) first and then select the operation, or to select an operation, which will when prompt you for the frame(s). However, if you prefer the latter mode of operation, you must make sure that there is no current selection when you enter a command, or else the command may be performed on the wrong frame.

When no command is currently active, left clicking on a node will cause that frame to be selected. To indicate this, the node will be shown in reverse video. Shift-left clicking on a node adds it to or removes it from the selection, allowing you to select multiple frames for a single operation. Left-clicking on the background cancels all current selections. In addition, there are three commands accessible from the top-level Frame menu in the hierarchy and relationships viewers, Select All, Select Descendants, and Select Ancestors, that will select a whole group of frames. After a selection is made, an operation may be selected from the command menus. If the operation is one that can operate on multiple frames, the operation is performed on the entire selection. If the operation requires a single frame, and more than one frame has been selected, the user will be offered a menu of selected frames from which to choose. If, for example, the operation is applicable to class frames only, but the selection consists of a mixture of class and instance frames, only the class frames will be used. If a selected frame cannot be used, a warning message is printed in the text pane.

If no frame is selected when an operation that requires one is invoked, the user is prompted to enter a frame. If just one frame is required, the user will be prompted directly. A frame can be entered either by clicking on the corresponding node in the graph pane, or by typing in its name in the text pane. If you change your mind, and no longer want to perform the operation, typing Control-Z or right-clicking in the background will abort the command. If the operation can accept more than one frame, you may be asked to input a sequence of frames. You can do this either by left clicking on several frames in sequence, or entering a comma-separated list of frame names via keyboard. In some cases, additional selection options are available (such as All or None or Compute Automatically), in which case, a menu of options is popped up. You may choose to enter only a single frame, in which case the frame is entered as before. If you choose to enter multiple frames, you are put into a mode in which every node you left click on is added to or removed from the selection. You cannot type in frame names in this mode. Left clicking on the background ends the selection process. If the command can accept no frames (as in the case of creating a class with no parents), this is also provided as an option in the menu. The No Select option in the menu aborts the command.

When selecting an edge, if two nodes are preselected and there exists an edge between them, that edge is used. If one node is preselected, it is assumed to be the child node (unless it is a root, in which case it is assumed to be the parent). If there is only one incoming edge, that edge is selected automatically. If there is more than one incoming edge, the user is asked to click on the desired parent. If no nodes are preselected, the user is asked to select the child first, and then the parent if necessary.

Completion is available in most cases when typing in frame and slot names: if you enter a partial name and then type Return, a menu of completions will be popped up.

The "Kill" Ring

A cut-and-paste/kill-ring facility is available for use in most input contexts, to reduce the need to type in frame names, etc. Any time the Copy to Kill Ring command is invoked, the currently selected nodes are copied to a kill ring. A node is also copied to the kill ring when it is individually deleted. When prompted to enter a frame or a value, Control-Meta-Y yanks the last object from the kill ring. Meta-Y invoked immediately after a Control-Meta-Y or another Meta-Y rotates the kill ring. This facility attempts to yank values in the form expected by the input context. For example, if you are being prompted to enter a frame, the yanked value will be coerced to a frame name where possible. If you are prompted to enter a string, the value will be converted to a string, etc.

Due to limitations beyond our control, the kill ring cannot handle multi-line strings, and also is not usable from within a Motif text-editing window. Motif text-editing windows are used from within the frame-editing viewer to edit multi-line values, which the kill ring cannot handle, anyway, due to the first limitation. A variety of emacs-like editing commands can be made available within Motif text-editing windows by adding the appropriate entries to your .Xdefaults file. (See the Installation Instructions for information about setting up your .Xdefaults file)

Creating Classes and Slots

If you are creating a new KB from scratch, the basic pattern to follow is: first create the classes, then create the slots, and finally, create the instances and store slot values in the instances. Now in fact, you can interleave these different tasks. The more precise constraints are: An instance cannot be created until at least one of its parent classes exists, and a slot cannot be created until the most general class that will contain the slot has been created.

Once you have created classes and slots, the degree to which you can modify them within the GKB Editor may be constrained by your FRS.

Creating slots is a bit tricky, so we discuss the issue in more detail. Most FRSs store not only the values of slots within a given frame, but they store meta information about each slot that describes general properties of how the slot will be used in the KB. These slot properties are often called facets; facets are in a sense ``slots on slots'' because facets store a set of named values that are associated with a slot. For example, a facet called :value-type defines the types of values that a given slot can take, and a facet called :domain defines those KB classes within which a slot can appear. The facet names listed here may not actually be used within your FRS, but because each FRS uses different facet names, the GKB Editor internally translates from the names shown here to the names used by your FRS.

All editing of slots is performed by invoking the Frame Editor on the class frame that will contain, or that already contains, the slot in question. For example, to add a slot called Age to the class Person, first invoke the Frame Editor on Person. Then click on Create from the Slot menu to add the Age slot to this class. Similarly, the Destroy operation will remove Age from Person, and the Rename operation will rename the slot.

More subtle modifications to a slot definition can be achieved by changing its facets. Imagine that we wish to state that the Age slot can only take one value, which must be an integer. To do so, we would give the :cardinality-max facet the value 1, and we would give the :value-type facet the value :integer.

These facet values can be assigned in two ways. To establish default, KB-wide values of the facets, use the Edit Slotunit operation from the Slot menu. A slotunit is a special frame whose slots encode KB-wide default values for slot facets. For example, if we edit the slotunit for Age, and give its :value-type slot the value :integer, we are effectively setting the :value-type facet for the Age slot.

The other approach is to edit the facets of Age directly within a class frame. Use this approach when either your FRS does not support slotunits, or when you wish to specialize facet values. For example, imagine our FRS also supported a facet called :numeric-max, which defined the maximum value that a slot value is allowed to have. In the Age slotunit, we could set the value of :numeric-max to 150 -- a reasonable value for the class Person. Imagine that we now define a new class, Infant, for which the :numeric-max facet of Age should be further constrained to have the value 1. To do so, first invoke the Frame Editor on class Infant. Then use the Preferences menu to enable the display of facets. If your FRS supports the :numeric-max facet, you can then click on it and use the ReplaceValue command to change it value in that class, without affecting the :numeric-max of Age in Person.

Invoking Viewers Programmatically

You may wish to incorporate part or all of the GKB-Editor into another Lisp application by invoking one or more of the viewers programmatically from your other Lisp application. The Lisp commands to accomplish this are described in this section.

gkb-editor:view-hierarchy (&key start-browse? roots width height) [Function]
Invoke the hierarchy viewer. Since this is the main GKB-Editor startup window, it also provides access to the other viewers from its command menus. If start-browse? is non-nil, and there exists a current open KB, then the GKB-Editor will immediately begin browsing the class hierarchy. If roots (a list of frame names) are supplied, then they will be used as the roots of the hierarchy browse (assuming start-browse? is non-nil); otherwise the roots will be computed using the user's current preferences, as usual. If start-browse? is nil and a previous hierarchy browse exists, it is resumed; otherwise the viewer will appear showing the GKB-Editor copyright graph. If both width and height are supplied, then they will be used for the dimensions of the viewer window; otherwise the dimensions will be automatically calculated based on the user's screen size.

gkb-editor:view-relationshiops (&key roots (width 0) (height 0) (slots *current-slots*) (breadth gsp::*browse-breadth-limit*) (depth gsp::*browse-depth-limit*) (hard-depth gsp::*browse-hard-depth-limit-p*)) [Function]
Invoke the frame relationships viewer. If roots (a list of frames) is specified, the specified frames are used as roots of the relationships browse. Otherwise, if a previous relationships browse exists, then that browse is resumed. If no roots are specified and there is no browse to resume, the user will be prompted to enter the roots. If both width and height are supplied, then they will be used for the dimensions of the viewer window; otherwise the dimensions will be automatically calculated based on the user's screen size.

gkb-editor:view-frame (&key frame slot (width 800) (height 500)) [Function]
Invoke the frame-editing viewer. If frame (a frame name) and slot (a slot name) are both specified, then only the specified slot and its values, facets, etc. will be displayed. If frame is specified, but not slot, then the entire frame will be displayed. This is what is normally seen when you invoke the frame-editor from one of the other viewers. If slot is specified, but not frame, and a slotunit for the specified slot exists, the slotunit information will appear in the display. If neither are specified, this function will return immediately with no effect. width and height are used for the dimensions of the viewer window.

gkb-editor:view-spreadsheet(frames (slots :single) &key (dialog? t) (pretty-name? t) list-supers? (frame-order? :alpha)) [Function]
Invoke the spreadsheet viewer. If dialog? is true then a dialog is presented to the user before the spreadsheet is invoked. The dialog gathers data for which slots to display and in which order, which order to display the frames, whether to display pretty or frame names and their parents. frames can be a list of instances or classes. slots can be a list of slots or one of (:all :common :single).

When pretty-name? is true, the pretty names of the frames are displayed. Otherwise frame names are displayed. The parents of the instances are displayed when list-supers? is true. frame-order? is one of (:alpha :class). When dialog? is set to true, all arguments except frames are ignored and the dialog is presented to the user. The default for this call is that the dialog will appear. The frames will be pretty names listed in alphabetical order, without their parents. The spreadsheet will display single-valued slots.


Most commonly used commands have keyboard accelerators defined for them. These commands are therefore accessible either by using the mouse to select the appropriate command from a menu or by typing some key combination (usually some letter while holding down either the Control key, the Meta key, or the Control and Shift keys) on the keyboard. Commands with keyboard accelerators have the corresponding key sequence listed next to the command name in the menu, and also in this documentation. As keyboards differ, you may need to experiment with your keyboard to determine which actual key corresponds to the Meta key.

In any viewer, you may use Control-v to scroll the viewport downwards and Meta-v to scroll it upwards.


Return to the GKB-Editor Overview page.

Return to the beginning of the GKB User Manual.

Suzanne M. Paley <>
Last modified: Wed May 29 15:53:23 1996