\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#101: Export Tcltest Configuration}
\date{June 11, 2002}
\author{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 \#101}&\textbf{Export Tcltest Configuration}\\\hline
Author&

Don Porter \tipmail{dgp}{users.sf.net}
\\
Created&Tuesday, \(\text{11}^{\text{th}}\) June 2002\\
Type&Project\\
Tcl Version&\(8.4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.4 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Proposes public command \textit{tcltest::configure} to give programmatic control to processing configuration options of the tcltest package.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

During \textit{package require tcltest}, the internal command \textit{ProcessCmdLineArgs} is evaluated. This command uses the contents of \textit{\$::argv} as option-value pairs to configure several aspects of the tcltest package.

This approach leaves two aspect of package configuration hardwired, and outside of the control of users of \textit{tcltest}. First, the timing of configuration is fixed to package load time. Second, the source of configuration data is fixed to be the global variable \textit{argv}.

It would improve flexible use of tcltest to export a public command, \textit{tcltest::configure}, that will allow configuration of \textit{tcltest} by its users at any time and from any source.

\section{Proposal}

Add and export the command \textit{tcltest::configure}, with the syntax:
\begingroup\small\begin{verbatim}
	tcltest::configure ?option? ?value option value ...?
\end{verbatim}
\endgroup

With no options, \textit{configure} returns a list of the available configurable options. With a single \textit{option} argument, \textit{configure} returns the corresponding value of that option, or an error if no such option exists. In the most general form, \textit{configure} accepts an even number of arguments that are alternating options and values, and sets each option to each value.

The list of options and acceptable values are to be the same as those currently recognized by \textit{tcltest} as its command line options. The difference is that this configuration can now be performed programmatically, not only on the command line.

With complete programmatic access to \textit{tcltest} configuration made available, the special customization hooks \textit{processCmdLineArgsHook} and \textit{processCmdLineArgsAddFlagsHook} will be deprecated and removed from the documentation. Compatibility support for their existing use will be provided as described below.

\section{Compatibility}

Many existing test suites have been written depending on the auto-configuration from \textit{\$::argv} at package load time. Some of them may also be using the special customization hooks that allow the addition of more command line options. For compatibility, if the presence of any of these hooks is detected, \textit{tcltest} will fall back to performing its load-time configuration. Also, if any command that can be influenced by configured values is called prior to any call to \textit{configure}, then automatic configuration from \textit{::argv} will be performed.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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