CTCLChannelCommander

Description

The CTCLChannelCommander is a class that registers an input event handler for a Tcl channel. When input is available on the channel, a line of text is read, and appended to a command under construction. When the command is syntactically complete, it is dispatched to a Tcl interpreter for execution.

The subclass CTCLStdioCommander is specifically tailored to accept commands on stdin. ALong with the server listener CTCLServer, CTCLTcpServerInstance is tailored to accpet commands on a socket.

Many aspects of the class are tailorable by overriding the various methods in derived classes. The class is capable of generating prompts in case the channel is interactive. The classs can also return the results of commands to the client over the medium of its choice. End file and exception handling can be simlarly tailored.

When deriving a specific class be sure you understand the default actions of all of the base class members. You may save a great deal of work by carefully chosing exactly which members to override, or generate a great deal of work by making poor choices.

Public member functions

Constructs a new channel commander. Activation of the commander is a two step process. First the commander is constructed, second it start method is called to register the event handlers.

interp is a pointer to the interpreter channel on to which the commands will be dispatched. channel is the channel from which commands will be accepted.

The application must also be visiting the event loop for commands to be processed from the channel. Tk applications automatically run the event loop. Pure Tcl applications run the event loop only when vwait is waiting, while the special shell or tcl applications based around CTCLLiveEventLoop run the event loop automatically just like Tk does.

Enables processing of commands from the channel. When the event loop is entered, if the channel is readable, control will be to onInput in object context. It is not considered an error to call start when event processing is in progress.

Requests channel processing be disabled. The event handlers that arrange for control to be dispatched to the onInput method are disabled. The channel remains open and must be closed (if desired) by any client software.

Returns the channel from which commands are being accepted.

This member function is called when data can be read from the input channel. The function attempts to read a line of text. The text is appended to a command under construction and, if Tcl_CommandComplete says that string is a syntactically complete command, onCommand is invoked to execute the command.

All of this command acquisition and exection is also mixed up with prompting. prompt1 is called when the object is ready to get a new command, and prompt2 is called when the object is ready to accept the next line of a multi-line command.

Called when an exception condition is detected on the channel. The default implementation calls onEndFile

Called when reads of the channel indicate an end file condition. onInputException's default implementation also calls this. The default behavior is to invoke stop so that no additional events will be posted. This is the normal and reasonable behavior because a channel with an endfile condition continously generates readable events.

The channel remains open. It is always up to client software to close the channel.

Called when a complete command has been accepted. Complete in this case means syntactically complete. It does not imply correctness, or even proper number of arguments.

Default behavior is to submit the command string to the interpreter. Once the command has been executed, returnResult is executed to allow the command result to be reported if desired.

By default this does nothing. It is provided to allow subclasses to tailore what is done with command results. For example, the CTCLStdioCommander class reports the result on stdout. CTCLTcpServerInstance on the other hand reports the result back to the client over the socket.

The GetResultString method of the interpreter object (the pointer m_pInterp is a pointer to the interpreter object) should be used to get the result string.

Called when its time to prompt for the first line of a command. This calls prompt1String to get the prompt string, and calls sendPrompt to actually emit the prompt.

Called when its time to prompt for additional linesof a command. This calls prompt2String to get the prompt string and calls sendPrompt to actually emit the prompt.

Prompting

The class provides a framework for prompting interactive channels. This frameworks is based on two prompt strings that can be gotten via calls to prompt1String and prompt2String respectively.

The first of these prompts is emitted when the software is ready to accept the first line of a new command. By default it is the text "% ". Scripts can customize this prompt by defining the variable tcl_prompt1 to be a script whose returned value is the prompt.

The second of these prompts is emitted when the software is ready to accept continuation lines of multiline commands. By default it is the text "%_ ". Scripts can customize this prompt by defining the variable tcl_prompt2 to be a script whose returned value is the desired prompt.