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. Errors can then be appended onto the interp to enable them to be returned to Tcl.
The stack is circular, retaining the most recently added error strings. As error messages are pushed onto the stack (with shErrStackPush()), 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 Application Programming Interface (API) is made available:
The user can explicitly clear the error stack with shErrStackClear(). But, the error stack is also automatically cleared. When a Tcl command is issued at the top level Tcl interpreter (level 1), the first shErrStackPush() 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 C or Tcl 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, a NULL will be returned. This routine should be called before any calls to shErrStackGetNext() are made as shErrStackGetEarliest() resets the stack retrieval pointers. Subsequent calls to shErrStackGetNext() 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. shErrStackGetEarliest() should be called once to get the first (earliest) message and set the stack retrieval pointer to a known location. If no more messages are on the stack, a NULL is returned. Continued calls to shErrStackGetNext() will wrap around the error stack (ignoring any empty messages) back to the earliest message on the stack.
Return the number of times the error stack overflowed (by pushing messages with shErrStackPush()) since the last time the stack was cleared (shErrStackClear()). If no overflows have occurred, zero 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 a sprintf() 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.