Config class

A hierarchical configuration.

Configuration can be provided from three sources: commandline arguments, environment variables and configuration files. This configuration 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.

Constructors

Config({List<String> commandLineDefines = const [], Uri? workingDirectory, Map<String, String> environment = const {}, Map<String, dynamic> fileParsed = const {}, Uri? fileSourceUri})
Constructs a config by parsing the three sources.
factory
Config.fromConfigFileContents({List<String> commandLineDefines = const [], Uri? workingDirectory, Map<String, String> environment = const {}, String? fileContents, Uri? fileSourceUri})
Constructs a config by parsing the three sources.
factory

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

bool(String key) → bool
Lookup a boolean value in this config.
double(String key) → double
Lookup an double value in this config.
int(String key) → int
Lookup an integer value in this config.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
optionalBool(String key) → bool?
Lookup an optional boolean value in this config.
optionalDouble(String key) → double?
Lookup an optional double value in this config.
optionalInt(String key) → int?
Lookup an optional integer value in this config.
optionalPath(String key, {bool resolveUri = true, bool mustExist = false}) → Uri?
Lookup an optional path in this config.
optionalPathList(String key, {bool combineAllConfigs = true, String? splitCliPattern, String? splitEnvironmentPattern, bool resolveUri = true}) → List<Uri>?
Lookup an optional list of paths in this config.
optionalString(String key, {Iterable<String>? validValues}) → String?
Lookup an optional string value in this config.
optionalStringList(String key, {bool combineAllConfigs = true, String? splitCliPattern, String? splitEnvironmentPattern}) → List<String>?
Lookup an optional string list in this config.
path(String key, {bool resolveUri = true, bool mustExist = false}) → Uri
Lookup a path in this config.
pathList(String key, {bool combineAllConfigs = true, String? splitCliPattern, String? splitEnvironmentPattern, bool resolveUri = true}) → List<Uri>
Lookup a list of paths in this config.
string(String key, {Iterable<String>? validValues}) → String
Lookup a string value in this config.
stringList(String key, {bool combineAllConfigs = true, String? splitCliPattern, String? splitEnvironmentPattern}) → List<String>
Lookup an optional string list in this config.
toString() → String
A string representation of this object.
override
valueOf<T>(String key) → T
Lookup a value of type T in this configuration.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

fromArguments({required List<String> arguments, Map<String, String>? environment, Uri? workingDirectory}) → Future<Config>
Constructs a config by parsing CLI arguments and loading the config file.
fromArgumentsSync({required List<String> arguments, Map<String, String>? environment, Uri? workingDirectory}) → Config
Constructs a config by parsing CLI arguments and loading the config file.

Constants

boolStrings → const Map<String, bool>