\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#363: Vector Math in the Tcl Core}
\date{March 02, 2010}
\author{Karl C. Hansen}
\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 \#363}&\textbf{Vector Math in the Tcl Core}\\\hline
Author&

Karl C. Hansen \tipmail{Karl.Hansen}{BrilliantPoints.com}
\\
Created&Tuesday, \(\text{2}^{\text{nd}}\) March 2010\\
Type&Project\\
Tcl Version&\(9.0\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.1 $\\
Keywords&expand, \{*\}, vector, math\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

The ``expand'' operator --- \textbf{\{*\}} --- was adopted in Tcl 8.5 and is very useful for simplifying code involving lists. It is proposed to add this operator to the list of actions performed during processing of double-quote ("), joining the \textbf{\$}, \textbf{[}, and \textbf{\(\backslash\)}, and to modify the behavior of \textbf{\$} in variable substitution. The proposed behavior \textit{will} break existing substitution, but a trivial quoted-string substitution restores original behavior with the new approach. The proposed approach will enable eventual incorporation of vector-math to the Tcl engine without changing any of the existing syntax.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

It is desired to enhance the current math engine in TCL to handle vector math, without having to create new syntax or add cumbersome new function calls. Given the assignments \textbf{set ScalarA 1}, \textbf{set ScalarB 2}, \textbf{set ListA \{1 2 3\}}, and \textbf{set ListB \{4 5 6\}}, evaluating \textbf{\$ScalarA + \$ScalarB}, \textbf{\$ListA + \$ListB}, and \textbf{\$ListA + \$ScalarB} would all be trivially understandable, with the first behaving as currently implemented, the second returning a list containing the element-by-element sums of the two lists, and the third returning a list containing the elements of ListA incremented by the common ScalarB.

With the proposed enhancement (see below) the expression parser would receive a brace-delimited set of values wherever the lists appear, and a single value wherever the scalars appear.

With the proposed enhancement, and a vector-math core enhancement, given the assignments above, the following would behave identically:
\begingroup\small\begin{verbatim}
expr $ListA + {4 5 6}
expr $ListA + $ListB
expr {1 2 3} + $ListB
expr {1 2 3} + {4 5 6}
\end{verbatim}
\endgroup

With the proposed enhancement, incorporating vector math into the TCL core is vastly simplified, reducing to enhancing the current math handlers to perform different actions based on whether they received lists or scalars or both, and checking that the vectors have the appropriate element counts for the operation specified.

\section{Proposal}
\begin{enumerate}
\item{}
Add expansion -{}- \textbf{\{*\}} -{}- to set of actions performed during double-quote processing.
\begin{enumerate}
\item{}
Treat expand operator as a single character 'tri-graph'.
\setcounter{enumii}{1}
\item{}
Escape the operator -{}- \textbf{\(\backslash\)\{*\}} -{}- to turn it into ``regular text'' causing it to behave as it currently does during double-quote processing. Note that this is identical with the current behavior of escape, i.e., \textbf{\(\backslash\)\{} currently gives \textbf{\{}. With the new implementation it turns the expand operator into normal text inside of a quoted string.
\end{enumerate}
\setcounter{enumi}{1}
\item{}
Modify \textbf{\$} substitution so that \textit{lists} are enclosed in braces during substitution, i.e. after \textbf{set A \{1 2\}} execution of \textbf{puts ``\$A''} yields \textbf{\{1 2\}} instead of \textbf{1 2} as it currently does. Note that this behavior only manifests inside of quoted strings, as the assignment \textbf{set B \$A} still gives the same results as the original implementation, i.e. assigning a list to \textbf{B}.
\begin{enumerate}
\item{}
Prefix \textbf{\$} with expand \textbf{\{*\}} to restore current behavior, i.e., with the same assignment above, execution of \textbf{puts ``\{*\}\$A''} yields \textbf{1 2} instead of \textbf{\{*\}1 2} as it currently does. Note that this provides a fairly simple way to fix scripts broken by implementing this proposal. If exising scripts contain quoted lists, simply (a) replace all double-quoted occurrances of \textbf{\{*\}} with \textbf{\(\backslash\)\{*\}}, and (b) replace all double-quoted occurrances of \textbf{\$} with \textbf{\{*\}\$}.
\end{enumerate}
\end{enumerate}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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