Atom USING [GetPName],

CIFS USING [GetFC, Open, read],

Commander USING [CommandProc, CommandObject, Enumerate, Lookup, Register, Handle],

ConvertUnsafe USING [AppendRope],

Exec USING [commandLine],

File USING [Capability, nullCapability],

FileIO USING [Open, OpenFailed],

Generator USING [Handle, Produce],

IO USING [AppendStreams, ChangeDeliverWhen, Close, CreateFilterCommentsStream, CR, DeliverWhenProc, EndOf, EveryThing, GetOutputStreamRope, LookupData, PeekChar, PutChar, PutF, PutRope, RemoveData, rope, ROPE, RIS, ROS, SetEcho, SetIndex, SP, StoreData, STREAM, BreakProc, CharProc, GetSequence, GetToken, GetRefAny, IDProc, SkipOver, WhiteSpace],

List USING [DotCons, Nconc1, Sort],

MessageWindow USING [Append],

ProcessProps USING [AddPropList],

CommandProcOps USING [PutProperty],

Rope USING [Cat, Concat, Equal, Fetch, Find, IsEmpty, Length, Replace, Substr],

RTFiles USING [GetMapList],

Spell USING [GeneratorFromEnumerator, SpellingGenerator, IsAPattern, Modes],

TTY USING [Handle],

SymTab USING [Create, Fetch, Store, Ref],

UnsafeStorage USING [GetSystemUZone],

UserExec USING [DoIt, AcquireResource, CommandProc, ExecHandle, GetMatchingFileList, GetStreams, GetTheOne, MethodProc, ReleaseResource, ErrorThisEvent, AcquireStreams, ReleaseStreams, TransformProc, HistoryEvent],

UserExecExtras USING [CorrectionDisabled],

UserExecPrivate USING [CommandRecord, commandString, EventFailed, ExecDeliverWhen, ExecPrivateRecord, GetExecFromStream, HistoryEventPrivateRecord, FileNotFound, methodList, MethodRecord, PrintCommand, RopeFromCMFile, RunBCDFile, StripComments, w, Zone, GetPrivateStuff],

UserProfile USING [CallWhenProfileChanges, ProfileChangedProc, Token],

VersionMapOps USING [SourceFileList, FindSource]

;

Event argument to GetTheOne etc for supporessing correction, could be done via property list mechanism.

Larry and I spent an interesting hour discussing the technical aspects of how we could have the best of both worlds, namely that clients could register themselves with the Commander and would be able to be invoked in leaner meaner cedar, but magically, when running in the full Cedar world, would behave as they now do. I then went off and spent several hours examining in detail the difference between the Commander interface and UserExec interface with an eye to implementing the latter in terms of the former, and trying to identify what functionality, if any would be lost. This process has led me to a clear(er) espousal of the differences (actually fairly small) between Commander and UserExec, and to a specific proposal consisting of two small changes to the Commander interface which would accomplish all of the desired goals. I submit both espousal and proposal for your consideration.

A Commander CommandProc traffics in an object called a Handle, which basically consists of input and output streams, the commandLine and commandName, and a catch all propertyList. UserExec CommandProcs are more complicated. They take three arguments, an event and a handle, and a clientData field. Basically, the event corresponds to, and contains the commandLine/command information, and the handle contains the stream information (which must be accessed via a procedure rather than directly - more on this later). The clientData field contains information particular to the command so that the same commandProc can be used to implement several different commands, as is the case with the expansion of aliases, treatment of commands registered in catalogue, etc. This sort of technique is used in other interfaces such as Menus, and was originally championed by Russ.

UserExec CommandProcs also return two values, one which says that everything was ok, and the other a rope. In most cases these are TRUE and NIL. One could imagine an implementation in which for the exceptional case, the client called a procedure which recorded the relevant information in the event, or raised a signal, etc. In other words, it would be possible to eliminate this difference and have a UserExec.CommandProc not return a value and still retain all of the current functionality.

So we are left with two issues: why does the UserExec.CommandProc need two pieces of information and the Commander only one, and why are these two pieces of information so much more complicated than the Commander.Handle, which consists of only six fields? Let's consider the latter question first, since it really is a red herring.

The UserExec ExecHandle is actually pretty simple. It just consists of a viewer and a privateData field. The event also has a private data field, but it in addition exposes some other information which I thought might be useful to some clients, such as an expression field which helps when dealing with interpreter, e.g. you can see if any corrections were made, a dontCorrect field, so that clients that call the spelling corrector etc. don't have to worry about those situations where they shouldn't, e.g. the run command does not attempt correction when it is executing an event from a command file, whereas it does when coming from the keyboard, etc. I could also have provided this information via procedures for those exceptional clients that needed it. We all know that, in general, procedural interfaces allow the implementor more freedom to change his representation without affecting his clients, but make it slightly more cumbersome for the clients to access the relevant information.

The main reason that the UserExec type structure looks so complicated and the Commander so simple is that the behind the scenes implementation information in the Commander is stored on the property list of the handle, rather than in a declared field in the record. In the same way as the private data field in the UserExec represents an attempt to provide for more interface stability by using an opaque type in order not to commit to a particular representation, the Commander goes one step further by removing all mention of this information from the interface. This gives maximal freedom to the implementor while running the risk of postponing certain errors to runtime that would normally be caught by the compiler. Had I used the same approach for the UserExec, the data structure for an event and a handle would look pretty much the same as it does for Commander.

