MagmaSoft Software Wiki/ TclConfig
  1. Terms and Concepts
  2. Overall process for collection of options
  3. Requirements
  4. Configuration file formats
  5. References

Is a Tcl package, maybe for inclusion in tcllib, with the purpose of generic configuration and preferences managment for programs.

Download the Tcl file here attachment:config.tcl

Or a zip-file which unpacks in its own directory and contains: sources, package index and documentation: attachment:config-0.1.zip

Terms and Concepts

option:
an option is some data that determines certain behavior of a program
configuration:
is an option that is determined at programm start and is not to be changed during the runtime of a programm.
preference:
is an option that is initialized during program start, may be altered during the runtime of a program and may be saved for future invocations of the program.
Scope:
system (wide setting):
is data for options, that is given for invocations under any of the systems users.
user (setting):
is data for options, that is specific for invocation of a specific user.
programm (default setting):
is data for options, that is predefined for invocation of the program on any system.

Sources:

configuration options can be set from:

  • files
  • environment variables
  • commandline options and arguments preferences can also be set from program input (user interaction)

Overall process for collection of options

The following sequence is invoked to process options:

  1. determine location of configuration files in the following order:
    • from program defaults
    • from the environment
    • from the commandline
  2. The following stages are processed to determine the value of a all other options:
  3. program default
  4. system
  5. user
  6. environment
  7. commandline if a value is obtained from a later stage, it overrides any data collected from an earlier stage:

Requirements

  • The package(s) shall provide an easy way to specify:
    • a name for the option
    • a (i18n-able) short description for the option
    • ditto for a long description
    • a program default value
  • Any number of option-sets can be defined and processed
  • Any number of configuration file sets may be specified für an option set
  • A configuration file may be searched for under different names and locations
  • support for different configuration file formats inside one program.

Configuration file formats

A number of "standard" formats for configuration files exist. Especially for programs written in Tcl a most natural option is also to source a file into a Tcl interpreter.

practically all file formats ignore empty lines or lines with whitespace.

Some quick and dirty descriptions of configuration file formats:

Tcl

# comment
set option value
set option {
          value
          value
          ...
}

procedure  value value ...

Value may be number, \"string\", or a { } surrounded, whitespace separated list of them. strings need not be quoted if they do not contain whitespace (and are not numbers).

$option evaluates to the value of an option, even within double quotes

[text] evaluates "text" as an

{text} evaluates to text, i.e. it fullfills the same purpose as double quotes for strings, but without evaluation of $ and [

\ at the and of a line appends the next line to the current line, even after a comment (#).

FIXME: single quotes, they are seldom used

Option names: Case matters, lower_case and ?MixedCase are common, white space is not allowed

Shell

# comment

OPTION=value

"double quotes" or 'single quotes' are used to enter values with whitespace.

Option names: Case mattes, UPPERCASE is common, white space is not allowed

ISC

# comment

context {
  option = value;   # comment
  option = value;
  ...
  subcontext {
     option = value;
     option = value;
     ...
  }
}

"double quotes" are use to enter values with whitespace

For option names several usages exist:

  • single token
  • several single tokens are allowed white space from line start to the first token and from the last token to the = character is stripped.
  • string between start of line and = is processed as follows:
    • 1) al white space is removed 2) the remaining string is converted to either lower, or upper case The value is obtained by stripping white space between the = character and the following text. Some parsers use "double quotes" to protect white space in the value text.

The trailing semicolon (;) may be either required, permited or illegal, depending on the specific variation of this format.

INI Files

; comment
# comment

[section]
  option = value
  ...

[section]
 option = value
 ...

The format is similar to the ISC style, however contexts start at a [section] header and end at the following [section] header or at the end of file. Context nesting is not allowed.

Sections may have predefined (or reserved) names, and or can be named to configure instances of objects managed by programms. The section name is then an identifier by which the object is referred to in configuration and processing. This name may or may not contain whitespace, or Mixed Case, depending on the individual parser.

; is commonly used by Windows programms, # by Unix programms, some parsers allow either.

XML

no commment

References