Robotics Service Bus

h1. Configuration

The configuration mechanism is based on the following principles:
* We cannot (and do not want) to handle configuration of individual participants. The configuration mechanism is intended to provide process-wide defaults. Participants that require individual configurations have to be configured programmatically.
* The configuration mechanism works identically across implementation languages
* Configuration options are obtained from multiple configuration sources:
** Configuration files
** Environment variables
** _Commandline options (planned)_
* Configuration options are organized in a tree of name-value pairs

h2. Syntax and Semantics

Option names consist of multiple components which are specified in configuration-source-dependent syntax. For example, in configuration files section names like @[transport.spread]@ are concatenated with names of contained options like @port@ to obtain @transport.spread.port@. For environment variables, the name @RSB_TRANSPORT_SPREAD_PORT@ maps to @transport.spread.port@.

Currently the following option tree is defined (uppercase option name components are placeholders, LANGUAGE refers to the implementation language):
<pre>
+ qualityofservice
+-- reliability { UNRELIABLE, RELIABLE }
+-- ordering { UNORDERED, ORDERED }
+ errorhandling
+-- onhandlererror { LOG, PRINT, EXIT }
+ plugins
+-- LANGUAGE
+---- path list of strings
+---- load list of strings
+ transport
+-- NAME
+---- enabled bool
+---- TRANSPORT_SPECIFIC_OPTION ?
+---- converter
+------ LANGUAGE
+-------- WIRE-SCHEMA string
+-- spread
+---- host string
+---- port uint
+---- maxfragmentsize uint
+---- tcpnodelay boolean
+-- inprocess
</pre>

h2. Processing Order

Configuration sources are processed in the following order such that options from sources which are processed later take precedence over options from sources which are processed earlier:
# Config file @${HOME}/.config/rsb.conf@
# Config file @$(pwd)/rsb.conf@
# Environment variables

h3. Example and test case

Consider the following situation:
* Contents of @${HOME}/.config/rsb.conf@:
<pre>
[transport.spread]
host = azurit
port = 5301
</pre>
* Contents of @(pwd)/rsb.conf@
<pre>
[transport.spread]
host = localhost
</pre>
* Environment Variables
@RSB_TRANSPORT_SPREAD_PORT='4444'@

This would result in the following effective option values:
* @transport.spread.host = localhost@
* @transport.spread.port = 4444@

h2. Sources

The following sections briefly explains the currently defined configuration sources.

h3. Configuration Files

Configuration files use the following syntax, which is similar to "INI-files":http://en.wikipedia.org/wiki/INI_file or "desktop-files":http://standards.freedesktop.org/desktop-entry-spec/latest/:
* Comments are initiated by the @#@ character and extend to the end of the current line
* After removing comments, all lines have to be of one of the following forms:
** empty
** @[NAME]@ where @NAME@ consists of alphanumeric characters and colons
** @NAME = VALUE@ where @NAME@ consists of alphanumeric characters

Here is an example:
<pre>
[qualityofservice]
reliability = UNRELIABLE
ordering = UNORDERED

[errorhandling]
onhandlererror = LOG

[transport.spread]
host = localhost
port = 4803
enabled = 1 # this is the default

[spread.converter.cpp]
image = IplImage # wire-schema = data-type

[transport.inprocess]
foo = barbar
factor = 1.5
enabled = 1

[plugins.cpp]
path = /vol/vampire/lib:/vol/cor/lib
load = rsbspread:rsbvampire # no filetype suffix
</pre>

h3. Environment Variables

Environment variables are processed according to the following rules:
# Variables whose names start with @RSB_@ are processed
# The @RSB_@ prefix is stripped form the name
# To obtain the name of the corresponding option, the remainder of the name is converted to lower case and split at @_@ characters

Examples:
* @RSB_PLUGINS_CPP_LOAD <-> plugins.cpp.load@
* @RSB_TRANSPORT_SPREAD_PORT <-> transport.spread.port@

h3. Commandline Options

_This section is a proposal._

Commandline options are processed according to the following rules:
# Language-specific name components (such as @plugins.cpp.load@) are dropped
# Components are joined with/strings are split at @-@ characters

Examples:
* @--plugins-load <-> plugins.cpp.load@
* @--transport-spread-port <-> transport.spread.port@