CTCLException

DESCRIPTION

The CTCLException class allows you to instantiate and throw exceptions that are distinguishable as coming from the TCL library and its extensions. In most cases the TclPlus library itself will convert error conditions detected by the Tcl API and intantiate and throw an appropriate exception.

The following example shows how to execute code that is aware of these exceptions. In this case, the code just reports the error message and continues.

    try {
        // In here is TclPlus invoking code.
    }
    catch (CTCLException& e) {
        cerr << "TclPlus error caught: " << e.ReasonText() << endl;
    }
            

The following example shows a typical code segment that throws a CTCLException:

    int status = Tcl_xxxxxxx(pInterp->getInterpreter()....); // Some Tcl call.
    if (status != TCL_OK) {
        throw CTCLException(*pInterp, status,
                            "Call to Tcl_xxxxxx returned an error");
    }
                

Note that constructing a CTCLException object incorporates the Tcl result string at the time into the text returned by the ReasonText() member function.

METHODS

  CTCLException (CTCLInterpreter& rInterpreter,
                 Int_t nReason,
                 const char* pString);
  CTCLException(CTCLInterpreter& rInterpreter,
                Int_t nReason,
                const std::string& rString);
  CTCLException (const CTCLException& aCTCLException );
        

These construct a CTCLException. rInterpreter is a reference to the intepreter that was used in the operation that resulted in the error. The result string of that interpreter will be saved as part of the text returned by the ReasonText member function.

The nReason is a reason for the exception. Typically this will be TCL_ERROR however other error codes can be created and used for application specific problems. This is the value that will be returned by the ReasonCode member function.

rString and pString are intended to provide information about the context of the error, and will be incorporated into the text strin greturned from ReasonText.

aCTCLException is a reference for the sourc object of the copy constructor.

  CTCLException operator= (const CTCLException& rhs);
  int operator==(const CTCLException& rhs);
        

These two functions provide a mechanism to assign exceptions and to compare them for equality. rhs is the object that is the source of the assignment or the object to which this is being compared. Equality is defined as the two exceptions having the same underlying interpreter, and same reason text.

  void AddErrorInfo (const char* pMessage)  ;
  void AddErrorInfo(const std::string& rMessage);
  void AddErrorInfo(const CTCLString& rMessage);
        

These functions are wrapperf ro the API function Tcl_AddErrorInfo the pMessage, and rMessage parameters provide the message that is added to the errorInfo variable.

  void SetErrorCode (const char* pMessage,
                     const char* pMnemonic="???",
                     const char* pFacility="TCL",
                     const char* pSeverity="FATAL")  ;
  void SetErrorCode(const std::string rMessage,
                    const std::string& rMnemonic=std::string("???"),
                    const std::string& rFacility=std::string("TCL"),
                    const std::string& rSeverity=std::string("FATAL"));
        

These function set the errorCode Tcl interpreter variable. The convention these function support is to set the error code to a list that consists of a message (pMessage and rMessage, mnemonic for the message (pMnemonic or rMnemonic, the Facility (pFacility or rFacility)that is throwing the error and the severity (pSeverity or rSeverity) of the error.

virtual   const char* ReasonText () const;
virtual   Int_t ReasonCode () const  ;
        

These two functions are intended for use by exception catch blocks. ReasonText provides human readable text that describes the exception. ReasonCode provides a numerical code that describes the exception. Often this just has the value TCL_ERROR

SEE ALSO

Tcl_AddErrorInfo(3tcl), Tcl_SetErrorCode(3tcl)