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:
The following routine is available for use within the C code of a Tcl procedure:
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.
Clear the error stack of all messages.
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).
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.
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.
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.
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.