Skip to content

Commit

Permalink
Update documentation in README.md.
Browse files Browse the repository at this point in the history
  • Loading branch information
greg-1-anderson committed Jun 27, 2017
1 parent 273a137 commit 86a25fe
Showing 1 changed file with 66 additions and 0 deletions.
66 changes: 66 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,62 @@ Under development.

Provide a simple Config class that can be injected where needed to provide configuration values in non-command classes, and make configuration settings a no-op for command classes by automatically initializing the Input object from configuration as needed.

## Configuration File Usage

Configuration files are simple hierarchical yaml files.

### Providing Command Options

Command options are defined by creating an entry for each command name under the `command:` section of the configuration file. The options for the command should be defined within an `options:` section. For example, to set a configuration value `red` for the option `--color` in the `example` command:
```
command:
example:
options:
color: red
```
If a command name contains a `:`, then each section of the command name defines another level of heirarchy in the command option configuration. For example, to set a configuration value `George` for the option `--name` of the command `my:foo`:
```
command:
my:
foo:
options:
name: George
```
Furthermore, every level of the command name heirarchy may contain options. For example, to define a configuration value for the option `--dir` for any command that begins with `my:`:
```
command:
my:
options:
dir: '/base/path'
foo:
options:
name: George
bar:
options:
priority: high
```

### Configuration Value Substitution

It is possible to define values in a configuration file that will be substituted in wherever used. For example:
```
common:
path: '/shared/path'
command:
my:
options:
dir: '${common.path}'
foo:
options:
name: George
```

[grasmash/yaml-expander](https://github.com/grasmash/yaml-expander) is used to provide this capability.

## API Usage

The easiest way to utilize the capabilities of this project is to use [Robo as a framework](https://robo.li/framework) to create your commandline tools. Using Robo is optional, though, as this project will work with any Symfony Console application.

### Load Configuration Files
```
use Consolidation\Config\Config;
Expand All @@ -39,6 +93,18 @@ $processor->extend($loader->load('defaults.yml'));
$processor->extend($loader->load('myconf.yml'));
$config->import($processor->export());
```

### Set Up Command Option Configuration Injection

```
$configInjector = new InjectConfigForCommand($config);
$application = new Application($name, $version);
$eventDispatcher = new \Symfony\Component\EventDispatcher\EventDispatcher();
$eventDispatcher->addSubscriber($configInjector);
$application->setDispatcher($eventDispatcher);
```

### Get Configuration Values
If you have a configuration file that looks like this:
```
Expand Down

0 comments on commit 86a25fe

Please sign in to comment.