TIP #336: SUPPORTED ACCESS TO INTERP->ERRORLINE 
=================================================
 Version:      $Revision: 1.4 $
 Author:       Don Porter <dgp_at_users.sf.net>
 State:        Final
 Type:         Project
 Tcl-Version:  8.6
 Vote:         Done
 Created:      Tuesday, 21 October 2008
 URL:          https://tip.tcl-lang.org336.html
 Post-History: 

-------------------------------------------------------------------------

 ABSTRACT 
==========

 This TIP proposes a supported public interface to set and get the value 
 of the /errorLine/ field of the /Tcl_Interp/ data structure. 

 BACKGROUND 
============

 A more forceful barrier to direct access to the /result/ and /freeProc/ 
 fields of the /Tcl_Interp/ data structure has just been accepted [TIP 
 #330]. This revision leaves only the /errorLine/ field still normally 
 publicly visible. The visibility of this field prevents the realization 
 of /Tcl_Interp/ as a fully opaque data structure. 

 The /result/ and /freeProc/ fields have long had the recommended 
 alternatives of *Tcl_GetStringResult* and *Tcl_SetResult* which make 
 direct access unnecessary. The /errorLine/ field has long gone without 
 such alternatives. Starting with Tcl 8.5, some alternatives do exist. 
 The value of the /errorLine/ field can be set by passing an appropriate 
 dictionary to *Tcl_SetReturnOptions* and the value can be retrieved 
 from the dictionary returned by passing *TCL_ERROR* to 
 *Tcl_GetReturnOption* [TIP #227]. The housekeeping burden of these 
 alternatives is significant, so there's little attraction for replacing 
 direct access to the /errorLine/ field with them. 

 Specialized routines already exist for managing the fully private 
 fields /errorInfo/ and /errorCode/ in the opaque part of the /Interp/ 
 data structure, *Tcl_SetErrorCode*, *Tcl_AddErrorInfo*, etc. The 
 management of these values is needed frequently enough to make 
 simplified alternatives like this worthwhile. 

 PROPOSAL 
==========

 Create the following new public routines to get and set the /errorLine/ 
 field: 

       int *Tcl_GetErrorLine*(Tcl_Interp */interp/) 

       void *Tcl_SetErrorLine*(Tcl_Interp */interp/, int /value/) 

 These will be implemented as (equivalent to): 

   int Tcl_GetErrorLine(Tcl_Interp *interp) {
       return ((Interp *) interp)->errorLine;
   }
   
   void Tcl_SetErrorLine(Tcl_Interp *interp, int value) {
       ((Interp *) interp)->errorLine = value;
   }

 In addition, following the example of [TIP #330], disable the default 
 public access to the /errorLine/ field, permitting the restoration of 
 access only when the *USE_INTERP_ERRORLINE* directive is defined. 

 COMPATIBILITY 
===============

 This change is a source incompatibility with C code directly accessing 
 the /errorLine/ field. The quick fix to restore compatibility is to 
 define *USE_INTERP_ERRORLINE*. The next step for migrating old code 
 would be to adopt the new routines, and offer macros to duplicate the 
 effect of the new routines when older Tcl headers are in use. 

 RATIONALE 
===========

 This is the last stepping stone to prepare the way for /Tcl_Interp/ to 
 become a fully opaque data structure. The rationale for the immediate 
 disabling of public access is to (over?)learn the lesson of [TIP #330]. 
 No matter how sternly you warn about deprecation, nothing happens until 
 you turn it off, so let's move immediately to turning it off, with the 
 burden on the users to restore what they need. 

 COPYRIGHT 
===========

 This document has been placed in the public domain. 

-------------------------------------------------------------------------

 TIP AutoGenerator - written by Donal K. Fellows