\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#393: Add -command Option to lsearch}
\date{April 25, 2011}
\author{Pawel Salawa}
\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 \#393}&\textbf{Add -command Option to lsearch}\\\hline
Author&

Pawel Salawa \tipmail{pawelsalawa}{gmail.com}
\\
Created&Monday, \(\text{25}^{\text{th}}\) April 2011\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.2 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This document describes new option for \textbf{lsearch} named \textbf{-command} that lets the developer define a custom comparision algorithm for searching for an element of a list.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The \textbf{-command} option would be very useful when someone wants to look for element on list, that contains objects (TclOO, Itcl, etc), or simply Tcl dicts. Specifying a command lets a developer to decide what data from objects in a list is important for the comparison.

This is effectively introducing the \textbf{-command} option from \textbf{lsort} to \textbf{lsearch}.

\section{Specification}

The option \textbf{-command} takes additional argument, which is a name of a command prefix that implements the comparison. The command prefix will have two extra arguments added during evaluation, being (1) the element of the list and (2) the pattern that is being sought. Thus, a suitable command might be defined like:
\begingroup\small\begin{verbatim}
    proc searchCommand {listElement pattern} {...}
\end{verbatim}
\endgroup

And used like:
\begingroup\small\begin{verbatim}
    lsearch -command searchCommand $list $pattern
\end{verbatim}
\endgroup

The command must return a boolean value, where true means that the element matches the pattern. Since the \textbf{-command} option specifies a comparision method, therefor it's treated the same way as \textbf{-exact}, \textbf{-glob}, \textbf{-regexp} and \textbf{-sorted} options are. It also causes some options (e.g., \textbf{-integer}, \textbf{-nocase}) to be ignored.

\section{Reference Implementation}

\url{http://sqlitestudio.pl/tcl/patches/tip-393-lsearch-command.patch}

Patch made against 8.6.0 beta.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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