Frames are the objects in a Frame Representation System. A frame is a named object. Frames may be used to represent classes, instances, slots, annotations, and other representation primitives. The operations in this section do not distinguish among these ways that frames are used. The operations defined in Section 3.1.1 and 3.1.2 apply to class frames and instance frames, respectively.
The protocol provides several different ways to refer to frames. Virtually all FRSs uniquely identify each frame in a KB with a LISP\ symbol, which we call the frame name. Some FRSs implement frames using LISP objects with which a pointer is associated; frame operations are faster on these objects than on the frame name. We call these arbitrary LISP objects frame objects. The vast majority of the users of GFP need be concerned only with frame names and frame objects. Both frame names and frame objects are acceptable arguments to those GFP operations that take a frame argument (such as get-frame-type , delete-frame , and get-class-all-instances .
Most readers will want to skip the following paragraph, which defines frame handlers and frame pretty-names.
In most implementations, the frame handle and the frame name will be the same. However, the frame handle is not required to be a symbol; it is only required to be a data structure that can be compared using EQL comparison, and that can be used to select a frame using get-frame-named . A frame handle may be used as a frame argument to any GFP operation, but it cannot be used as a value argument. Therefore, frames may be uniquely identified by integer handles, but there will never be any confusion between supplying an integer and an integer-valued frame handle as a slot value. The frame pretty-name is a name for a frame that is meant for use in a user interface that needs to display a visually appealing name for a frame that may be neitehr unique, nor suitable for programmatic use; the frame pretty-name also defaults to the frame name. Table 3.1 summarizes how these different frame identifiers differs along several dimensions. An example of how these identifiers might differ in a complex implementation is as follows. The frame name is a symbol that is unique in a KB, but not across different KBs (different KBs can contain different frames that happen to have the same frame name). The frame handle is a LISP data structure that can be created more quickly than can a LISP symbol, and is also guaranteed to be unique only within a KB. The frame object is a LISP data structure that is guaranteed to be unique across all KBs, i.e., no two frames in any two KBs have the same frame object. The frame pretty-name is a string describing the frame, that happens to be retrieved from a slot of the frame.
|Type||Unique in KB?||Unique across KBs?||Frame arg?||Slot value?||Pretty?|
get-frame-in-kb thing &key kb error-p kb-local-only-p
This function returns two values. The second value is t iff: thing is either a symbol that names a frame in kb, or thing is a frame object for a frame in kb, or thing is a frame handle for a frame in kb. In all cases we verify that the frame does in fact reside in kb. Otherwise, the second value is nil (unless error-p is t, in which case the function signals an error because thing is not a valid frame in kb).
When the second value is t, the first value is the frame object for thing (or the name of thing, for FRSs that do not support frame objects). When the second value is nil, the first value is also nil.
frame-in-kb-p thing &key kb kb-local-only-p
This function returns t when thing is a frame name, a frame object, or a frame handle, for a frame in kb. Frame-in-kb-p is equivalent to:
(nth-value 1 (get-frame-in-kb thing :kb kb))
coerce-to-frame thing &key kb error-p kb-local-only-p
This function coerces thing to be a frame object, if such objects exist for the underlying FRS. Thing can be a frame name, a frame object, or a frame handle. However, this function is less careful than is get-frame-in-kb about ensuring that the frame of thing is actually in kb when the supplied thing is a frame object. It verifies that thing is the appropriate type of frame object for kb, but not that the frame actually resides in kb. Therefore, this function will be faster than is get-frame-in-kb for some FRSs.
This function returns two values. If thing is a frame object of the appropriate type for kb, then this function returns thing and t. Else, if thing is a symbol naming a frame in kb, or a frame handle for a frame in kb, then this function returns the associated frame object and t. Else, this function returns nil for both values (unless error-p is t, in which case the function signals an error because thing is not coercible to a frame).
coercible-to-frame-p thing &key kb kb-local-only-p
This function returns t when thing is either a frame object, or the name of a frame in kb, or the handle of a frame in kb, and is equivalent to:
(nth-value 1 (coerce-to-frame thing :kb kb :error-p nil))
frame-eql frame-1 frame-2 &key kb kb-local-only-p
This function returns t iff frame-1 and frame-2 identify the same frame in kb. Frame-1 and frame-2 may be any mixture of frame names, frame objects, or frame handles.
frame-object-p thing &key kb kb-local-only-p
This operation returns t iff thing is a frame object for the FRS specified by kb. This operation only implements a type check, so thing need not actually be in kb (see frame-in-kb-p ). In the case where frame objects are actually symbols, and thing is a symbol corresponding to a valid frame, the operation should return t. more
get-frame-named frame-name &key kb error-p kb-local-only-p
Returns the frame object for the frame in kb whose name is the symbol, frame, or frame handle frame-name. If the underlying FRS does not support frame objects, then the symbol or handle that names the frame is returned. Error-p affects the behavior of the function when frame-name is not the name of a frame; the function returns nil when error-p is nil rather than signaling an error.
get-frame-labeled label &key kb error-p kb-local-only-p
Intuitively, this function is meant to be used by a user interface program to return a set of frames that match a label or a frame name. This function is useful for FRSs that associate additional labels besides the frame-name symbol with a frame. Although there is exactly one unique frame-name symbol per frame, a given frame may have multiple labels, and those labels need not be unique within a KB. The mapping from labels to frames is implemented by FRS-specific software, such as a hash table, in a manner that GFP does not specify. Labels may be useful to associate a human-readable string with a frame, or when we wish to associate several synonymous labels with a frame. There is a many-to-many mapping from frames to labels.
The parameter label can be a frame-name symbol, or a frame handle, or a frame object, or a label string.
Get-frame-labeled returns a list of the one or more frame objects (or the frame handle or frame name for systems that do not support frame objects) matched by label.
get-frame-name frame &key kb error-p kb-local-only-p
Returns a symbol that is the name of the frame identified by frame, which can be either a symbol or a frame object. Error-p affects the behavior of the function when frame is not a valid frame; the function returns nil when error-p is nil rather than signaling an error.
get-frame-handle frame &key kb error-p kb-local-only-p
Returns a handle that uniquely identifies the frame argument. The value returned may well be a symbol, such as the frame's name, but is required only to be a data structure that can be compared with other frame handles using EQL comparison, and that can be used to select a frame using get-frame-named . The frame argument can be either a symbol, a frame handle or a frame object. Error-p affects the behavior of the function when frame is not a valid frame; the function returns nil when error-p is nil rather than signaling an error.
get-frame-pretty-name frame &key kb error-p kb-local-only-p
Returns a string that is a pretty name for frame, meaning the name is suitable for use within a user interface. The default GFP methods return the frame name. Error-p affects the behavior of the function when frame is not a valid frame; the function returns nil when error-p is nil rather than signaling an error.
get-frame-type thing &key kb error-p kb-local-only-p
When thing is a frame or name of a frame, returns either :class or :instance depending on the type of the frame. Error-p affects the behavior of the function when thing is not a valid frame; the function returns nil when error-p is nil rather than signaling an error.
copy-frame frame new-name &key kb new-kb kb-local-only-p
Copies frame, which resides in kb, to a frame whose name is given by the symbol new-name. The new frame will reside in new-kb, which defaults to kb. The new frame will be created with the same parent classes as the old frame, therefore, an error will occur if the frame is copied to a different KB but the parent classes do not exist in that KB.
create-frame name &key direct-types direct-supers doc template-slots template-facets own-slots own-facets kb error-p
Creates a new frame with the name name, which is a symbol. Direct-types is a list of class frames (symbols or frame objects) of which this new frame is a direct instance. Direct-supers is a list of class frames of which the new frame is a direct sub. If this list is non-null then the new frame is a class frame. To specify a root class for a KB - a class without any superclasses - use '(:CLASS) for the direct-types. Doc is a string documenting this frame.
Template-slots and own-slots each take a list of slot specifications. A slot specification assigns a set of values to a slot. The syntax of a slot specification is (slot-name slot-value*), where slot-name is a symbol naming a slot and slot-value is a Lisp object suitable as a value of the specified slot. Template slots are only allowed for class frames.
Template-facets and own-facets each take a list of facet specifications, which can assign a set of facet values. A facet specification has the form (slot-name [(facet-name facet-value*)]*), where slot-name is a symbol naming a slot, facet-name is a symbol naming a facet, and facet-value is a Lisp object suitable as a value of the specified facet. Template facets are only allowed for class frames.
KB is a KB name or object. Error-p defaults to nil; if it is nil and the frame already exists, then the specified relation and slot information is asserted for the frame, otherwise an error condition is signalled.
rename-frame frame new-frame &key kb kb-local-only-p
Changes the name of frame to be the symbol new-frame.
delete-frame frame &key kb recursive-delete? kb-local-only-p
Deletes frame from kb. When recursive-delete? is t, the function recursively deletes all direct subs and direct instances of frames that have no direct-supers or direct templates other than frame. This function does not signal an error if frame does not exist.
print-frame thing &key kb stream kb-local-only-p
Prints an ASCII representation to stream of the frame thing or the frame named thing. A warning is printed when thing is neither a valid frame or frame name.