TIP #227 Version 1.5: Interface to Get and Set the Return Options of an Interpreter

This is not necessarily the current version of this TIP.

Abstract

This TIP proposes new public C routines to allow the same access to interpreter return options TIP #90 as are provided at the script level by the catch and return commands.

Background

In Tcl 8.5, the return command has aready been extended to accept all option value pairs passed to it as arguments, to permit extensions to augment any custom return code values with whatever additional data values are appropriate. The errorInfo and errorCode values associated with the TCL_ERROR return code are already converted to this mechanism.

The ability to set custom return options in the interp has been limited to the script level though. For extension commands implemented entirely in C, it is inconvenient and somewhat unreliable to perform a Tcl_Eval("return ...") to be able to access this capability.

Likewise, the catch command is able to capture the current set of return options in the interp, but doing so requires both a script level command, and use of a variable. Extension commands implemented in C are better served with a direct interface to fetch the dictionary value.

Proposal

Two new routines will be added to Tcl's public stub table:

int Tcl_SetReturnOptions(Tcl_Interp *interp, Tcl_Obj *options)

Tcl_Obj *Tcl_GetReturnOptions(Tcl_Interp *interp, int result)

These routines already exist in the HEAD of Tcl's development sources, but as private routines. The Tcl source code itself already makes calls to these routines where appropriate, and their functioning is tested by the test suite. This TIP merely proposes making these routines available as part of the public interface.

The Tcl_SetReturnOptions routine is essentially equivalent to the return -options command. The int value returned