\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#336: Supported Access To interp-\tiprangle{}errorline}
\date{October 21, 2008}
\author{Don Porter}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#336}&\textbf{Supported Access To interp-\tiprangle{}errorline}\\\hline
Author&

Don Porter \tipmail{dgp}{users.sf.net}
\\
Created&Tuesday, \(\text{21}^{\text{st}}\) October 2008\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.4 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a supported public interface to set and get the value of the \textit{errorLine} field of the \textit{Tcl\_Interp} data structure.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Background}

A more forceful barrier to direct access to the \textit{result} and \textit{freeProc} fields of the \textit{Tcl\_Interp} data structure has just been accepted \cite{tip330}. This revision leaves only the \textit{errorLine} field still normally publicly visible. The visibility of this field prevents the realization of \textit{Tcl\_Interp} as a fully opaque data structure.

The \textit{result} and \textit{freeProc} fields have long had the recommended alternatives of \textbf{Tcl\_GetStringResult} and \textbf{Tcl\_SetResult} which make direct access unnecessary. The \textit{errorLine} field has long gone without such alternatives. Starting with Tcl 8.5, some alternatives do exist. The value of the \textit{errorLine} field can be set by passing an appropriate dictionary to \textbf{Tcl\_SetReturnOptions} and the value can be retrieved from the dictionary returned by passing \textbf{TCL\_ERROR} to \textbf{Tcl\_GetReturnOption} \cite{tip227}. The housekeeping burden of these alternatives is significant, so there's little attraction for replacing direct access to the \textit{errorLine} field with them.

Specialized routines already exist for managing the fully private fields \textit{errorInfo} and \textit{errorCode} in the opaque part of the \textit{Interp} data structure, \textbf{Tcl\_SetErrorCode}, \textbf{Tcl\_AddErrorInfo}, etc. The management of these values is needed frequently enough to make simplified alternatives like this worthwhile.

\section{Proposal}

Create the following new public routines to get and set the \textit{errorLine} field:

\begin{quote}
int \textbf{Tcl\_GetErrorLine}(Tcl\_Interp *\textit{interp})
\end{quote}

\begin{quote}
void \textbf{Tcl\_SetErrorLine}(Tcl\_Interp *\textit{interp}, int \textit{value})
\end{quote}

These will be implemented as (equivalent to):
\begingroup\small\begin{verbatim}
int Tcl_GetErrorLine(Tcl_Interp *interp) {
    return ((Interp *) interp)->errorLine;
}

void Tcl_SetErrorLine(Tcl_Interp *interp, int value) {
    ((Interp *) interp)->errorLine = value;
}
\end{verbatim}
\endgroup

In addition, following the example of \cite{tip330}, disable the default public access to the \textit{errorLine} field, permitting the restoration of access only when the \textbf{USE\_INTERP\_ERRORLINE} directive is defined.

\section{Compatibility}

This change is a source incompatibility with C code directly accessing the \textit{errorLine} field. The quick fix to restore compatibility is to define \textbf{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.

\section{Rationale}

This is the last stepping stone to prepare the way for \textit{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 \cite{tip330}. 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.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#2}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#227]{tip227}
Don Porter,
\emph{Interface to Get and Set the Return Options of an Interpreter},
on-line at \url{http://purl.org/tcl/tip/227.html}
\bibitem[TIP \#330]{tip330}
Kevin B. Kenny,
\emph{Eliminate interp-\tiprangle{}result from the Public Headers},
on-line at \url{http://purl.org/tcl/tip/330.html}
\end{thebibliography}
\end{document}
