\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#57: Move TclX's [lassign] into the Tcl Core}
\date{August 30, 2001}
\author{Donal K. Fellows, Agnar Renolen, 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 \#57}&\textbf{Move TclX's [lassign] into the Tcl Core}\\\hline
Author&

Donal K. Fellows \tipmail{fellowsd}{cs.man.ac.uk}
\par
Agnar Renolen \tipmail{agnar.renolen}{emap.no}
\par
Don Porter \tipmail{dgp}{users.sf.net}
\\
Created&Thursday, \(\text{30}^{\text{th}}\) August 2001\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 2.4 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to move the \textit{lassign} command from the TclX extension into the Tcl core to make multiple assignment a much easier process for people.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

In many cases, a command needs to return more than one return value to the caller. For example, suppose that the statement:
\begingroup\small\begin{verbatim}
 set coords [LocateFeature $featureID]
\end{verbatim}
\endgroup

would set the variable ``coords'' to a list containing two elements ``x'' and ``y''. Assume that you need to set the ``x'' and ``y'' components directly, you can do this today using the following statement:
\begingroup\small\begin{verbatim}
 foreach {x y} [LocateFeature $featureID] {}
\end{verbatim}
\endgroup

Now, this is not what the \textit{foreach} command was designed for, and it is not obvious at first glance from the source code what the statement does. Although it is quite useful for the purpose described in this TIP, It would be more logical if the developer could write the following:
\begingroup\small\begin{verbatim}
 set {x y} [LocateFeature $featureID]
\end{verbatim}
\endgroup

or
\begingroup\small\begin{verbatim}
 mset {x y} [LocateFeature $featureID]
\end{verbatim}
\endgroup

However, there is already a command in TclX for doing this kind of operation: [lassign]. Given that many people already know TclX, importing the command from there makes a great deal of sense. It also has the nice feature of returning those list items that were not assigned, making it easy to strip a few words off the front of a list. That sort of operation is useful when performing tasks like command-line option parsing.

\section{Proposal}

Define a new command in Tcl called [lassign] with the following syntax (\textit{\$val} indicates an argument that the caller would supply):
\begingroup\small\begin{verbatim}
 lassign $listValue $varName ?$varName ...?
\end{verbatim}
\endgroup

The command interprets its first argument as a list value and all subsequent arguments as variable names. The first item in the list value (i.e. at index 0) will be assigned to the first variable named, the second item in the list value will be assigned to the second variable named (if present), etc. When there are more variables than list items, the remaining variables will be assigned the empty string. The result of the command is a sublist of the input list-value that contains only items that were not assigned to a variable; if all values were assigned, the result is an empty list.

This is exactly the specification of the behaviour of the correspondingly-named command in TclX.

\section{Notes}

It should be possible to efficiently compile [lassign] in many cases, which would make a tremendous difference in execution speed over not only the TclX version of [lassign], but also over the [foreach] ``idiom'', especially when assigning to variables that are not simple local variables (the case which [foreach] compilation is optimized for.) For this reason, I'm not committing to implementing [lassign] using the TclX code.

This TIP was substantially different in the past. Please view the CVS history for details.

\section{Copyright}

This document is placed in the public domain.

\section{Colophon}

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