\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#36: Library Access to 'Subst' Functionality}
\date{June 13, 2001}
\author{Donal K. Fellows}
\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 \#36}&\textbf{Library Access to 'Subst' Functionality}\\\hline
Author&

Donal K. Fellows \tipmail{fellowsd}{cs.man.ac.uk}
\\
Created&Wednesday, \(\text{13}^{\text{th}}\) June 2001\\
Type&Project\\
Tcl Version&\(8.4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.4 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Some applications make very heavy use of the \textit{subst} command --- it seems particularly popular in the active-content-generation field --- and for them it is important to optimise this as much as possible. This TIP adds a direct interface to these capabilities to the Tcl library, allowing programmers to avoid the modest overheads of even \textit{Tcl\_EvalObjv} and the option parser for the \textit{subst} command implementation.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Functionality Changes}

There will be one script-visible functionality change from the current implementation; if the evaluation of any command substitution returns TCL\_BREAK, then the result of the \textit{subst} command will be the string up to that point and no further. This contrasts with the current behaviour where TCL\_BREAK (like TCL\_CONTINUE) just causes the current command substitution to finish early.

\section{Design Decisions}

The code should be created by effectively splitting \textit{Tcl\_SubstObjCmd} in the current \textit{.../generic/tclCmdMZ.c} into two pieces. One of these pieces will have the same interface as the present code and will contain the argument parser. The other piece will be the implementation of the \textit{subst} behaviour and will be separately exposed at the C level as well as being called by the front-end code.

The code should take positive flags stating what kinds of substitutions should be performed, as this is closest to the current internal implementation of the \textit{subst} command. These flags will be named with the prefix TCL\_SUBST\_*. For programming convenience, the flag TCL\_SUBST\_ALL will also be provided allowing the common case of wanting all substitutions to be performed with a minimum of fuss.

The string to be substituted will be passed in as a \textit{Tcl\_Obj *} too, as this is both easiest to do from the point-of-view of the front-end code and permits additional optimisation of the core at some future point if it proves necessary and/or desirable. By contrast, passing in a standard C string or a \textit{Tcl\_DString *} does not permit any such optimisations in the future.

The code should return a newly-allocated \textit{Tcl\_Obj *} as this allows for the efficient implementation of the front-end involving no re-copying of the resulting string. It also allows error conditions to be represented by NULL (with an error message in the interpreter result) and does not force a Tcl\_DString reference to be passed in as an \textit{out} parameter; returning the result gives a much clearer call semantics. Another advantage of using \textit{Tcl\_Obj}s to build the result is the fact that they have a more sophisticated memory allocation algorithm that copes more efficiently with very large strings; when large and small strings are being combined together (as is easily the case in \textit{subst}) this can make a substantial difference.

\section{Public Interface}

\textit{Added to .../generic/tcl.h}
\begingroup\small\begin{verbatim}
#define TCL_SUBST_COMMANDS    0x01
#define TCL_SUBST_VARIABLES   0x02
#define TCL_SUBST_BACKSLASHES 0x04
#define TCL_SUBST_ALL         0x07
\end{verbatim}
\endgroup

\textit{Added to .../generic/tcl.decls}
\begingroup\small\begin{verbatim}
declare someNumber generic {
    Tcl_Obj * Tcl_SubstObj( Tcl_Interp *interp,
                            Tcl_Obj *objPtr,
                            int flags)
}
\end{verbatim}
\endgroup

\section{Implementation}

The implementation is to be developed upon acceptance of this TIP, but will involve \textit{Tcl\_AppendToObj} and \textit{Tcl\_AppendObjToObj}.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
