\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#339: Case-Insensitive Package Names}
\date{November 14, 2008}
\author{Andreas Kupries}
\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 \#339}&\textbf{Case-Insensitive Package Names}\\\hline
Author&

Andreas Kupries \tipmail{andreask}{activestate.com}
\\
Created&Friday, \(\text{14}^{\text{th}}\) November 2008\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Rejected\\
Vote&Done\\
Version&\tipversion$Revision: 1.8 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This document proposes to change the package management facilities of the Tcl core to handle package names in a case-insensitive manner, switching back to case-sensitive operation if and only if explicitly requested by the user. The case of package names is preserved in the storage however.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The package management facilities of Tcl are an area where the user of packages is currently burdened with more ... than is convenient or easy. A big problem is that Tcl compares package names case-sensitively. This means that \textit{Expect} and \textit{expect} are two different things to Tcl. In the real world however having two packages using the same name but different capitalization is extremely rare.

Yet the user of Tcl package facilities has to remember whatever ecclectic capitalization the package creator has chosen.

Changing this, i.e. having Tcl's package management go to case-insensitive comparison, will lift this burden and make things easier, as it is not necessary anymore to get the capitalization right. Most people will likely simply start to write all package names lower-case after this change.

\section{Specification}

\subsection{Script Level}

The only command affected by the proposed change is \textbf{package}. More specifically, its sub-commands \textit{ifneeded}, \textit{present}, \textit{require}, and \textit{versions}.

In detail
\begin{itemize}
\item{}
\textbf{package require} \textit{name} ...

This sub-command is changed to accept an additional option \textit{-strict}.

If this option is present the sub-command performs an old-style, i.e. case-sensitive search for the package \textit{name}.

Otherwise the command is changed to disregard case during the search for \textit{name}. In that case it is possible that multiple packages are found which have the same name, just with different capitalizations. To resolve this conflict the command will load the package in the matching set which was added first to its memory database via \textbf{package ifneeded}.

If that resolves to the wrong package the user has to use \textit{-strict} and specify the exact name of the package required, capitalization and all. Given our rationale for the TIP this should be required seldomly.
\item{}
\textbf{package present} ?-exact? \textit{name} ?\textit{version}?

This sub-command is changed to accept an additional option \textit{-strict}.

If this option is present the sub-command performs an old-style, i.e. case-sensitive search for the package \textit{name}.

Otherwise the command is changed to disregard case during the search for \textit{name}. In that case it is possible that multiple packages are found which have the same name, just with different capitalizations. To resolve this conflict the command will return the version of the package in the matching set it found first among the loaded packages.

If that resolves to the wrong package the user has to use \textit{-strict} and specify the exact name of the package to look for, capitalization and all. Given our rationale for the TIP this should be required seldomly.
\item{}
\textbf{package versions} \textit{name}

This sub-command is changed to accept an additional option \textit{-strict}.

If this option is present the sub-command performs an old-style, i.e. case-sensitive search for the package \textit{name}.

Otherwise the command is changed to disregard case during the search for \textit{name}. In that case it is possible that multiple packages are found which have the same name, just with different capitalizations. To resolve this conflict the command will return the version of the package in the matching set which was added first to its memory database via \textbf{package ifneeded}.

If that resolves to the wrong package the user has to use \textit{-strict} and specify the exact name of the package to query, capitalization and all. Given our rationale for the TIP this should be required seldomly.
\item{}
\textbf{package forget} \textit{name} ...

This sub-command is changed to accept an additional option \textit{-strict}.

If this option is present the sub-command performs an old-style, i.e. case-sensitive search for the package \textit{name} to forget.

Otherwise the command is changed to disregard case during the search for \textit{name}. In that case it is possible that multiple packages are found which have the same name, just with different capitalizations. Instead of resolving the conflict by forgetting only the first package found among the loaded this command will forget \textbf{all} of the packages matching the name.

If that does more than intended the user has to use \textit{-strict} and specify the exact name(s) of the package to forget, capitalization and all. Given our rationale for the TIP this should be required seldomly.
\item{}
\textbf{package provide} \textit{name} \textit{version}

This form of the command is left unchanged.
\item{}
\textbf{package provide} \textit{name}

This form of the command is like \textbf{package present}, except for the different handling of a package not in memory. It is therefore changed in the same manner, i.e:

This form of the sub-command is changed to accept an additional option \textit{-strict}.

If this option is present this form of the sub-command performs an old-style, i.e. case-sensitive search for the package \textit{name} before returning its version, or the empty string if nothing was found.

Otherwise this form of the sub-command is changed to disregard case during the search for \textit{name}. In that case it is possible that multiple packages are found which have the same name, just with different capitalizations. To resolve this conflict the command will return the version of the package in the matching set it found first among the loaded packages.

