[Cyan]<CedarChest6.1>LoganBerryTools>LoganBerryBrowser.mesa!5

LoganBerryBrowser.mesa

Doug Terry, February 24, 1987 2:28:25 pm PST

Operations used by the LoganBerry Browser that may be of use to others. Includes facilities for performing multi-attribute filtered queries and for creating customized browsers.

DIRECTORY

ChoiceButtons USING [EnumTypeRef],

Containers USING [Container],

Icons USING [IconFlavor],

IO USING [STREAM],

Labels USING [Label],

LoganBerryStub USING [Attribute, AttributeType, Entry, EntryProc, OpenDB],

LoganBerryStubExtras USING [SchemaInfo],

Menus USING [Menu],

RefID USING [nullID],

RefTab USING [Ref],

Rope USING [ROPE],

ViewerClasses USING [Viewer, ViewerFlavor];

LoganBerryBrowser: CEDAR DEFINITIONS

~ BEGIN

Attribute-based queries

Following are some operations for dealing with attribute patterns and using them to query a LoganBerry database.

Attribute patterns are lists of LoganBerry attributes that may optionally contain a pattern type. The currently supported types of patterns include "exact", "prefix", "wildcard", "reg. exp.", and "soundex" (see LoganBerryToolsDoc.mesa). The following data structure is the internal representation of an attribute pattern list. In addition, attribute patterns have an external (character string) representation that can be printed or typed in. A basic LoganBerry attribute is represented in the form:
<attribute type>: <attribute value>
In this case, since a pattern is not explicitly specified, the value is taken to be the exact value of the attribute. That is, a missing pattern defaults to "exact". The attribute value may be either a token or a rope literal.

An explicit pattern type may be given in parenthesis immediately following the attribute type. Thus, an attribute pattern is given in the form
<attribute type>(<pattern>): <attribute value>
Several of these may be concatenated together to get a list of attribute patterns. For example,
Name: "Douglas B. Terry" Phone(prefix): 494-44 Office(wildcard): 35-2*

AttributePattern: TYPE = REF AttributePatternRec;

AttributePatternRec: TYPE = RECORD [

attr: LoganBerryStub.Attribute,

ptype: Rope.ROPE ← NIL

];

AttributePatterns: TYPE = LIST OF AttributePattern;

SyntaxError: ERROR [explanation: Rope.ROPE ← NIL];

QueryWarning: SIGNAL;

ReadAttributePatterns: PROC [s: IO.STREAM] RETURNS [ap: AttributePatterns];

Reads an externalized list of attribute patterns from the given stream and builds the appropriate data structure. Raises ! SyntaxError if the stream does not contain a validly formed list of attributes.

WriteAttributePatterns: PROC [s: IO.STREAM, ap: AttributePatterns] RETURNS [];

Writes a list of attribute patterns to the given stream.

PatternsToEntry: PROC [ap: AttributePatterns] RETURNS [entry: LoganBerryStub.Entry];

Converts a list of attribute patterns to a LoganBerry entry by ignoring the pattern type.

EntryToPatterns: PROC [entry: LoganBerryStub.Entry] RETURNS [ap: AttributePatterns];

Converts a LoganBerry entry to a list of attribute patterns with ptype=NIL.

FilteredQuery: PROC [db: LoganBerryStub.OpenDB, patterns: AttributePatterns, proc: LoganBerryStub.EntryProc, baseIndex: LoganBerryStub.AttributeType ← NIL, feedback: FeedbackProc ← NIL] RETURNS [];

Retrieves entries in the LoganBerry database that match the attribute patterns and calls the given procedure for each one. The baseIndex parameter governs which attribute type is used as the base index for the query; for baseIndex=NIL, an index is chosen that attempts to optimize the execution of the query (use this unless you really care about the order in which database entries are retrieved). If a feedback procedure is supplied, it is called to provide information about the query (see the definition of FeedbackProc). The signal QueryWarning is raised if the complete database must be retreived in order to anwser the query (i.e. the query will take a potentially long time); this signal can be resumed.

FeedbackProc: TYPE = PROC [category: ATOM, info: Rope.ROPE] RETURNS [];

