\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#356: NR-enabled Substitutions for Extensions}
\date{September 17, 2009}
\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 \#356}&\textbf{NR-enabled Substitutions for Extensions}\\\hline
Author&

Don Porter \tipmail{dgp}{users.sf.net}
\\
Created&Thursday, \(\text{17}^{\text{th}}\) September 2009\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.4 $\\
Keywords&Tcl, C API, subst\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes the new public routine \textbf{Tcl\_NRSubstObj} to provide extension commands that evaluate Tcl substitutions the ability to do so in a non-recursive manner.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Background}

Continuing in the path of \cite{tip322} and \cite{tip353}, we want extensions to be able to create NR-enabled commands, and any command procedures currently calling the \textbf{Tcl\_SubstObj} routine are not NR-enabled. The solution is to provide the NR-enabled counterpart.

\section{Proposal}

Add the following routine to Tcl's public interface:

\begin{quote}
int \textbf{Tcl\_NRSubstObj}(Tcl\_Interp *\textit{interp}, Tcl\_Obj *\textit{objPtr}, int \textit{flags})
\end{quote}

This routine places on the NR stack a request that the Tcl non-recursive trampoline evaluate the \textit{objPtr} value as a Tcl substitution in interpreter \textit{interp}, as controlled by the value of \textit{flags}. The \textit{flags} value is the same combination of \textbf{TCL\_SUBST\_BACKSLASHES}, \textbf{TCL\_SUBST\_COMMANDS}, and \textbf{TCL\_SUBST\_VARIABLES} that control \textbf{Tcl\_SubstObj}. This routine returns the value \textbf{TCL\_OK}, since there is (currently) no way this request operation can fail. The proposed interface still provides for an int return value so that future revisions to Tcl's internals have the freedom to change that without need to change the public interface.

After the trampoline completes the requested substitution, it will pass the return code, either \textbf{TCL\_OK} or \textbf{TCL\_ERROR}, to the next callback on the NR-stack, and either the result of the substitution or the error message will be stored in the result of \textit{interp}. The caller of \textbf{Tcl\_NRSubstObj} may also call \textbf{Tcl\_NRAddCallback} to request a \textbf{Tcl\_NRPostProc} callback routine be placed on the NR stack to receive these results, if needed to achieve the task the caller is performing.

\section{Implementation}

The proposed routine is already present in the HEAD of Tcl as the internal routine \textbf{TclNRSubstObj}. This proposal would simply promote it to Tcl's public interface.

\section{Compatibility}

There should be no compatibility issues, since at the interface level this is just the addition of a new routine.

\section{Migration}

As an example for extensions to follow, consider this template for a \textbf{Tcl\_ObjCmdProc} currently calling \textbf{Tcl\_SubstObj}.
\begingroup\small\begin{verbatim}
int ObjCmd(ClientData cd, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[])
    Tcl_Obj *resultPtr;
    /* determine text to be substituted, objPtr */
    /* determine flags value to control substitution */
    resultPtr = Tcl_SubstObj(interp, objPtr, flags);
    if (resultPtr == NULL) {return TCL_ERROR}
    /* resultPtr holds substitution result; continue */
}

Tcl_CreateObjCommand(interp, name, ObjCmd, /* ... */);
\end{verbatim}
\endgroup

To use \textbf{Tcl\_NRSubstObj} to NR-enable this command, rewrite along these lines:
\begingroup\small\begin{verbatim}
int ObjCmd(ClientData cd, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[])
{   return Tcl_NRCallObjProc(interp, NRObjCmd, cd, objc, objv);  }

int NRObjCmd(ClientData cd, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[])
{   
    /* determine text to be substituted, objPtr */
    /* determine flags value to control substitution */
    Tcl_NRAddCallback(interp, Callback, /*...*/);
    return Tcl_NRSubstObj(interp, objPtr, flags);
}

int Callback(ClientData data[], Tcl_Interp *interp, int code)
{   Tcl_Obj *resultPtr;
    if (code == TCL_ERROR) {return TCL_ERROR;}
    resultPtr = Tcl_GetObjResult(interp);
    /* resultPtr holds expression result; continue */
}

Tcl_NRCreateCommand(interp, name, ObjCmd, NRObjCmd, /*...*/);
\end{verbatim}
\endgroup

\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 \#322]{tip322}
Miguel Sofer,
\emph{Publish the NRE API},
on-line at \url{http://purl.org/tcl/tip/322.html}
\bibitem[TIP \#353]{tip353}
Don Porter,
\emph{NR-enabled Expressions for Extensions},
on-line at \url{http://purl.org/tcl/tip/353.html}
\end{thebibliography}
\end{document}
