config(n) 0.1 "options managment"
config - onfiguration and preferences managment
TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
OVERVIEW
COMMANDS
VARIABLES
Defining Optionsets
Get the options set
Terms and Concepts
SCOPE
SOURCES
OPTIONSETs
EXAMPLES
SEE ALSO
KEYWORDS
COPYRIGHT
package require Tcl 8.2
package require config ?0.1?
The config package provides flexible options managment.
A programms configuration or user preferences can be stored in
optionsets, which can be set from configuration files, the
environment or from the commandline.
options are elements of optionsets, their value can be set from
several sources.
An optionset holds information about sources, default
values, descriptions, shortcuts, configuration file locations of a
range of options
In the end, an optionset is a Tcl array which can be
manipulated as needed by the program.
Configuration files can be specified explicitely, else an internal
heuristic can be used to determine posible locations and names of
configuration files. Any number of configuration files can be
specified for an optionset.
The format of each configuration file can be defined individually.
Actually (safe) Tcl is the default and actually the only option.
Commandline parsing is also configurable, beeing the cmdline
package the default and actually only option.
Note that the the cmdline package is not required, if
commandline parseing is not used.
Although config is designed with extensibility in mind, its
main purpose is to simplify option handling. The default way to
invoke option processing is just to call ::config::get_config.
The following sequence is then invoked to process options:
-
determine location of configuration files in the following order:
- from program defaults
- from the environment
- from the commandline
-
The following stages are processed to determine the value of a all
other options:
- program default
- system
- user
- environment
- commandline
if a value is obtained from a later stage, it overrides any data
collected from an earlier stage:
- ::config::optionsets
- list of defined optionsets
- ::config::version
- version of the config package
- ::config::add_option optionset name short_description ?options?
-
Define an optionset. posible ?options? are:
- -secret
- don't show the option to the user
- -optional
- this option may have an argument
- -default defaultvalue
- set the default value
- -shortcut shortcut
-
the first letter of shortcut is used as sinlge letter option
name for the option
- -env envname
-
envname is the name of the environment variable used to set
the option
- ::config::add_file optionset ?parser? ?-tag tag? ?filename ..?
-
Register a configuration file to be parsed with parser. Eventuall add
a tag to distinguish configuration file setup. The list of
files: filename .. will be searched in order, the first file matched is
used.
If the list of files is empty, search in several places with
predefined names derived from argv0 and tag. If tag
is not specified set it to $argv0. If parser is not
specified set it to tcl
- ::config::get_config optionset ?parser? ?usage? ?envname? ?shortcut?
-
parse options from environment, config files and the commandline of
a program.
- string usage
- modfiy the usage message of cmdline
- string shortcut
- modify the shortcut for the configfile option, default 'c'
- token envname
- modify the environment variable used to look up the
configfile, default CONFIG
- token parser
- modify the parser used to parse the configfile, default tcl
- ::config::env_getoptions optionset
-
set options from environment variables
- ::config::parse_file optionset ?tag?
-
(eventually) set options by parsing the configuration file specified
by tag, or the default configuration file if tag is not specified
- ::config::tcl_parse_file optionset filename
-
parse filename in a safe interpreter and set optioneset with
variables defined there whose name is in $optionset(options).
- ::config::cmdline_getoptions optionset argv ?usage?
-
parse the argumentstring in the variable named argv into the optionset
with the cmdline parser.
- ::config::optionset optionset ?processor?
-
- token optionset
- name of an array holding optionset definition
- token processor
- name of the processor to use, by default
cmdline
The optionset is converted into a form usable by the processor and
then return'ed
- 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.
- 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.
configuration options can be set from:
- files
- environment variables
- commandline options and arguments
preferences can also be set from program input (user interaction)
In the following * means not supported by cmdline package
An optionset is an array, describing options. The optionset is first
defined, and can then be manipulated by searching the environment, the
commandline, several configuration or preferences files and user input
during the runtime of the program.
In the following list of reserved indexes 'option' containes the name
of an option
- ($option)
-
holds the value of the option after option processing
- (options)
- list of option names, auto generated by add_option
- (shortcuts)
- list of the respective shortcuts
No check is made to garantee unique shortcuts
- ($option,shortcut) token
-
- string
- the letter to use is the first letter of string
- true or unset
- use first letter of longname
- false
- do not define a short option *
- ($shortcut,option) option
-
this reverse index of shortcuts to optionname is created during
parsing of the options, put deleted afterwards
- ($option,secret) flag
-
- true
- do not show the option to the user
- false or unset
- show in usage messages, etc.
when using cmdline this is made a boolean option
- ($option,default) defaultvalue
-
- not set
- option is a boolean
- else
- value to give the option if not defined elsewhere
- ($options,optional) flag
-
only taken into account if defaultvalue exists
- true
- the option may be specified without an argument
in which case it is set to the defaultvalue *
- not existent or false
- an argument to the option must be given
- ($option,description) long description
- *
- ($option,short) (less then) one line description
-
this index is required
- ($option,env) name
-
name of the asociated environment variable
- (tags)
- list of tags, each describing a configuration fileset
- ($tag,files)
- list of possible configuration files
- ($tag,parser)
- parser used for this configuration file
- ($tag,filename)
- first filename out of ($tag,files) which exists
If no tag is specified:
- (files)
- list of files
- (filename)
- first filename out of (files)
- (parser)
- parser to use for (filename)
| |
package require config
::config::add_options config <name> <description> \
-default <value> -env <NAME>
..
::config::get_config config
|
This will set $config(<name>) to one of:
-
<value>
-
the value of the variable <name> set in a tcl config file that
can be placed at various system wide or user specific places
-
the value of the environment variable <NAME>
-
the value of the -<n> switch on the commandline, where <n> is the
first letter of <name>
Later items in the list precede earlier items.
argument processing, cmdline processing, configuration files
Copyright © 2006 Georg Lehner <jorge@magma.com.ni