\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#246: Unify Pattern Matching}
\date{April 27, 2005}
\author{Reinhard Max}
\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 \#246}&\textbf{Unify Pattern Matching}\\\hline
Author&

Reinhard Max \tipmail{max}{tclers.tk}
\\
Created&Wednesday, \(\text{27}^{\text{th}}\) April 2005\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.5 $\\
Keywords&pattern, match, glob, exact, regexp, case sensitive, Tcl\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Many Tcl commands take arguments that are patterns to match against. Some of these commands allow options to specify whether the pattern should be treated as a literal, a glob pattern, or a regular expression, and whether or not matching should be case sensitive. This TIP proposes a unique set of options for all commands that accept pattern arguments.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

It is hard to memorize which of the commands that take a pattern argument allows to modify the matching mode, and in which way. With this TIP in place pattern matching will be orthogonal throughout Tcl, so the rules learned once can be applied to every command that uses pattern matching.

\section{Current situation}

The following commands currently take pattern arguments with varying combinations of switches to specify their behaviour:
\begin{itemize}
\item{}
\textbf{array get} \textit{arrayName} ?\textit{pattern}?
\item{}
\textbf{array names} \textit{arrayName} ?\textit{mode}? ?\textit{pattern}?
\item{}
\textbf{array values} \textit{arrayName} ?\textit{pattern}?
\item{}
\textbf{array unset} \textit{arrayName} ?\textit{pattern}?
\item{}
\textbf{dict filter} \textit{dictionaryValue} \textbf{key} \textit{globPattern}
\item{}
\textbf{dict filter} \textit{dictionaryValue} \textbf{value} \textit{globPattern}
\item{}
\textbf{dict keys} \textit{dictionaryValue} ?\textit{globPattern}?
\item{}
\textbf{dict values} \textit{dictionaryValue} ?\textit{globPattern}?
\item{}
\textbf{lsearch} ?\textit{options...}? \textit{list pattern}
\item{}
\textbf{parray} \textit{arrayName} ?\textit{pattern}?
\item{}
\textbf{string match} ?\textbf{-nocase}? \textit{pattern string}
\item{}
\textbf{switch} ?\textit{options...}? \textit{string pattern body}
\item{}
\textbf{namespace children} ?\textit{namespace}? ?\textit{pattern}?
\item{}
\textbf{namespace export} ?\textbf{-clear}? ?\textit{pattern pattern ...}?
\item{}
\textbf{namespace forget} ?\textit{pattern pattern ...}?
\item{}
\textbf{namespace import} ?\textbf{-force}? ?\textit{pattern pattern ...}?
\item{}
\textbf{info commands} ?\textit{pattern}?
\item{}
\textbf{info functions} ?\textit{pattern}?
\item{}
\textbf{info globals} ?\textit{pattern}?
\item{}
\textbf{info locals} ?\textit{pattern}?
\item{}
\textbf{info procs} ?\textit{pattern}?
\item{}
\textbf{info vars} ?\textit{pattern}?
\item{}
\textbf{registry keys} \textit{keyName} ?\textit{pattern}?
\item{}
\textbf{registry values} \textit{keyName} ?\textit{pattern}?
\end{itemize}

The following commands which also take pattern arguments are outside the scope of this TIP:
\begin{description}
\item[* Commands that match patterns against file names]
\textbf{auto\_import}, \textbf{auto\_mkindex}, \textbf{pkg\_mkIndex}, \textbf{tcltest}.
\item[* Commands that use regular expressions by design]
\textbf{regexp}, and \textbf{regsub}.
\end{description}
\begin{itemize}
\item{}
The \textbf{case} command, because it is deprecated
\end{itemize}

\section{Specification}

The commands listed above shall allow for two optional switches, one that specifies the matching mode, and can be \textbf{-exact}, \textbf{-glob}, or \textbf{-regexp}, and one that specifies case sensitivity, and can be \textbf{-case}, or \textbf{-nocase}. Their current behaviour shall become the default behaviour in absence of the respective switch. (Some commands may accept other switches as well.)

Also shall there be two new manual pages, one that describes glob matching similar to the \textit{re\_syntax} page, and one that describes the pattern matching options. These manuals shall be referenced by the manuals for the individual commands instead of repeating the detailed descriptions.

\section{Objections}

Some of the mentioned commands could become somewhat slower when they need to check for more options. This needs to be checked when implementing this TIP.

\section{Reference Implementation}

There is no reference implementation yet.

The idea is to have common code for option checking, and matching, that can be used by all mentioned commands. That way it would be easy to add new algorithms or options, and have them immediately available for all commands that can do pattern matching.

The C API for this will first be worked out as a private API when creating the reference implementation and later be published by a separate TIP, so that extensions can also make use of it.

\section{Notes}

There might be need for a similar unification in Tk as well, but that's outside the scope of this TIP, and should be easy to add once this TIP is implemented so that Tcl provides the needed infrastructure.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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