So the main difference is the division of the information needed by the commandProc into two arguments, the event and the handle, and the fact that the streams have to be obtained via a procedure (both changes made for 4.0). What does this buy?

The main area I was attacking was to make it possible for a client to invoke a command proc when the client didn't have an execHandle in hand (e.g. from Walnut, Russ's compiletool, or some other tool based application). I did not want to force the client to create an execHandle, complete with historylist, viewer, symbol table, etc., because in most of these applications, there would be no output/input unless something went wrong. Another related issue was that a command proc running under a particular execHandle ought to be able to FORK its execution, which might not complete until after several more events were executed under the same handle. The latter was not possible previously because all event-related information, such as the commandLine, was stored in the UserExec Handle, and got overwritten with each event. (Interestingly enough, this shortfall was first pointed out to me by Larry Stewart.) Given the possibility of events executing asynchronously and simultaneously under the same handle, I wanted some method of synchronizing, i.e. locking, the input/output streams. The procedural access to the streams provides a way of making sure these two events don't intermix their input/output by assigning the streams to one and only one event. Furthermore, I only assign those streams when they are needed so that if an event does not require input/output it can execute "silently" at the same time as another event. However, Larry pointed out that one could accomplish the same thing with a special kind of stream which did acquired the underlying streams when they were first needed. I wish I had thought of that earlier, and will use this idea in accomodating to the Commander interface which requires that the streams be available through the handle directly.

So, the bottom line is, there are very few unresolved differences between the two ways of doing business. In fact, we can get the best of both worlds, as follows (each of these changes are independent and obtains the indicated benefit. They can be accepted or rejected independently.):

(1) Change Commander.Register by adding a clientData field argument which is passed to the CommandProc.

(2) Change the type of CommandProc by adding an event argument, where event is defined trivially as a REF RECORD[commandLine: Rope.ROPE, command: Rope.ROPE, propertyList: List.AList],

What I could do with this is to store the UserExec Handle on the commander handle's property list, and similarly store the HistoryEvent on the Commander Events property list. I would provide procedural interfaces in the UserExec for obtaining this information for those clients who need to invoke operations available only through the UserExec interface, such as DoIt, or GetTheFile, etc, and to allow me to register all of my commandprocs as CommanderProcs. All would be wonderful!

One more minor change is necessary to AskUser due to its special nature. The current version of AskUser provided by UserExec correctly handles type ahead in the presence of an AskUser interaction by posting a menu and ignoring the keyboard. In the new scheme of things, AskUser is being moved to IO because bringover/smodel use it, and they are in the kernel, whereas the UserExec is not. Therefore, a simpler version of AskUser was implemented which takes two streams as arguments and does all of its interactions with the keyboard. How can we arrange things so that when called from a WorkArea in a full Cedar, AskUser, i.e. smodel, bringover, etc., will automatically behave as they do now?

(3) Instead of taking two streams, change IOMisc.AskUser to take a Commander.Handle (actually a REF ANY which is NARROWED to a Commander.Handle in order to avoid interface circularities), which contains these streams.

I understand that Paul has already committed, i.e. compiled some of his code to use depend on Commander and IOMisc.AskUser. I would be willing to remake those components with the new interface if it would make his response more positive. I think that there are a lot of benefits to be obtained with the above proposal.


warren

any error coming out of running registered command, included aborted, was causing it to attempt to load version maps.

changes to: CallRegisteredProc, CallRegisteredProc

changes to: GetCommands (local of GetRegisteredCommands) added .bcd to name obtained from registered commands catalogue when no extension specified., UserProfile, END

changes to: RegisterCommanderProc, CommanderProcRecord, CallCommanderProc, END, DIRECTORY, IMPORTS, CallRegisteredProc, LookupGenerate, CallRegisteredProc, IsACommanderProc (local of CallRegisteredProc), RegisterCommanderStuff, register (local of RegisterCommanderStuff), RegisterCommanderStuff, UserProfile, DIRECTORY, IMPORTS, IsACommanderProc (local of CallRegisteredProc), CallRegisteredProc, DIRECTORY, CallRegisteredProc, RegisterCommanderStuff, register (local of RegisterCommanderStuff), EndOps, UserProfile, DIRECTORY, IMPORTS, UserProfile, register (local of RegisterCommanderStuff), register (local of RegisterCommanderStuff

changes to: CallRegisteredProc, CallCommanderProc, registrationTable, GetRegistrationData, Register, proc (local of LookupEnumerate), Register, LookupCommand, DIRECTORY, LookupCommand, DIRECTORY, Register, GetRegistrationData, RegisterData, DIRECTORY, IMPORTS, CallCommanderPro

changes to: DIRECTORY, IMPORTS, CallCommanderProc, CallRegisteredProc, inner (local of CallCommanderProc), IMPORTS, CallCommanderProc, inner (local of CallRegisteredProc), CallRegisteredProc, CallCommanderProc, inner (local of CallRegisteredProc), CallRegisteredProc, inner (local of CallRegisteredProc), inner (local of PushPropsAndCallProc), PushPropsAndCallProc, inner (local of CallCommanderProc), CallCommanderProc

changes to: CallRegisteredProc