Configuration

All software components set the values of their configurable parameters using a global configuration instance. This global configuration keeps a set of configuration resources.

Resources

A configuration resource is a key/value pair. The key part of the resource has the form <selector1>.<selector2>. ... .<selectorN>. Any of the selectors may be the wildcard *. The * can replace also a sequence of selectors.

Selections are created according to the object hierarchy of the software system (e.g. speech-recognizer.acoustic-model.hmm is the selection corresponding to the object describing the HMM structure used by the recognizer). The first selector is always the name of the executable.

The request for the value of a parameter <name> w.r.t. to a given selection <selector1>.<selector2>. ... .<selectorM> is resolved as follows:

The selection <selector1>.<selector2>. ... .<selectorM>.<name> is matched against the key part of each resource.
If matching resources exist, the value of the best matching resource is returned.

Example

Resources:
*.hmm.number-of-states = 3
*.hmm.*.exit = 43.34
*.phoneme-look-ahead.*.hmm.number-of-states = 1

Requests:
speech-recognizer.acoustic-model.hmm.number-of-states -> 3
speech-recognizer.acoustic-model.hmm.silence.exit -> 43.34
speech-recognizer.phoneme-look-ahead.acoustic-model.hmm.number-of-states -> 1
speech-recognizer.phoneme-look-ahead.acoustic-model.hmm.silence.exit -> 43.34

Configuration Input

Configuration resources are set up from:

configuration files
command line arguments of the form --selectors.name=value, e.g. --*.output-channel.file=myfile.log
environment variables

References

The value of a resource may contain a reference of the form $(selector). When this resource is looked up (i.e. matched against a parameter specification), the reference is textually replaced by its resolved value. The resolved value is determined by appending the resources selector to the matched parameter specification and searcing for a matching resource. This implies that resources are context dependent. If this fails the matched parameter specification is truncated until either a match is found or the resolution fails.

Example

Given the resources:

*.foo.abc = cat
*.foo.xyz = dog
foo.*.bar = /tmp/$(foo).txt

then foo.abc.bar is resolved to /tmp/cat.txt and foo.xyz.bar is resolved to /tmp/dog.txt

Configuration Files

Configuration files are plain text files. The recommended file name extension is .config. Everything after the comment character # is ignored.

In configuration files you can group resources as follows:

[<selector-1>.<selector-2>. … .<selector-N>] name-1 = value-1 name-2 = value-2

Configuration files can include other configuration files by a include directive:

include filename.config

The referenced file is included at exactly this position. If the included file does not contain a group selector, the preceding group selector is used.

Example

[*.output-channel]
file   = logfile.log
append = true
# equivalent to
# *.output-channel.file = logfile.log
# *.output-channel.append = true

[*.acoustic-model.hmm]
include shared-hmm-settings.config   # include some shared parameters
silence.loop = 0.0                   # set specific value

Arithmetic Expressions

Arithmetic Expressions of the form $[expression,format] are resolved to their value.

expression may be any valid arithmetic expression, including standard math functions. format specifies if the result should contain decimals, <float> or <int>

The expression may contain references to resources.

Example

lm-scale            = 13.34
reciprocal-lm-scale = $[1 / $(lm-scale)]

# a more theoretical example:
cmp-2.value = 45.89
val         = 3
*.foo = $[ $(cmp-$[ $(val) - 1, int]).value * log(6.23) ]

Pitfalls

Cmdline

Note that there is a difference between specifying variables by cmdline

<tool> tool.config --MY_VAR1=<value> --*.MY_VAR2=<value>

The first variable can only be used as a value $(MY_VAR1) within the config files whereas the second variable $(MY_VAR2) could also be used within flow files, as it is specified as a node. Note also that if one would have already specified MY_VAR1 in tool.config the config parameter would not have been overwritten by the cmdline value --MY_VAR1, whereas MY_VAR2 in tool.config whould have been overwritten by --*.MY_VAR2

Helpful for debugging such matching problems can be:

--log-configuration=yes --log-resolved-resources=yes

Config Filenames

You cannot use the char . to separate a config filename, e.g. my.funky.settings.config as it is used as a special resource_separation_char in the configuartion mechanism. Otherwise you might wonder about the following exit error message:

PROGRAM DEFECTIVE: precondition add_selection.find(resource_separation_char) == std::string::npos violated in Core::Configuration::Configuration(const Core::Configuration&, const std::string&) file Configuration.cc

Code

Internally the configuration is represented by Core::Configuration objects and usually only a single one is created (as part of the Application class).

class Configuration

Central configuration class. Configuration

Subclassed by PyConfiguration

Public Functions

Configuration(const Configuration &c, const std::string &selection)

Configuration(const Configuration &c)

Configuration()

~Configuration()

Configuration &operator=(const Configuration &c)

void enableLogging(): Enable logging facility.

