72 lines
3.3 KiB
Markdown
72 lines
3.3 KiB
Markdown
|
[](https://github.com/dart-lang/tools/actions/workflows/cli_config.yml)
|
||
|
|
[](https://coveralls.io/github/dart-lang/tools?branch=main)
|
||
|
|
[](https://pub.dev/packages/cli_config)
|
||
|
|
[](https://pub.dev/packages/cli_config/publisher)
|
||
|
|
|
||
|
|
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
|
||
|
|
```yaml
|
||
|
|
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.
|
||
|
|
|
||
|
|
```dart
|
||
|
|
final config = await Config.fromArguments(arguments: arguments);
|
||
|
|
final pathValue =
|
||
|
|
config.optionalPath('my_path', resolveUri: true, mustExist: false);
|
||
|
|
print(pathValue?.toFilePath());
|
||
|
|
```
|