If that resolves to the wrong package the user has to use \textit{-strict} and specify the exact name of the package to look for, capitalization and all. Given our rationale for the TIP this should be required seldomly.
\item{}
\textbf{package ifneeded} \textit{name} \textit{version} \textit{script}

This form of the command is left unchanged. It keeps storing the package name as given, preserving capitalization, and \textit{package provide} searches case-sensitively. This means that the name used by \textbf{provide} has to match the name used by the \textbf{ifneeded}, just like the version numbers have to match. While we are working on easing the load on the user of a package with regard to letter case we do assume that the developer of a package does know how it is spelled, capitalization and all, therefore a strict, case-sensitive search is best to detect such avoidable mismatches.
\item{}
\textbf{package ifneeded} \textit{name} \textit{version}

This form of the command is similar to \textbf{package present} or \textbf{package provide}. It is therefore changed in the same manner, i.e:

This form of the sub-command is changed to accept an additional option \textit{-strict}.

If this option is present this form of the sub-command performs an old-style, i.e. case-sensitive search for the package \textit{name} before returning the script, or the empty string if nothing was found.

Otherwise this form of the sub-command is changed to disregard case during the search for \textit{name}. In that case it is possible that multiple packages are found which have the same name, just with different capitalizations, and the same version. To resolve this conflict the command will return the script of the package in the matching set it found first among the loaded packages.

If that resolves to the wrong package the user has to use \textit{-strict} and specify the exact name of the package to look for, capitalization and all. Given our rationale for the TIP this should be required seldomly.
\end{itemize}

\subsection{C API}

At the C-level the only functions to consider are
\begin{itemize}
\item{}
Tcl\_PkgPresent
\item{}
Tcl\_PkgPresentEx
\item{}
Tcl\_PkgRequire
\item{}
Tcl\_PkgRequireEx
\item{}
Tcl\_PkgRequireProc
\end{itemize}

The first four of these currently have an integer (boolean) argument \textit{exact}. This argument is changed to an integer (bitset) \textit{flags}, with the original exact value residing in bit 0. The strictness of the package name comparison is encoded in bit 1. For easy access to the flags we define
\begingroup\small\begin{verbatim}
 #define TCL_PKG_EXACT  1  /* Exact version required */
 #define TCL_PKG_STRICT 2  /* Use strict (case-sensitive) package name
                            * comparison */
\end{verbatim}
\endgroup

This change relies on the assumption that all (most) existing users of these functions use the constants 0 and 1 for \textit{exact}, making them fully backward compatible.

The last function, \textit{Tcl\_PkgRequireProc}, has no arguments we can modify in this manner. Its behaviour is changed to perform case-insensitive searches, as specified above for the associated subcommands of \textbf{package}, and a new function is added for access to the old behaviour, i.e. case-sensitive searches. This new function is
\begin{itemize}
\item{}
Tcl\_PkgRequireProcEx
\end{itemize}

It has the same signature as its pre-TIP counterpart, except that a \textit{flags} argument is added after the clientData. This argument recognizes \textit{TCL\_PKG\_STRICT} as defined above and uses it to switch between case-insensitive and strict search. The old \textit{Tcl\_PkgRequireProc} is reimplemented in terms of \textit{Tcl\_PkgRequireProcEx}.

\subsection{Unknown handlers}

The contract between the package management facilities in the Tcl core and the handler commands registered with \textit{package unknown} is amended. The handler has to perform case-insensitive search for the package whose name it is invoked with.

\subsection{Discussions}

The contract for the package unknown handler is amended because not doing so would force the package management facilities in the Tcl core to search for a package by iterating over all possible combinations of upper/lower case in the package name. For a name containing N alphabetic characters (i.e. not counting ':'s, and digits) this means to loop 2**N times. This exponentional explosion and consequent running time is not acceptable (The longest name for a package currently found in ActiveState's public TEApot repository is 25 alpabetic characters, forcing over 30 million searches before the core can give up).

Further, of the two known standard package unknown handlers the handler for regular packages need not be modified at all as it always register every possible package it finds. Only the unknown handler for Tcl Modules has to be modified to perform case insensitive filesystem searches, and only for Unix. On Windows the builtin \textbf{glob} command already perform such.

\section{Reference Implementation}

An implementation patch is available at SourceForge [\url{http://sourceforge.net/support/tracker.php?aid=2316115}].

\section{Copyright}

This document has been placed in the public domain.

Please note that any correspondence to the author concerning this TIP is considered in the public domain unless otherwise specifically requested by the individual(s) authoring said correspondence. This is to allow information about the TIP to be placed in a public forum for discussion.

\section{Colophon}

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