TIP:		56
Title:		Standardize Call Interface to Tcl_Eval* Functions
State:		Final
Type:		Project
Tcl-Version:	8.4
Vote:		Done
Post-History:	
Version:	$Revision: 1.4 $
Author:		Miguel Sofer <msofer@users.sourceforge.net>
Created:	28-Aug-2001

~ Abstract

This TIP replaces ''Tcl_EvalTokens'' with ''Tcl_EvalTokensStandard'',
which obeys the standard result management conventions for script
evaluation functions.

~ Rationale

The standard call interface for ''Tcl_Eval*'' functions returns a Tcl
completion code (TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or
TCL_CONTINUE), and sets a result object in the interpreter.  The
single exception is the function ''Tcl_EvalTokens'', that returns a
pointer to the result object, or a NULL when an exception occurs.
This effectively transforms all exceptions into errors.  This TIP
proposes to replace ''Tcl_EvalTokens'' with a new function
''Tcl_EvalTokensStandard'' that performs the same chores but adheres
to the standard call interface.

There are two arguments for the replacement of ''Tcl_EvalTokens'':

   * Present a consistent call interface to all ''Tcl_Eval*''
     functions.

   * Allow the return of non-error exceptional returns when evaluating
     tokens; the impossibility to do this is the cause of Bugs #455151
(https://sourceforge.net/tracker/index.php?func=detail&aid=455151&group_id=10894&atid=110894)
     and #219384
(https://sourceforge.net/tracker/index.php?func=detail&aid=219384&group_id=10894&atid=110894)

~ Proposed Change

The proposal is to deprecate the use of ''Tcl_EvalTokens'' and replace
it with a new ''Tcl_EvalTokensStandard''. The core should only use the
new function, the old one remains only for backward compatibility with
extensions.

The proposal is implemented in the patch included in [[Bug: 455151]]
https://sourceforge.net/tracker/index.php?func=detail&aid=455151&group_id=10894&atid=110894

~ Copyright

This document has been placed in the public domain.