CTCLProcessor

DESCRIPTION

Do not use this for new commands

The CTCLProcessor provides a compatibility interface to the old Tcl style argc, argv style of command extension. New commands should be written using the CTCLObjectProcessor class instead.

To extend the interpreter using this mechanism, you must derive a class from CTCLProcessor and minimally override and implement its operator() pure virtual function. You may optionally overrid its OnDelete member as well. Having written the class, you must create an object of that class and register it on an interpreter. Once the class is registered, invocations of the command under which it was registered will invoke your operator().

If the interpreter is destroyed or the object destroyed, or unregistered, the OnDelete member will be called. CTCLProcessor defines and implements this function with an empty body, so it is only necessary for you to override and implement this if you have some cleanup actions that must be done when the command is deleted.

This class is now implemented in terms of a CTCLObjectProcessor derived class called a CTCLCompatibilityProcessor. It is less efficient to use this class than to use a class derived directly from a CTCLObjectProcessor. This class is therefore not recommended for use with new extensions, but is only provided for compatibility with existing extensions written before CTCLObjectProcessor was developed.

METHODS

CTCLProcessor(const std::string sCommand,
             CTCLInterpreter* pInterp);
CTCLProcessor(const char*       pCommand,
             CTCLInterpreter* pInterp);
        

Constructs a CTCLProcessor. sCommand or pCommand are the initial name of the command. Note that the Tcl interpreter supports command renaming at the script level, so there is no gaurentee that this will always be the name of the command. pInterp is the interpreter on which the command will be registered when the Register function is called.

std::string getCommandName() const;
        

Returns the initial name of the command. Unlike CTCLObjectCommand::getName() this function does not track changes in the command name.

virtual int operator()(CTCLInterpreter& rInterpreter,
                       CTCLResult& rResult,
                       int argc,
                       char** argv) = 0;
virtual void OnDelete();
        

operator() is a pure virtual function and therefore must be overidden and implemented in concrete command implementations. rInterpreter is a reference to the interpreter that is executing this command. rResult is a reference to a CTCLResult object that represents the result of the interpreter. Any text stored into this object will be made available to the interpreter as the result of the command. argc and argv are the number of words on the command line and a pointer to an array of pointers to the command words respectively.

operator() should be written to return TCL_OK if it is successful and TCL_ERROR if it encounters an error. Other return values are possible and meaningful for commands that implement flow of control structures, but documenting these is beyond the scope of this manpage. See the return(3tcl) manpage for more information about these.

OnDelete is called whenever the interpreter or the object is being destroyed, or the object's Unregister function has been called. CTCLProcessor provides a default implementation for OnDelete which does nothing. It is only necessary to override and implement this function if you require specific action when the command is being unregistered.

void Register();
void Unregister();
        

These functions register and unregister the command with the intepreter respectively.

static  std::string ConcatenateParameters(int nArguments,
                                           char* pArguments[])  ;
        

Concatenates all of the nArguments words in the pArguments array into a std::string and returns it. The words are space separated.

int ParseInt(const char* pString,
             int* pInteger)  ;
int ParseInt(const std::string& rString,
             int* pInteger)
        

Parses the character string pString or rString as a 32 bit signed integer into pInteger. Returns TCL_OK if successful, or TCL_ERROR if the string coult no be parsed. In that case, the result string of the interpreter will report why the string could not be parsed.

int ParseDouble(const char* pString,
                double* pDouble)  ;
int ParseDouble(const std::string& rString,
                double* pDouble)
        

Parses the input string, either pString or rString as a double precision floating point value, storing the result in the double pointed to by pDouble. On success, TCL_OK is returned. On failure, TCL_ERROR and the interpreter result is a textual reason for the failure.

int ParseBoolean(const char* pString,
                 Bool_t* pBoolean)  ;
int ParseBoolean(const std::string& rString,
                 Bool_t* pBoolean)
        

Parses either pString or rString as a boolean value. The result is stored in boolean pointed to by pBoolean. TCL_OK is returned on success, TCL_ERROR on error. If TCL_ERROR was returned, the interpreter result is the textual reason for the failure.

static int MatchKeyword(std::vector<std::string>& MatchTable,
                        const std::string& rValue,
                        int NoMatch = -1);
        

Searches for the string rValue in the vector of strings MatchTable, and returns the index in the vector at which the match occured. If no match could be found, the value NoMatch is returned.

Within SpecTcl, this is often used to match command switches.

SEE ALSO

CTCLCompatibilityProcessor(3), CTCLObjectProcessor(3), CTCLPackagedCommand(3), CTCLResult(3), return(3tcl)