void writeSources(XmlWriter&) const: Report where configuration ressources came from.

void writeResolvedResources(XmlWriter&) const: Report all configuration resolved resources in the database.

void writeResources(XmlWriter&) const: Report all configuration resources in the database.

std::vector<std::string> writeResourcesToCommandlineArgs() const: Return all configuration resources in command-line format

void writeUsage(XmlWriter&) const: Report how configuration ressources where used by which parameters.

inline const std::string &getSelection() const

inline const std::string &getName() const

void setSelection(const std::string &selection)

void set(const std::string &name, const std::string &value = "true", const SourceDescriptor *source = 0)

Add a resource. If a resource with the same name already exists, its value is replaced.

Parameters:

name – of the resource to be added
value – of the resource

bool tryToSet(const std::string &name, const std::string &value = "true", const SourceDescriptor *source = 0)

Try to add a resource. This is a safe veriosn of set(). If the resource name is not well-formed, an error message is printed and no resource is set.

See also

set()

Returns:: true is name is well-formed.

bool setFromEnvironment(const std::string &variable)

bool setFromFile(const std::string &filename)

std::vector<std::string> setFromCommandline(const std::vector<std::string> &arguments)

bool get(const std::string &parameter, std::string &value) const

Query the configuration for a parameter.

It is strongly discouraged to use get() directly use one of the Parameter classes instead.

See also

Parameter

Parameters:

parameter – is the parameter identification string
value – The value of the queried parameter is stored in value. Remains unchanged if the parameter is not specified in the configuration.

Returns:

true if the parameter was configured

std::string resolve(const std::string &value) const

Substitutes all parameter references, arithmetic expressions and cache manager commands in a string. Cache manager commands are only resolved if the corresponding module is enabled

See also

Configuration::resolveReferences

See also

Configuration::resolveCacheManagerCommands

Public Static Functions

static bool isWellFormedResourceName(const std::string&): Test if argument is a well-formed resource name. A string is a well-formed resource name iff it matches the regular grammar: S -> ‘*’ | [a-zA-Z0-1]+ | S ‘.’ S

static bool isWellFormedParameterName(const std::string&): Test if argument is a well-formed parameter name. A string is a well-formed resource name iff it matches the regular grammar: S -> [a-zA-Z0-1]+ | S ‘.’ S

static std::string prepareResourceName(const std::string &selection, const std::string &name)

static std::string resolveArithmeticExpressions(const std::string &value)

Substitute arithmetic expressions in a string

All occurances of $[expression] are substituted. expression can be any valid arithmetic expression, including standard math funcions. To cast the result of the expression to a specific type, use $[expression,format] Format may be int or float, default is float. Parameter references are not resolved! So use resolveReferences before.

Parameters:: value – is a string which may contain arithmetic expressions
Returns:: @vc value with all arith. expressions subsituted

Public Static Attributes

static const char resource_wildcard_char = '*'

static const char *resource_wildcard_string = "*"

static const char resource_separation_char = '.'

static const char *resource_separation_string = "."

class Resource

Item of configuration.

A resource is a piece of configuration specified by the user. It consists of a name and an associated value. The name may contain wildcards. The value may contain references (e.g. ), which are subject to substitution.

Public Functions

inline Resource(const std::string &_name, const std::string &_value, const SourceDescriptor *_source)

inline const std::string &getName() const

inline const std::string &getValue() const

inline bool operator<(const Resource &r) const

inline bool operator==(const Resource &r) const

inline void write(std::ostream &os) const

s32 match(const std::vector<std::string> &components) const

Determine if the resource matches a configurtion path.

Finds best match using dynamic programming: Runtime is at most |Component| * |Resource|

Parameters:: components – the components of the configuration path
Returns:: the number of path components matched by the resource, or -1 of the resource does not match.

inline void registerUsage(const std::string &n, const AbstractParameter *p, const std::string &v) const

void writeUsage(XmlWriter&) const

class ResourceDataBase : public Core::ReferenceCounted

Central storage place for all resources.

Public Functions

void set(const std::string &name, const std::string &value = "true", const SourceDescriptor *source = 0)

Add a resource. If a resource with the same name already exists, its value is replaced.

Parameters:

name – of the resource to be added
value – of the resource

const Resource *find(const std::string &parameter) const

Find the resource to be used for a given parameter.

Parameters:: parameter – the parameter specification string
Returns:: the most specific resource matching parameter

inline const std::set<Resource> &getResources() const

inline const Resource *noResource() const

inline SourceDescriptor *addSource(const std::string &type, const std::string &data)

ResourceDataBase()

~ResourceDataBase()

inline void enableLogging()

void writeSources(XmlWriter&) const

void writeUsage(XmlWriter&) const

void write(std::ostream&) const

class SourceDescriptor

Describes where a resource comes from.

Public Functions

inline void write(XmlWriter &os) const

Public Members

std::string type

std::string data