Provides human-readable feedback returned by the query planner. For each attribute pattern, feedback may be given indicating the actual pattern value used (e.g. for date), the actual pattern type used (e.g. for DWIM), errors encountered in parsing a pattern value (e.g. for date or int), etc.; for these cases, the category given corresponds to the pattern's attribute type (e.g. $Name or $Phone). A special category, $QUERY, is used to return general information about the query being executed, such as the base index being used or the projected query cost.

Browser tools

The following operations allow one to create a LoganBerry browser with customized behavior.

Tool: TYPE = REF ToolBody;

ToolBody: TYPE = RECORD[

db: LoganBerryStub.OpenDB ← RefID.nullID, -- open database handle (*)

dbInfo: LoganBerryStubExtras.SchemaInfo ← NIL, -- database schema (*)

menu: Menus.Menu ← NIL, -- command menu (default is standard menu)

innerFlavor: ViewerClasses.ViewerFlavor ← NIL, -- flavor for inner viewer

inner: ViewerClasses.Viewer ← NIL, -- viewer for retrieved database entries (*)

outer: Containers.Container ← NIL, -- main container (*)

icon: Icons.IconFlavor ← unInit, -- icon used

fields: LIST OF LoganBerryStub.AttributeType ← NIL, -- fields that should be present in the entry form (default is set of indexed attributes)

entryform: RefTab.Ref ← NIL, -- set of "FormField"s (*)

inputArea: ViewerClasses.Viewer ← NIL, -- area for type in (*)

sortButton: ChoiceButtons.EnumTypeRef ← NIL, -- order of retrieval (*)

queryFeedback: Labels.Label ← NIL, -- area for feedback about query processing (*)

details: Containers.Container ← NIL, -- container for choice buttons (*)

historyData: REF ANY ← NIL, -- log of executed queries (*)

history: ViewerClasses.Viewer ← NIL, -- viewer for history data (*)

height: CARDINAL ← 0, -- current height of tool (excluding inner viewer) (*)

process: PROCESS ← NIL, -- process currently executing a query

clientData: REF ← NIL -- client-specific data

];

Entries that are not marked with (*) can be set explicitly by a client before calling CreateTool; all other entries should be treated as read-only.

CreateTool: PROC [db: LoganBerryStub.OpenDB, tool: Tool] RETURNS [];

Builds a tool for browsing the given LoganBerry database.

The following routines may be useful for those clients creating customized browsers.

ReadEntryForm: PROC [tool: Tool] RETURNS [form: AttributePatterns, orderBy: LoganBerryStub.AttributeType];

Returns the contents of the entry form and the sort button.

PrintEntry: PROC [entry: LoganBerryStub.Entry, tool: Tool];

Simply prints a LoganBerry entry in the browser's inner viewer.

ReportFeedback: PROC [category: ATOM, info: Rope.ROPE, tool: Tool] RETURNS [];

Displays the feedback in the browser's feedback areas.

END.

Doug Terry, October 20, 1986 4:24:29 pm PDT

changes to: DIRECTORY, LoganBerryCommands, ~

Doug Terry, October 31, 1986 3:34:34 pm PST

Added CreateTool operation.

changes to: DIRECTORY, LoganBerryBrowser, ~

Doug Terry, November 23, 1986 8:12:21 pm PST

Exported the default DisplayProc; added OpProc registration to the browser.

changes to: ~

Doug Terry, December 4, 1986 6:44:20 pm PST

CreateTool now allows the client to specify a particular flavor for the output viewer.

changes to: ~, DIRECTORY

Doug Terry, January 29, 1987 1:35:00 pm PST

Added a FeedbackProc for FilteredQuery.

changes to: ~

Doug Terry, February 23, 1987 6:28:02 pm PST

Changed CreateTool to take a Tool object has its major parameter.

changes to: DIRECTORY , ~

Doug Terry, February 23, 1987 6:38:16 pm PST

changes to: DIRECTORY, ~

Doug Terry, February 24, 1987 2:28:25 pm PST

changes to: DIRECTORY, ~