TIP #336: Supported Access To interp->errorline

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.

[Index] [History] [HTML Format] [Source Format] [LaTeX Format] [Text Format] [XML Format] [*roff Format (experimental)] [RTF Format (experimental)]