A library to take config values from configuration files, CLI arguments, and environment variables.

Usage

Configuration can be provided from commandline arguments, environment variables, and configuration files. This library makes these accessible via a uniform API.

Configuration can be provided via the three sources as follows:

1. commandline argument defines as -Dsome_key=some_value,
2. environment variables as SOME_KEY=some_value, and
3. config files as JSON or YAML as {'some_key': 'some_value'}.

The default lookup behavior is that commandline argument defines take precedence over environment variables, which take precedence over the configuration file.

If a single value is requested from this configuration, the first source that can provide the value will provide it. For example config.string('some_key') with {'some_key': 'file_value'} in the config file and -Dsome_key=cli_value as commandline argument returns 'cli_value'. The implication is that you can not remove keys from the configuration file, only overwrite or append them.

If a list value is requested from this configuration, the values provided by the various sources can be combined or not. For example config.optionalStringList('some_key', combineAllConfigs: true) returns ['cli_value', 'file_value'].

The config is hierarchical in nature, using . as the hierarchy separator for lookup and commandline defines. The hierarchy should be materialized in the JSON or YAML configuration file. For environment variables __ is used as hierarchy separator.

Hierarchical configuration can be provided via the three sources as follows:

1. commandline argument defines as -Dsome_key.some_nested_key=some_value,
2. environment variables as SOME_KEY__SOME_NESTED_KEY=some_value, and
3. config files as JSON or YAML as

   some_key:
     some_nested_key:
       some_value
   

The config is opinionated on the format of the keys in the sources.

• Command-line argument keys should be lower-cased alphanumeric characters or underscores, with . for hierarchy.
• Environment variables keys should be upper-cased alphanumeric characters or underscores, with __ for hierarchy.
• Config files keys should be lower-cased alphanumeric characters or underscores.

In the API they are made available lower-cased and with underscores, and . as hierarchy separator.

Example usage

This example creates a configuration which first looks for command-line defines in the arguments list then looks in Platform.environment, then looks in any local configuration file.

final config = await Config.fromArguments(arguments: arguments);
final pathValue =
    config.optionalPath('my_path', resolveUri: true, mustExist: false);
print(pathValue?.toFilePath());