# TIP 101: Export Tcltest Configuration
	Author:		Don Porter <dgp@users.sf.net>
	State:		Final
	Type:		Project
	Vote:		Done
	Created:	11-Jun-2002
	Post-History:	
	Tcl-Version:	8.4
-----

# Abstract

Proposes public command _tcltest::configure_ to give programmatic
control to processing configuration options of the tcltest package.

# Rationale

During _package require tcltest_, the internal command
_ProcessCmdLineArgs_ is evaluated.  This command uses the contents
of _$::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 _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 _argv_.

It would improve flexible use of tcltest to export a public command,
_tcltest::configure_, that will allow configuration of _tcltest_
by its users at any time and from any source.

# Proposal

Add and export the command _tcltest::configure_, with the syntax:

		tcltest::configure ?option? ?value option value ...?

With no options, _configure_ returns a list of the available
configurable options.  With a single _option_ argument,
_configure_ returns the corresponding value of that option, or an
error if no such option exists.  In the most general form,
_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 _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 _tcltest_ configuration made
available, the special customization hooks _processCmdLineArgsHook_
and _processCmdLineArgsAddFlagsHook_ will be deprecated and removed
from the documentation.  Compatibility support for their existing use
will be provided as described below.

# Compatibility

Many existing test suites have been written depending on the
auto-configuration from _$::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, _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
_configure_, then automatic configuration from _::argv_ will be
performed.

# Copyright

This document has been placed in the public domain.

