Interlook.Configuration 1.0.0

Interlook.Configuration

Library for obtaining configuration data from different sources (currently INI-files and command line options) utilizing Microsoft.Extensions.Configuration.

May be combined with other existing extensions like Microsoft.Extensions.Configuration.NewtonsoftJson.

Overview

In the Microsoft.Extensions.Configuration world, actual configuration is generally stored as key/value-pairs. The key names are case insensitive and may pre prefixed with section names. Thus a key, say server_name may occur multiple times, eg. like this:

• database:server_name
• nuget_repo:server_name

The colon is used as key delimiter. Multiple prefixes are possible (like nuget_repo:primary:connection:server_name) but providers of this library don't make directly use of it, although you may define likewise.

Supported sources

INI-Files

The classic Ini-File format from old DOS times. There is a standard implementation in Microsoft.Extensions.Configuration.Ini, which doesn't completely deliver what I wanted.

Values

Values are assigned to keys like this:

keyname=value that includes everything behind the equals sign
another="double quotes are possible and omitted in the value, if they are the first and last characters of the line"
imagine='same goes for single quotes'

Please note that multi-line values are not supported by the Ini-file format.

Comments

Comments are marked with # or ; at the beginning of the line

# Everything here is not parsed and just a comment
warning=Comments behind values are not possible, so     #this still belongs to the value

  # but you may indent comments, if you insist
colon="possible, and..."
;colon=seems to be used mostly to comment things out

Sections

Keys can be grouped into sections (as described above) like this:

# everything before the first section is not prefixed
global_key=has no prefix

[database]
# the following key name will be database:server_name
server_name=127.0.0.1
user_name=caligula

[nuget]
# you get the idea
server_name=stuff.our-intranet.universe

#NOTE: sections cannot be nested, but again
#      if you insist, you could enforce it
[nuget:primary:connection]
server_name=secure_repo.intranet.universe
# but this is against standard 
# and not guaranteed to work always, everywhere and forever

That's everything (actually a bit more) that is supported by Ini-files.

Command line arguments

Again, there is a standard implementation in Microsoft.Extensions.Configuration.CommandLine, but I wanted slightly more control and the opportunity to group short-switches, as known from the unix format.

Unlike with Ini-Files, you have to define the key-names (including possible [multi-]prefixes) in advance and map them to command line arguments.

Command line arguments can be divided into switches, valued options and values.

Switches

A switch is a single argument without a further value, mostly just enabling something (like a boolean value).

myTool --quiet
myTool -q

The above may be defined als aliases. For switches you define both key name and value in advance. This key/value pair is added to configuration, as soon as the corresponding switch is provided. Switches are always optional, since an mandatory switch would make no sense; what's the point of an argument, that always is to be specified for a program to work.

Valued options

There are arguments, which require an additional value to be provided. Consider this:

myTool --user MartinGalway
myTool -v 5

These arguments may be optional or required, just as you define it.

Here, you only define the key name in advance, since the actual value is obtained from command line. Omitting the value will cause an error.

Values

Finally, the program may require certain values as input. We all know this:

copy -f source_file destination

Their order is fixed, the first argument, that is no switch and no value-option is interpreted as first value. For this you define a list of configuration key names, which determines the number and order of the required values.

Of course, all of the three types above can be mixed in any way.

myTool -q first_value --user Armakuni -nib second_value -f
myTool -nqib --user Armakuni -f first_value second_value
myTool --user Armakuni -fnqib first_value second_value

Short names

Short named options (switch or valued options) consist of only one single character and must be preceded by a single dash. They may be grouped and have no strict order, so the following syntaxes are (almost) equivalent:

myTool -q -i -n
myTool -qin
myTool -i -nq

An argument requiring an additional value can, of course, only be in a group, if it's the last character, like this:

myTool -q -i -n -v 5
myTool -qinv 5

Long names

Long names for arguments have to be prefixed with a double dash.

myTool --quiet
myTool --user MilkaCow

Order of options

The order of options (not required values) is generally not important. The only thing to consider is, that arguments are parsed in sequence, so if you define conflicting arguments, the last argument may be decisive. Consider:

myTool --verbose --quiet
myTool --quiet --verbose

Here, if quiet and verbose define opposing values for the same key, the first version will go with the quiet value while the latter will result the verbose one. The same applies for valued options:

myTool --user MelittaMan -u GerdFroebe
myTool -u GerdFroebe --user MelittaMan

The respective last value ist taken for the configuration key for user.