[Indigo]<KRL>specs>userInterface.bravo!4

Status: I think this accurately reflects our discussions, and is achievable. \$ and PPK are not implemented at all, the intermediate level edit macros need to be revised, and some framework for using Align as an editor needs to be developed. Also, UNITS: needs some work.

The general topic of this is the user interface to KRL. There are three dimensions along which variation occurs: Operation (input, output, editing), Level (Message, Intermediate, Memory), and structural environment (LISP or KRL, that is \.../ vs. (UNITS: ...)).

The KRL structural environment really exists in only way: as a collection of message level units on a file. Here the user’s resources are fairly limited. The UNITS: prettycom governs the writing of message level versions of units to files. The functions READWHITEUNITS and READBRACKETUNITS cause message level units to be read from files and converted to intermediate level versions, which are not accessible to the user. They will subsequently be converted to memory level. UNITS: puts calls to these functions on the file ahead of the unit definitions it writes out. File pointers are maintained in the memory level version of units, so in remaking a file unchanged units will simply have their old message level definitions copied.

If units without file pointers (e.g. constructed units or read in units which have been modified at the memory level) are encountered in a UNITS: prettycom at write time, they will be dumped by prettyprinting directly from memory level to the file. This may lead to loss of information, as memory level prettyprinting is not guaranteed to know about parts of units not actually present in the memory level version, e.g. functional definitions, in-line comments, some of the pseudo-functionals noticed by the cataloger (see the Cataloging document).

In general the prettyprinting of memory level structures will be possible, via PPK(handle). Initially this will print only what is actually there in the memory structures. This means that reading in a message level structure, converting it to memory level, and doing PPK of the resulting is not the identity transformation. The approved way to change the message level version of a structure is to use a text editor on that structure. See the Conversion document for details on what will get lost, transformed, etc in the current implementation.

No provision for editing intermediate level versions of units will be provided. Editing can be accomplished either permanently, at the message level, by text editing the source, or temporarily, at the memory level, by appropriate calls to Align, which is the general purpose memory level structure manipulator. For details, see the Matcher document. As noted above, memory level editing can lead to loss of information at cleanup time.

It will be possible to copy the message level version of a unit on the screen with PPU(unitName), edit it via chat typescript -> bravo -> do file and, having wrapped the new definition in \.../, redefine the unit. As the result will have been read from a file (the temporary file used to handle \ typed at the terminal), the right thing will get dumped when the file on which the unit lives is dumped.

KRL structures may appear in the LISP structural environment in several ways, principly surrounded by \.../ in a function definition, or encountered in the terminal dialog, during debugging etc. Message level forms read in following a \ are converted to intermediate level versions which are wrapped in a datatype called a nexus, along with file pointers. This allows them to be recognized and prettyprinted using the KRL printer when encountered in functions, etc., causes them to be dumped in a quickly loadable form when compiled, printed distinctly if they appear on the stack, etc.

Conversion to memory level is done at evaluation time, and the resulting structures may be printed and modified via Align, but no access to memory structures via the LISP editor is provided.

For editing the intermediate level form, which may be encountered in a nexus within some LISP structure, several edit macros will be created to allow descent into the record structure within a nexus, descent into the contents of descriptors, permutation of nexus types (Anchor, Descriptor, and Unit), and so forth. This is strictly a quick and dirty debugging tool, and requires a knowledge of the record structures at the intermediate level. No validity checks are made on the result of such editing, and mistakes may have arbitrary results. Consider the following example, where ES, for Enter Structure, is an edit macro which descends into both the descriptor field of a nexus and the data portion of an intermediate level descriptor:

←EF(FunnyFun)
...
*pp
(Describe \Danny/)
*(n \A Person with name = "Danny"/)
*pp
(Describe \Danny/ \A Person with name = "Danny"/)
*3 P
$Anchor
*ES
*p
INT.Perspective
*ES p
(Person (name . INT.IntLispPointer))
*(n (home . \PaloAlto/))
*0 pp
\A Person with name = "Danny" home = PaloAlto/

Note that in the first insertion, a nexus was built as the structure was being inserted directly in a LISP context. In the second, the insertion was into an intermediate structure, so no nexus was needed. Because of the possibility of getting back into the LISP context under a nexus via for example a LispPointer to an S expression, the edit chain will have to be examined with some care before the correct form for an insertion can be determined.

\ produces a nexus of type Anchor, \# one of type Unit, and \~ one of type Descriptor. $ is the prefix character for memory level units and labelled anchors, which will print as \$unitName and \$unitName.slotName. The KRL reader will do the right thing so that such constructs will read in as the appropriate handle. Note that this means that $ is a break character in the KRL read table, and so cannot be used in a KRL identifier.

Intermediate level structures print as the type of structure prefixed with INT., as in the above example. Nexi print as the type of nexus prefixed with $, as $ANCHOR, $DESCRIPTOR, $UNIT. Handles other than labelled anchors and units print as the type of handle prefixed with MEM., as MEM.MapDescriptor, MEM.Collection.