Tcl Error Stack Extensions

Dervish provides both C routines and Tcl procedures the ability to push messages onto an error stack, independent of Tcl's built in error handling (errorInfo and errorCode). Only one error stack exists for a Dervish task. Users can push errors encountered during code development onto the error stack and review them later.

The stack is circular, retaining the most recently added error strings. As error messages are pushed onto the stack (with errStackPushC), they may overflow, causing the oldest messages in the stack to be discarded. Messages can be retrieved from the error stack, the latest message first, then the one pushed before that, and so forth.

The following Tcl procedures are made available:

  • errStackClear
  • errStackGetEarliest
  • errStackGetNext
  • errStackOverflow
  • errStackPush
  • The following routine is available for use within the C code of a Tcl procedure:

  • shTclInterpAppendWithErrStack
  • 
    
    

    Automatic Clearing of the Error Stack

    The user can explicitly clear the error stack with errStackClear. But, the error stack is also automatically cleared. When a Tcl command is issued at the top level Tcl interpreter (level 1), the first errStackPush will first clear the error stack. This push can be nested many levels down. Subsequent pushes onto the error stack below the top level of the Tcl interpreter will not clear the stack. This behaviour is very similar to how Tcl handles its global variable errorInfo with Tcl_AddErrorInfo().

    This automatic clearing of the error stack relieves the user from clearing the stack. Yet, it permits the contents of the error stack to be retrived by later Tcl or C commands at the top level of the Tcl interpreter. The only side effect occurs at the top level of the Tcl interpreter: only one error message can be effectively pushed onto the error stack, since each push will be the first since entering/returning to the top level of the Tcl interpreter.

    errStackClear

    _______________________________________________________________________________ NAME errStackClear - Clear the error stack of all messages SYNOPSIS (Tcl Syntax) errStackClear ARGUMENTS (None) RETURN VALUES TCL_OK Success. Successful completion. The interp result string is empty. TCL_ERROR Failure. The interp result string contains an error message. _______________________________________________________________________________ DESCRIPTION

    Clear the error stack of all messages.

    errStackGetEarliest

    _______________________________________________________________________________ NAME errStackGetEarliest - Get the last message pushed onto the error stack SYNOPSIS (Tcl Syntax) errStackGetEarliest ARGUMENTS (None) RETURN VALUES TCL_OK Success. Successful completion. The interp result string contains the latest error stack message. TCL_ERROR Failure. The interp result string contains an error message. _______________________________________________________________________________ DESCRIPTION

    Return the last message pushed onto the error stack. If the error stack is empty, an null string will be returned. This routine should be called before any calls to errStackGetNext are made as errStackGetEarliest resets the stack retrieval pointers. Subsequent calls to errStackGetNext will properly return the next older message (in a LIFO (Last In First Out) fashion).

    errStackGetNext

    _______________________________________________________________________________ NAME errStackGetNext - Get next message from the error stack SYNOPSIS (Tcl Syntax) errStackGetNext ARGUMENTS (None) RETURN VALUES TCL_OK Success. Successful completion. The interp result string contains the next error message. TCL_ERROR Failure. The interp result string contains an error message. _______________________________________________________________________________ DESCRIPTION

    Return the next message up the stack relative to the current stack retrieval pointer. Messages are returned in a LIFO (Last In First Out) fashion. The stack retrieval pointer will also be updated. errStackGetEarliest should be called to get the last message pushed onto the stack and set the stack retrieval pointer to a known location. If no more messages are on the stack, a null string is returned. Continued calls to errStackGetNext will wrap around the error stack (through all the empty messages) back to the top message on the stack.

    errStackOverflow

    _______________________________________________________________________________ NAME errStackOverflow - Get number of times the error stack overflowed SYNOPSIS (Tcl Syntax) errStackOverflow ARGUMENTS (None) RETURN VALUES TCL_OK Success. Successful completion. The interp result string contains the number of times the error stack has overflowed since the last clearing. TCL_ERROR Failure. The interp result string contains an error message. _______________________________________________________________________________ DESCRIPTION

    Return the number of times the error stack overflowed (by pushing messages with errStackPush) since the last time the stack was cleared (errStackClear). If no overflows have occurred, zero (0) is returned. An overflow condition is not fatal, it only indicates that some error messages have been lost.

    errStackPush

    _______________________________________________________________________________ NAME errStackPush - Push a message onto the error stack SYNOPSIS (Tcl Syntax) errStackPush <format> [arg1 [...]] format The format control string. The Tcl format command is used to format the resulting string. argn The arguments consumed by the conversion specifications in the format control string. RETURN VALUES TCL_OK Success. Successful completion. The interp result string is empty. TCL_ERROR Failure. The interp result string contains an error message. _______________________________________________________________________________ DESCRIPTION

    Format an error string and push it onto the error stack. If the pushing onto the error stack results in an overflow, the earliest messages are discarded as necessary to make room for the new message. Formatting of the message is specified with the Tcl format format control string. A newline (\n) is automatically appended to the error message.

    If this is the first push onto the error stack since the top level of the Tcl interpreter (level 1) was entered, the error stack is cleared prior to the pushing of the formatted message.

    shTclInterpAppendWithErrStack

    The pure C layer of DERVISH supports an error stack, allowing a routine to return long paragraphs of error information. This routine sets Interp->result to a list of the error strings set in the errstack. If the user types the word in interactively, or uses Tcl's default error processing in a procedure, the error information will be printed out. If the user uses the TCL verb CATCH to handle an error explicitly, the error text can be manipulated by other TCL words.

    C SYNTAX: void shTclInterpAppendWithErrStack ( Tcl_Interp *interp /* MOD: Interpreter to set the result for */ ) RETURNS: None.