Inter-Office Memorandum
To Cedar Interest Date May 4, 1983 12:17 am
From Warren Teitelman Location Palo Alto
Subject Cedar UserExec Organization PARC/ISL
XEROX
Release as [Indigo]<Cedar>Documentation>UserExec.tioga, .press
Draft [Indigo]<CedarDocs>Manual>UserExec.tioga, .press
By Warren Teitelman
Last edited By Warren Teitelman on May 4, 1983 12:17 am
If you are reading this document on-line, you can use the Tioga Levels menu to initially browse the top few levels of its structure before reading it straight through.
References to other sections refer to the document Introduction to Cedar, which is stored on [Indigo]<Cedar>Documentation>Introduction.tioga.
Underlined material is new or has been changed for the current release.
Contents
General Comments
Events
Help
Show Me First
Completion
Compound Events
Executive WorkAreas
Registered Commands
WorkArea Menu Buttons
Interpreter WorkAreas
Action WorkAreas
ActionArea Commands
Using the History facility
Confirmation
General Comments
The Cedar executive is called the UserExec. It is an amalgam of the Alto Exec, a Cedar Language interpreter, and a debuggerbacked up by optional automatic error correction facilities similar to InterLisp's DWIM. For example, the UserExec can be used to load and run bcds, list, copy, rename, and delete files, evaluate Cedar Language expressions, catch breaks and signals, and display the state of a process that has been stopped by a break or signal.
The user interacts with a particular UserExec (you can have several around, even executing, at the same time) through a special viewer called a WorkArea. Each WorkArea has a name, typically a single letter, which is displayed as part of its caption. Each WorkArea also has a mode, which is either Executive or Interpreter, also displayed as part of its caption. To "talk" to a particular UserExec, simply establish the input focus by clicking in the bottom portion of the corresponding viewer, and then start typing.
Since the WorkArea is a viewer, all of the viewer facilities are available for manipulating the WorkArea (see section 1.1). In particular, it can be grown, adjusted, scrolled, moved, closed (the UserExec will continue running and/or outputting characters, you just won't see them until you reopen the viewer), opened, split, or even destroyed (which will abort any operation that is executing the next time it tries to do input or output). Furthermore, since the viewer views a Tioga typescript, all of the Tioga editing and selection mechanisms can be used with respect to the command line that you are composing: you can edit this line to your heart's content, and when you terminate the command, it will behave exactly like you typed in the edited line.
For example, suppose you want to bringover (section 1.3.2) the file walnut.bcd which is pointed to from walnut.df, and you type:
&1 Bringover walnut.bcd walnut
At this point, you realize that you have forgotten to type the /o between Bringover and walnut.bcd. You can simply point between these two, type /o, and then move the selection to the end of the line and type ´ (RETURN). (A convenient way to move the selection to the end is to use the NEXT key, which is the key to the right of RETURN.)
Typing ESC as the first character in a command line will replay the previous input line, up to, but not including, the last character, i.e. the one that terminated the command. You can then edit the line, or type additional characters, before executing the corresponding command. For example, suppose in the previous example you did not notice that you had left out the /o until after Bringover started operating. You could stop Bringover (by clicking the Stop menu button), type ESC, and then point before walnut.bcd and proceed as above.
Here is another example:
&1 Bringover /p [Indigo]<Cedar>Top>Rigging´
...bringover does its thing...
&2 ESC
which expands into:
&2 Bringover /p [Indigo]<Cedar>Top>Rigging
You now type CTRL-W (erases the last word) followed by "IO", and then RETURN, and the result is the same as having typed:
&2 Bringover /p [Indigo]<Cedar>Top>IO
except that it required only five key strokes. You can retrieve command lines other than the last one typed by selecting in the corresponding event and then right-clicking the Redo menu button, as explained below. (Or, you can use the secondary selection facility of Tioga, but this requires a little bit more careful "aiming".) In other words, whenever a previous line is very close to something you want to type, consider retrieving that line and editing it, rather than retyping.
Finally, typing DEL at any point during the input of a command (provided that the current selection is at the end of the document, otherwise DEL will be interpreted as a Tioga editing command and delete the current selection) will abort the input. Clicking the Stop menu button (or typing CTRL-DEL) while the UserExec is executing will cause it to abort the current operation. (This sometimes takes a little while.)
New UserExecs and their corresponding WorkAreas can be created via the New menu button (described below) or the CreateExec registered command. The former will create a new UserExec immediately, i.e. as soon as it is clicked, even if the corresponding WorkArea is busy executing a command, or even "wedged up." Existing UserExecs can be destroyed via the Destroy Viewer menu button (left-most button in the hidden menu) or the DestroyExec registered command. Destroying a UserExec while it is executing a command will cause the corresponding process to abort the next time it tries to do any input or output.
Events
Each user interaction with a UserExec is called an event. At the start of each event, the user is prompted by & followed by the event number. (Previously executed events can be referenced and manipulated via the history facilities described below. One convenient way of doing this is by event number.) The user then types in a command line consisting of the name of a registered command (see below), followed by its arguments, if any, and terminated by ´, ?, CTRL-X, or ESC. The UserExec then performs the indicated operation, prints the result, and prompts the user for the next event. As mentioned above, typing DEL at any point during the input of a command will abort the input and reprompt the user. Typing CTRL-DEL or clicking the Stop menu button will abort the execution of an event.
Help
Terminating a command line with
? signifies a request for additional information. Specifically,
? by itself prints a list of commands currently registered,
? after a registered command prints a description of the command, and
? after a Cedar expression prints the type of (the value of) the expression, as well as any comments from the corresponding interface.
&4 walnut*?
Walnut For retrieving and sending mail
WalnutExpunge Expunges deleted messages
WalnutScavenge Rebuilds Mail database from log file
WalnutSend Creates a viewer for sending mail
&5 ← 3.2?
is of type REAL
&6 ← Rope.Cat?
is of type PROC [r1, r2, r3, r4, r5, r6: ROPE ← NIL] RETURNS [ROPE];
returns the concatenation of up to six ropes (limit based on eval stack depth)
BoundsFault occurs if the result gets too large
As described later in the section on Interpreter Areas, terminating a procedure name with CTRL-E will cause a "form" to be constructed containing the names and types of the arguments. The user can then simply fill in the corresponding fields.
Show Me First
Terminating a command with
CTRL-X means to "expand" the command, but not to execute it. For example,
&6 delete *.*.pressCTRL-X
delete inputimpl.mesa.press mesascanner.mesa.press newio.mesa.press newstuffimpl.mesa.press userexec.tioga.press userprofile.doc.press
You can now type a ´ to carry out the operation, or edit the line and then execute it, or abort the operation by typing DEL.
Expanding a command line will produce a command line in which all patterns are replaced by the elements that match the pattern (* expansion), history commands and aliases are replaced by the commands that they would construct, and command files are replaced by their contents.
Completion
Terminating a command with
ESC means to "complete" the command, as far as possible, but not to execute it. For example (underlined text typed by user, other text supplied by system),
&6 comESCpile vieESCwerexESCecopsimpl.
Compound Events
While a command is being executed, the user can type ahead the next several commands, or move the input focus to another UserExec and type a command there. If the user wants to see (e.g., to make sure he typed correctly) a series of commands that are to be executed, or wants to make the execution of one command dependent on the successful completion of a previous one, he employs a compound event, which consists of several commands separated by semicolons. For example:
&3 compile fooimpl; bind foo; run foo;´
In this case, binding will not be attempted if the compilation fails, i.e. contains any errors, and the program will not be run if the bind fails. Aborting a compound event will abort the command currently being executed, and not continue to the next command, i.e., it aborts the entire event.
Executive WorkAreas
As described above, each command line begins with the name of a registered command (case does not matter). When the UserExec sees a command line that does not begin with the name of a registered command, it attempts to treat the first token on the command line as the initial characters in a command. If this token unambiguously specifies a command, then the UserExec simply treats the token as specifying that command. Otherwise, if there is a match, the UserExec prints the commands that match. For example:
&1 cop foo.profile ← user.profile´ cop matches unambiguously with copy
Copied 919 bytes to foo.profile
&3 ru fooimpl´
ru is ambiguous. It matches with:
Run Load and Start the named programs.
RunAndCall Load and Start the named program. Then call the registered procedure, if any.
ru not a command.
If there is no match, depending on the settings in the user's profile, the UserExec will try to treat the first token as the misspelled name of a registered command, and correct the spelling. If this fails, the event will terminate in an error.
New commands can be registered by running a program that knows how to register the commands it implements (by calling UserExec.RegisterCommand). However, in order that the UserExec know about commands that are (would be) registered by programs that have not yet been run, the file RegisteredCommands.catalogue contains a list of the publicly used registered commands (think of this file as a data base describing registered commands). In addition, the user can inform the UserExec about his own personal registered commands, again even before the program that registers them has been run, by including these commands in the RegisteredCommands entry of his personal user profile (see UserProfile.doc). This mechanism can also be used to override, i.e. redefine, those commands that are specified in RegisteredCommands.catalogue.
Registered Commands
The following is a list of some of the most useful registered commands. Commands relating to manipulating the history list or debugging in ActionAreas are described separately in the sections on Using the History Facility and Action WorkAreas respectively. More commands can be discovered through the use of ?, or by examining the file RegisteredCommands.Catalogue.
@ takes a file name as argument. Treat the contents of the named file as a command file, i.e. interpret the text as a sequence of commands. If {file} has no extension, look for a file of the form {file}
.commands or {file}.cm.
The contents of the command file produces one large compound event. As each command is read, it is printed to the WorkArea so that the user can monitor the progress of the command file. No error correction is performed while executing a command from a command file. Nesting of command files is permitted.
Commands that appear on separate lines are assigned separate subevents. The effect of this is that if an error occurs in one command, processing will continue with the next. Commands that appear on the same line, separated by ;, will only be executed if the earlier commands on the same line were successful. Aborting a command file by clicking Stop or typing CTRL-DEL, however, will abort the entire top level event.
@fileCTRL-X will display the contents of the command file without executing it. You can then execute the corresponding commands by typing ´, or abort by typing DEL. You can also edit these commands.
← Treat the remainder of the input line as a Cedar expression to be evaluated. Evaluate the expression and print its value. If the expression is terminated with ?, print the type of its value, rather than the value. If the expression is terminated with !, print the value showing the referents of all REFs and POINTERs to an unlimited depth.
(Note that ? also terminates, i.e. activates, the command line, whereas ! does not - you have to type a
´ or ?.)
Note: many users prefer to do interpretation of expressions in Interpreter WorkAreas or Action WorkAreas (see below), in which case the ← is automatically provided at the beginning of each command line, and to use Executive WorkAreas for "executive" type of operations such as running programs and manipulating files. However, ← can be used to interpret expressions in an Executive Area, and is also the only way to specify the interpretation of an expression as part of a compound event, e.g. Run FooImpl; ← FooImpl.Init[].
Alias Define an Alias.
Aliases provide a substitution macro facility for the first token on a line, e.g. Alias bro bringover /o will cause bro mumble to be expanded into bringover /o mumble. Aliases can also be given an (optional) argument list, in which case the tokens on the command line following the alias name will be substituted for the formal parameters, e.g., Alias brob (file df) bringover /a /o file.mesa file.bcd df would cause brob rope rigging to expand to bringover /a /o rope.mesa rope.bcd rigging.df.
Commands defined via aliases are treated the same as other commands with respect to ?, spelling correction, CTRL-X and ESC completion, etc. A good place to save your own individual aliases from session to session is to define them in the CommandsFrom option in your user profile.
Bind Bind a list of configurations. See discussion of Compile menu button below.
Bringover Retrieve files using a specified df file (see 1.3.2)
ChangeAreaMode change an Executive WorkArea to an Interpreter WorkArea and vice versa.
Chat Create a Chat viewer, i.e. a "terminal" for communicating with Maxc, Ivy, Ernestine, etc.
Compile Compile a list of modules.
Copy Copy contents of one or more files to another. Syntax is
Copy new ← old1 old2 ... oldn.
Date Type today's date and time.
Delete Delete a list of files.
Help Provide more complete explanation of UserExec in a separate viewer.
Hickory Personal calendar facility.
List Print size, creation date for the indicated files.
ListByDates Print size, creation date for the indicated files, sorted by creation date.
Login Accept and record user name and password.
Open Create viewer(s) on existing file(s).
Print Print the following files. Print menlo/h 2/c foo.press will print two copies of foo.press on Menlo. TSetter provides the same function for documents that employ Tioga formatting or node structure.
Rename Rename a file. Syntax is Rename new ← old.
Run Load and Start the named programs. /d following a file name means just load the corresponding program, but do not start it. Instead, call the debugger, e.g. so that you can plant breakpoints. Proceeding from the corresponding action area will then start the program.
SModel Store files on remote servers using a specified df file. (see section 1.3.2)
TiogaMesa Convert "flat" Mesa files to Tioga node structure.
TSetter Create a typesetter viewer for specified server, and use it to print named documents
User Type the name of the logged-in user.
Version Type the version of Cedar that is running
Walnut For sending or retrieving mail.
WorkArea Menu Buttons
For convenience, a number of commonly used registered commands can be invoked via menu buttons that appear in the first line of the menu of each WorkArea.
(The Find and Split buttons are the same as the corresponding menu buttons on a Tioga document. They do not have any special knowledge about WorkAreas.) The effect of each of these commands could also be achieved by typing an appropriate command line, and, with the exception of
New and
Stop, the menu button is actually implemented by simply stuffing the appropriate command line into the input buffer. As a result, these menu operations are automatically synchronized with each other and with other material the user may type.
New Creates a new WorkArea. The WorkArea will be an Executive WorkArea if New is selected with the left mouse button, an Interpreter WorkArea if selected with the right mouse button. (Note that the ChangeAreaMode command described earlier can always be used to reverse the mode of a WorkArea.) The New Menu button is not synchronized with type-in: it will create a new UserExec even if the current UserExec is busy computing. It can also be used when the current UserExec is "wedged". You can begin typing to the new work area as soon as you have clicked New.
Stop Sets the "abort" bit for the corresponding WorkArea. Stop is not synchronized with type-in (wouldn't be very useful if it were!). Application programs are supposed to test this bit at appropriate intervals and abort. For example, the program that prints the values of expressions tests this bit frequently, and if it has been set, stops outputting. Note: typing CTRL-DEL to a WorkArea is the same as clicking Stop in that area.
Compile compile/bind indicated files as follows:
Left click: Compiles the indicated file(s). If the current selection is not a point or character selection, treat the selected material as the name of the file(s) to be compiled, otherwise compile the file that is viewed by the selected viewer.
Middle click: Bind the indicated file(s). If the current selection is not a point or character selection, treat the selected material as the name of the file(s) to be bound, otherwise, if the file that is viewed by the selected viewer is a "config" file, bind that file, otherwise, figure out the name of the config it came from (using the AMModel, so that the module in question must have been loaded for this to work). In this case, wait for user to type ´ before proceeding. For example, if the current selection is a point selection in UserExecImpl and I middle-click Compile, the command line Bind UserExecutive will be generated.
Right click: compile and bind.
Eval Treat the selected text as an expression and evaluate it. The Eval button works whether the WorkArea is an Executive WorkArea or an Interpreter WorkArea.
Redo Redoes the selected event(s). Right-clicking Redo is the same as terminating Redo command with CTRL-X, i.e. you get to see what it will do if you type ´. See section on Using the History Facility below.
Set Sets a break point.
Left click: sets a breakpoint at (near) the point selected. (Breakpoints can only be set in a module if it has been loaded and started, so it is advised that all modules be started in every configuration.)
Middle click: set breakpoint at entry to the indicated procedure. If the current selection is a point or character selection, break at the entry to procedure that contains the current selection, otherwise, treat the current selection as the name of the procedure, i.e. the value of the current selection, e.g. Rope.Substr, ViewerOps.FindViewer, specifies the procedure. (Note that if the current selection does not specify a full path name, i.e. does not include ".", the evaluation uses the defaults of the corresponding work area.)
Right click: set breakpoint at the exit from the indicated procedure.
Note: setting a breakpoint can take a long time, especially if it is the first breakpoint to be set in the corresponding module. However, you don't have to wait for the operation to complete: you can start typing the next operation or clicking menu buttons right away.
When the breakpoint has been successfully planted, the corresponding location is underlined (Tioga feedback selection) to show you where the breakpoint was actually inserted.
An attempt to plant a breakpoint may fail for various reasons, e.g. the source file does not correspond to the loaded module (you edited but did not recompile), or that the loaded module could not be found by various reasons, e.g., it hasn't been started yet. The WorkArea will tell you why the breakpoint was not set.
Clicking the set menu button in an ActionArea for an action that occurred in some other world (see section on WorldSwap And Remote Debugging) will plant the breakpoint in that world.
Clear Clears a breakpoint as follows:
Left click: clear the selected break point. If the current selection is in an ActionArea, clear the breakpoint associated with this ActionArea if any. Otherwise, clear the breakpoint closest to the selection. Failure to clear probably means that there was no break at the selected location.
Middle click: clear the breakpoint associated with this ActionArea, if any, regardless of where the current selection is.
Right click: clear all break points.
Fine point: it is permissible to plant more than one breakpoint at a given location (e.g. there may be different conditions attached to each). Sometimes if you clear a break point but it still seems to be there, this can be the cause. Try clearing it again, or else clearing all breakpoints.
Yes Displayed when a correction that may require confirmation is begun. See section on Confirmation below.
No Displayed when a correction that may require confirmation is begun. See section on Confirmation below
Interpreter WorkAreas
When typing to an Interpreter WorkArea, the user is always prompted with &nn ←, where nn is the event number. What the user types following the ← is treated as an expression to be evaluated in the current context and default global context, if any, for the WorkArea. The value of the expression will be assigned to the variable whose name precedes the ←, i.e. &nn. This value can be referenced in later expressions. (Where it is meaningful, some commands also assign values to the corresponding & variables.) As mentioned earlier, if ? is typed following an expression, the type of the expression, plus other explanatory information, is printed.
The following is taken from an actual session with an Interpreter WorkArea. The italicized text at the right is added commentary not printed by UserExec.
&2 ← Rope.Cat["Ce", "dar"]´ Note that Rope is the interface, not the implementation.
"Cedar"
&3 ← LIST[1, 3.2, &]´ & evaluates to the previous result (&2 in this case.)
(^1, ^3.2, "Cedar")
&4 ← &3? What type of list did the interpreter produce?
is of type LIST OF REF ANY
&5 ← &3.first^?
is of type INT
&6 ← &3.rest.first^?
is of type REAL
&7 ← List´
default interface changed to: List
{Interface: List}
&8 ← Appendd[Reverse[&3],&3]]´ Note that Reverse is now interpreted as List.Reverse.
Appendd -> Append ? Yes Spelling correction.
("Cedar", ^3.2, ^1, ^1, ^3.2, "Cedar")
Fine point: each UserExec has its own symbol table, so that &4 typed to a given WorkArea means the value of the fourth event executed in that WorkArea, and will not be confused with &4 in some other WorkArea. To refer to the value of an expression which was evaluated in a different WorkArea, simply insert the WorkArea's name following the &, e.g. &B5 is the value of &5 from WorkArea B.
Normally, the values of expressions are printed to a default width and depth. The user can descend into specified fields of a value for more detailed examination, or chase REFs or pointers by using ^. Terminating an expression with
! will cause its value to be printed to unlimited depth and width. Some types of values are printed in a special way
(by virtue of a PrintProc being associated with that type, as described in IO.Mesa), such as
STREAM and Viewer in the example below, in order to suppress a lot of detail. However, these values can also be dereferenced using ^, and particular fields in them can be accessed in the usual way. For all cases, the Stop menu button can be used to abort printing. The following illustrates these points:
&9 ← UserExec.GetExecHandle[]´
^[viewer: {Viewer - class: Typescript, name: Work Area A: Executive}, privateStuff: 6245744B^]
&10 ← UserExec.GetStreams[&9]´
[in: {7314462B - Echo When Delivered Stream}, out: {7314474B - Dribble Stream}]
&11 ← &.in?
is of type STREAM: TYPE = REF IO.STREAMRecord;
IO.STREAMRecord: TYPE = RECORD[streamProcs: REF IO.StreamProcs, streamData: REF ANY, propList: Atom.PropList ← NIL, backingStream: STREAM ← NIL]
&12 ← &10.in^´
[streamProcs: ^[getChar: UserExecImpl.EchoWhenDeliverGetChar, endOf: IOImpl.DefaultEndOf, charsAvail: IOImpl.DefaultCharsAvail, too much, user clicks Stop
aborted
&13 ← &10.in.stremData´
stremData -> streamData ? Yes DWIM knows the type of &5.in so it can compute the set of valid selectors.
^[echoTo: {6701326B - Buffered Stream}]
&7 ← &10.in.backingStream.streamData´
^[node: NIL, buffer: "", ready: "", readyPos: 33, lastReadyLength: 33, deliverWhen: UserExecImpl.DeliverWhen, echoTo: {6701314B - Dribble Stream}, viewer: {Viewer - class: Typescript, name: Work Area B: Executive}]
Often the user types ? following an expression whose value is a procedure type, because he has forgotten the names of the fields or the types of the arguments, e.g.
&17 ← Rope.Find?
is of type PROC [s1, s2: ROPE, pos1: INT ← 0, case: BOOL ← TRUE] RETURNS [INT];
-- returns -1 if not found
-- case => case of characters is significant
He would then type in Rope.Find followed by the desired arguments. In such cases, the user can terminate the expression with CTRL-E, and a "form" will be constructed and inserted in the typescript consisting of the names of the arguments, and their types and default values bracketed by placeholders:
&17 ← Rope.FindCTRL-E
which expands into:
Rope.Find[s1: ROPE, s2: ROPE, pos1: INT ← 0, case: BOOL ← TRUE]
The user can then move back and forth between the fields using NEXT and SHIFT-NEXT, fill in those fields he wants to specify, and conclude the operation by typing CTRL-NEXT, which will delete any unfilled fields that have default values, and advance the caret to just past the matching ]. For more complete discussion, see section on Cedar Creature Comforts.
Interpreting an expression whose value is a global frame will have the effect of setting the default context to that module. This will allow you to refer to variables in the corresponding global frame without giving the full path name. Similarly, you can set the default interface by typing in the name of an interface. You can also set the default context/interface using the registered command SetContext. SetContext´ is the only way to clear the default context/interface once you have set it.
Note that if you want to invoke a registered command from within an Interpreter WorkArea, it is necessary to erase the ← (by typing CTRL-A or CTRL-W), i.e. ← Walnut means you want to evaluate the variable Walnut. (In the case that what you type is obviously not a mesa expression, e.g. ← Bringover walnut.bcd walnut, DWIM will ask if what you really meant was the corresponding command without the ←, and you can simply type ´ to confirm.) Similarly, since ← is itself a registered command, you can evaluate expressions in Executive WorkAreas simply by first typing ← and then the expression. Most people prefer however to use one work area for interpreting expressions and a different one for invoking registered commands.
For more detailed information about exactly what subset of Cedar language expressions the interpreter can handle see section 2.3.
Action WorkAreas
Actions (currently) occur when a program raises a signal or error that is not caught, encounters an unconditional breakpoint, or a breakpoint whose condition is satisfied, or there is an explicit call to the debugger
(for more details, see the interface AMEvents.mesa). Whenever an action occurs, the corresponding process is stopped so that it can be examined. If a process that was running under a WorkArea causes an action, a message is printed in that WorkArea, the WorkArea is suspended, and control transfers to a different WorkArea called an Action WorkArea, or ActionArea for short. For example:
&10 ← Rope.Fetch["abc", 5]´ asks for the sixth character in the rope "abc"
ERROR Traps.BoundsFault from Traps.BoundsFaultTrap
computation suspended, switching to Action Area B...
and a new ActionArea will be created in which will appear:
Action #1 (kind: signal, process: 212B)
ERROR Traps.BoundsFault from Traps.BoundsFaultTrap
(came from WorkArea A)
&1 ←
The procedure that is followed when an action occurs from a process that is not running under a WorkArea (e.g. a forked process) is similar.
An ActionArea is an Interpreter WorkArea whose default context is the context of the action.
If the action occurred in a remote world, then the context is that remote world. Thus, continuing with the above example, in ActionArea B the user can evaluate expressions involving the arguments to Rope.Fetch that caused the uncaught signal:
&1 ← Rope.Fetch?
is of type PROC [base: ROPE, index: INT ← 0] RETURNS [c: CHAR];
-- fetches indexed character from given ropes
-- BoundsFault occurs if index is >= the rope size
&2 ← base´
"abc"
&3 ← index´
5
Note that when an action causes a particular process to be suspended, other processes will continue to run (subject to the usual constraints, e.g., monitor locks), The user can simply ignore the action for the time being if he so chooses, and perform some other operation in a different WorkArea. (Note that the original WorkArea is suspended, so the user may have to create a new WorkArea, which he can do with the New menu button as described above.) If the user does not wish to pursue the cause of the action at all, the simplest way to make it "go away" is to click Abort, as described below.
ActionArea Commands
ActionAreas have a second menu line containing the buttons Proceed, Abort, Source, WalkStack, and ShowFrame, which are described below. Each of these menu buttons corresponds to, and is implemented by, a registered command. In fact, when you click one of these menu buttons, the corresponding characters are simply stuffed into the input buffer of the UserExec and then read. This means that anything you can do with buttons you can type, so for example, you can type in a compound event consisting of ShowFrame; ← <SomeExpression>; Proceed and then keep typing ESC to march through a sequence of breakpoints performing the indicated operations. In addition, implementing these menu commands by stuffing the corresponding characters also means that the menu commands are automatically synchronized with each other and with user typein, i.e. you can click Set and then click Proceed without waiting for the Set to complete, because the Proceed won't happen until the Set finishes.
Proceed allows the current action to proceed. If the action was a breakpoint, control will proceed normally from that breakpoint. If the action was an uncaught signal, Proceed will generate a ResumeError, resulting in another action. (There is currently no way to Proceed, i.e. Resume, an uncaught signal.)
Abort aborts the current action by causing the error ABORTED to be raised in the process associated with the current action. Right clicking abort will abort the action, and then close the action area viewer. Middle clicking abort will abort the action, and then destroy the action area viewer. (Conversely, destroying an ActionArea viewer automatically aborts the action.)
Note: When an action is proceeded or aborted, the corresponding ActionArea becomes dormant, its second menu line disappears, and control transfers back to the suspended WorkArea, if any. You cannot type into a dormant ActionArea, though you can reference its & variables via the mechanism described earlier. However, the ActionArea stays around (unless the user explicitly destroys or closes it) so that it can be reused if another action arises out of the same parent WorkArea. Thus if you are proceeding from breakpoint to breakpoint while debugging a particular program, all of the breakpoints will be taken in the same ActionArea.
Source displays the source location for the current frame of the local context, if any, by creating or opening a viewer on the appropriate source file (perhaps automatically retrieving this file from a server) and setting the selection to a point near where control has stopped for the current action. If there is no current action, e.g. if you type Source to an Interpreter Area, the Source command will attempt to display the source for the current default global frame, if any.
WalkStack The WalkStack menu button allows you to change the context for interpreting expressions in the ActionArea.
Left click: walk one frame up the call stack, i.e. earlier in the stack.
Right click: walk one frame down the call stack, i.e. later in the stack.
Middle click: reset the context to what it was when the action occurred.
ShowFrame displays information about the current context (frame) as follows:
Left click: display just the frame name
Middle click: display the frame name plus its arguments.
Right click: display the frame name, the arguments, and local variables.
Thus, in the example above, if left click
WalkStack, and then middle click
ShowFrame in ActionArea B, I will see:
&5 WalkStack RopeImpl.Fetch
&6 ShowFrame args RopeImpl.Fetch
A- [base: "abc",
index: 5]
Whenever an action occurs, the current selection is saved before control transfers to an action area. If the current selection is in the action area when the user proceeds or aborts, the selection will be automatically restored. This allows the user to debug procedures that manipulate the current selection. The command ShowSelection can be used to show what the current selection would be restored to if the user proceeded or aborted the action. In addition, if the user invokes the command RestoreSelection, then the selection will be restored before executing each event. This allows the user to interpret expressions in the action area that depend on the current selection being what it was before the action occurred.
ShowSelection Shows what the current selection will be restored to when this action is proceeded or aborted.
RestoreSelection Specifies that the current selection should be restored before executing each event. This allows the user to interpret expressions in the action area that depend on the current selection being what it was before the action occurred.
Using the History facility
Each WorkArea has associated with it a history of all of the events that have taken place in that WorkArea. The user can examine this history via the History registered command, reexecute a particular event or events using the Redo command, or substitute new parameters (text strings) into a particular event or events and then reexecute them via the Use command.
Events can be indicated by (a) their event number, a positive integer; (b) relative event number, a negative integer which indicates how many events before the present, e.g. redo -1 refers to the last event; or (c) a pattern to be matched with any part of the input of the event, without regard for case, as follows: An expression of the form <id> will only match with id where its neighboring characters are not alphanumeric. An expression of the form ^text will only match with an event whose leading characters are text. Any other sequence of characters will match anywhere in the event. For example, redo <x> will redo the last event containing x as an identifier, and redo ^c might be used to redo a compile.
An event specification consists of a sequence of (a) (b) or (c), e.g. redo 4 5 -1, or redo comp bind.
The following three registered commands are currently provided for manipulating the history list.
History Shows the history. History´ shows entire history list. History {event specification} just the corresponding event(s), e.g. History -1
Redo replays the indicated event(s), e.g. redo comp bind.
Use Form is Use New For Old In {event specification}. e.g. use mesa for bcd in -1. Substitution is always on a character basis. If the event specification specifies more than one event, a compound event will be constructed. If there are more new arguments than old arguments, the substitution is distributed, e.g. Use 1 2 3 For 0 IN -1 -2 will construct an event consisting of the concatenation of the last two events, and then execute that event first with 1 substituted for 0, then 2 for 0 then 3 for 0. If the event specification is omitted, the first event that contains the first old argument is used, e.g. Use mesa For bcd will search for the first event containing 'bcd' and substitute in that. If no old argument is specified, and the event was itself the result of a use command, substitute for the original old arguments, e.g. use a for b, followed by use c d e is equivalent to use c d e for b. Finally, if no new arguments are specified, the first token in the corresponding event is used for old, e.g. compile mumble, followed by use bind.
Both the Redo and Use commands can be terminated by CTRL-X, in which case the corresponding command line is computed and stuffed in the input buffer, but not executed. The user can then edit the command before typing ´ to execute it.
As mentioned above, Redo can also be invoked via the Redo menu in the WorkArea. Select anywhere in an event and click redo to redo the corresponding event. Extend the selection across several events and click Redo and the corresponding events are redone. Clicking Redo with right button is the same as terminating Redo command with CTRL-X.
Confirmation
Occasionally the UserExec will attempt to correct an error: e.g. a misspelled file name, an invalid selector, syntax error, etc. In this situation, two new menu buttons, Yes and No, will be posted in the menu for the corresponding WorkArea. When/if the user is asked to confirm (depending on the settings in the user's profile, some errors may be corrected automatically), the user can confirm using these buttons, or by typing Y or N. The user can also confirm/reject ahead as soon as the buttons are posted. Rejecting ahead has the effect of stopping the attempted correction (which is not as severe as clicking Stop, which aborts the event as well as the correction). If the user has typed ahead before the need for confirmation was detected, the typeahead will be retained, and the user must confirm using the Yes and No buttons.
Session Log
The system will automatically keep a log of your entire session on the file Session.Log, unless you have an entry in your userprofile of the form CreateSessionLog: FALSE. This log will consists of all of the input/output in each work or action area, plus the material that is written to your changes log (see NewStuff.tioga), suitably bracketed so as to make it readable. A new log is created whenever you boot, and the existing log, if any, renamed to be Session.Log$. (You can also specify that the new log simply be appended to the existing log via your userprofile. For more information, see UserProfileDoc.Tioga.) This feature is quite useful for after-the-fact debugging, i.e. for you, or a wizard, to look back at what you did in a previous session.