TIP #101: Export Tcltest Configuration

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.