TIP #227: Interface to Get and Set the Return Options of an Interpreter
From: Don Porter (dgp_at_users.sf.net)
Date: 11/04/04
- Next message: Don Porter: "TIP #226: Interface to Save and Restore Interpreter State"
- Previous message: Bruce Hartweg: "Re: listbox doesn't resize with contents"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Date: Thu, 4 Nov 2004 19:10:53 +0000 (UTC)
TIP #227: INTERFACE TO GET AND SET THE RETURN OPTIONS OF AN INTERPRETER
=========================================================================
Version: $Revision: 1.1 $
Author: Don Porter <dgp_at_users.sf.net>
State: Draft
Type: Project
Tcl-Version: 8.5
Vote: Pending
Created: Saturday, 30 October 2004
URL: http://purl.org/tcl/tip/227.html
WebEdit: http://purl.org/tcl/tip/edit/227
Post-History:
-------------------------------------------------------------------------
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 is the return code
that the *return* command would return given the same options. In fact,
a valid implementation for the *return* command would be:
int Tcl_ReturnObjCmd(ClientData cd, Tcl_Interp *interp,
int objc, Tcl_Obj *const objv[])
{
int explicitResult = (0 == (objc %2));
int numOptions = objc - 1 - explicitResult;
if (explicitResult) Tcl_SetObjResult(interp, objv[objc-1]);
return Tcl_SetReturnOptions(interp, Tcl_NewListObj(numOptions, objv+1));
}
Note that /Tcl_SetReturnOptions/ is like /Tcl_SetObjResult/ and
/Tcl_SetVar2Ex/ in that you can pass it a newly created Tcl_Obj
confident that it will be freed later. No refCount manipulation is
required.
The /Tcl_GetReturnOptions/ routine is used by *catch* to fetch the
value to be stored in the /optionsVarName/ variable, if any. The
/result/ argument should be whatever return code was returned by the
script evaluation, or other /interp/ activity whose return options you
wish to retrieve.
The /(Tcl_Obj *)/ returned by /Tcl_GetReturnOptions/ points to a newly
created, unshared *Tcl_Obj*. It can be written to as returned; no need
to implement copy-on-write checks. In particular, new key value pairs
can be added to the dictionary, or existing ones changed or removed. As
noted above, such a value is also suitable for passing right back to
/Tcl_SetReturnOptions/.
COMPATIBILITY
===============
Some extensions provide commands that offer the ability to evaluate a
Tcl script in some other context, and return the complete result of
that evaluation. For example, the *Thread* package provides the
*thread::send* command that evaluates a script in another interp in a
different thread. The *thread::send* command ultimately has a return
code and a result that matches those produced by the script evaluation
in the other thread. Furthermore, the *::errorInfo* and *::errorCode*
variables are set according to the script evaluation outcome in the
other thread as well. Extensions that accomplish such passing of full
evaluation results achieve it now with copies of all portions of the
full evaluation results: the return code, the interp result, and when
appropriate, the values of *::errorInfo* and *::errorCode*.
Such mechanisms will continue to work unchanged in Tcl 8.5. However,
they will no longer represent the /complete/ evaluation results of the
script. In order to continue to communicate back the full outcome of
script evaluation, these extensions will want to call
/Tcl_GetReturnOptions/ after the script completes, transport that value
back, and call /Tcl_SetReturnOptions/ in the original interp. Note that
use of these routines will automatically take care of *::errorInfo* and
*::errorCode*, so the complete outcome of script evaluation will be
able to be communicated by the return code, the interp result, and the
dictionary of return options. Because the return options dictionary is
itself extensible, this interface will not need to change again.
REFERENCE IMPLEMENTATION
==========================
Pending...
COMMENTS
==========
Please make any comments here.
COPYRIGHT
===========
This document has been placed in the public domain.
-------------------------------------------------------------------------
TIP AutoGenerator - written by Donal K. Fellows
[[Send Tcl/Tk announcements to tcl-announce@mitchell.org
Announcements archived at http://groups.yahoo.com/group/tcl_announce/
Send administrivia to tcl-announce-request@mitchell.org
Tcl/Tk at http://tcl.tk/ ]]
- Next message: Don Porter: "TIP #226: Interface to Save and Restore Interpreter State"
- Previous message: Bruce Hartweg: "Re: listbox doesn't resize with contents"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Relevant Pages
|
