\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#251: Enhance the 'list' Command}
\date{June 28, 2005}
\author{Brian Schmidt, S\'{e}rgio Loureiro}
\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 \#251}&\textbf{Enhance the 'list' Command}\\\hline
Author&

Brian Schmidt \tipmail{contact}{schmidtsrus.net}
\par
S\'{e}rgio Loureiro \tipmail{srgloureiro}{gmail.com}
\\
Created&Tuesday, \(\text{28}^{\text{th}}\) June 2005\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Rejected\\
Vote&Done\\
Version&\tipversion$Revision: 1.14 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes enhancing the existing \textbf{list} command to serve as a top-level command ensemble for all the related list commands that have proliferated over time, as well as making it easier to add future new list-based commands.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

There are numerous top-level commands for lists already. This command would centralize them, making it easier for new developers of Tcl scripts to learn all the related list commands, to simplify and reduce the number of top-level commands to learn, etc. The enhanced \textbf{list} would be consistent with the new top-level commands \textbf{chan} \cite{tip208} and \textbf{dict} \cite{tip111}, as well as the existing \textbf{string} and \textbf{file} commands.

\section{Specification}

A new command \textbf{list} will be added with the following syntax:
\begin{description}
\item[list append]
 equivalent to \textbf{lappend}
\item[list create]
 equivalent to \textbf{list}
\item[list index]
 equivalent to \textbf{lindex}
\item[list insert]
 equivalent to \textbf{linsert}
\item[list join]
 equivalent to \textbf{join}
\item[list length]
 equivalent to \textbf{llength}
\item[list range]
 equivalent to \textbf{lrange}
\item[list repeat]
 equivalent to \textbf{lrepeat} (see \cite{tip136})
\item[list replace]
 equivalent to \textbf{lreplace}
\item[list search]
 equivalent to \textbf{lsearch}
\item[list set]
 equivalent to \textbf{lset}
\item[list sort]
 equivalent to \textbf{lsort}
\end{description}

Each represents the existing command that is commented. The arguments to each would remain what the current command takes.

Note that \textbf{split} is not included as it operates on a string and returns a list, and \textbf{concat} is not included because it can operate on both normal strings and lists.

The old commands could then potentially be deprecated:
\begin{itemize}
\item{}
\textbf{join}
\item{}
\textbf{lappend}
\item{}
\textbf{lindex}
\item{}
\textbf{linsert}
\item{}
\textbf{llength}
\item{}
\textbf{lrange}
\item{}
\textbf{lrepeat}
\item{}
\textbf{lreplace}
\item{}
\textbf{lsearch}
\item{}
\textbf{lset}
\item{}
\textbf{lsort}
\end{itemize}

\section{Incompatabilities}

Incompatability with the existing list command could potentially be solved by allowing the list command \textit{without} one of the defined options to be shorthand for the new \textbf{list create} command option. If the first argument to the new list command is not one of the new known options then \textbf{list create} is assumed by default.

For example,
\begingroup\small\begin{verbatim}
list {my list}
\end{verbatim}
\endgroup

would be equivalent to:
\begingroup\small\begin{verbatim}
list set {my list} {}
\end{verbatim}
\endgroup

It appears the only existing scripts that would break would be those that actually utilize the \textbf{list} command, has at least 2 arguments, and have as their first argument one of the new list command's ensemble options. This would likely result in a small minority of scripts being impacted. Only Tcl code with lists defined \textit{exactly} as follows would break:
\begingroup\small\begin{verbatim}
list append ?arg...
list create ?arg...
list index ?arg...
list insert ?arg...
list join ?arg... 
list length ?arg...
list range ?arg...
list repeat ?arg...
list replace ?arg...
list search ?arg...
list set ?arg...
list sort ?arg...
\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 \#3}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#111]{tip111}
Donal K. Fellows,
David S. Cargo,
\emph{Dictionary Values and Manipulators},
on-line at \url{http://purl.org/tcl/tip/111.html}
\bibitem[TIP \#136]{tip136}
Simon Geard,
\emph{Large List Initialisation},
on-line at \url{http://purl.org/tcl/tip/136.html}
\bibitem[TIP \#208]{tip208}
Jeff Hobbs,
\emph{Add a 'chan' Command},
on-line at \url{http://purl.org/tcl/tip/208.html}
\end{thebibliography}
\end{document}
