smart-config-commands 0.4.0-pre.4

Command-line extensions for `smart-config` library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

# Command-Line Extensions for `smart-config`

[![Build status](https://github.com/matter-labs/smart-config/actions/workflows/ci.yml/badge.svg)](https://github.com/matter-labs/smart-config/actions/workflows/ci.yml)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/License-MIT%2FApache--2.0-blue)](https://github.com/matter-labs/smart-config#license)
![rust 1.91+ required](https://img.shields.io/badge/rust-1.91+-blue.svg?label=Required%20Rust)

**Docs:** [![Docs.rs](https://docs.rs/smart-config-commands/badge.svg)](https://docs.rs/smart-config-commands/)
[![crate docs (main)](https://img.shields.io/badge/main-yellow.svg?label=docs)](https://matter-labs.github.io/smart-config/smart_config_commands/)

This library provides a couple of command-line extensions for the [`smart-config`] library:

- Printing help for configuration params with optional filtering.
- Generating a Markdown reference for configuration params.
- Debugging param values and deserialization errors.

## Usage

Add this to your `Crate.toml`:
<!--- x-release-please-start-version -->
```toml
[dependencies]
smart-config-commands = "0.4.0-pre.4"
```
<!--- x-release-please-end -->

### Printing help on config params

```rust
use std::io;
use smart_config::ConfigSchema;
use smart_config_commands::Printer;

let mut schema = ConfigSchema::default();
// Add configurations to the schema...

Printer::stdout().print_help(&schema, |param_ref| {
    // Allows filtering output params.
    param_ref.param.name.contains("test")
})?;
io::Result::Ok(())
```

Example output is as follows:

![Example output for print_help](examples/help.svg)

### Generating Markdown reference docs

```rust
use std::io;
use smart_config::ConfigSchema;
use smart_config_commands::{MarkdownOptions, Printer};

let mut schema = ConfigSchema::default();
// Add configurations to the schema...

Printer::stdout().print_markdown_reference(&schema, &MarkdownOptions::default(), |_| true)?;
io::Result::Ok(())
```

For a binary exposing configuration utilities, prefer a command name based on the task, for example:

```shell
config docs > docs/src/setup/configuration.md
```

### Debugging param values

```rust
use std::io;
use smart_config::{ConfigSchema, ConfigRepository};
use smart_config_commands::Printer;

let mut schema = ConfigSchema::default();
// Add configurations to the schema...
let mut repo = ConfigRepository::new(&schema);
// Add sources to the repo...

Printer::stdout().print_debug(&repo, |_| true)?;
io::Result::Ok(())
```

Example output is as follows:

![Example output for print_debug](examples/debug.svg)

The output will contain deserialization errors for all available params:

![Example output for print_debug](examples/errors.svg)

### Outputting JSON / YAML

The library can fancy-print JSON and YAML. This be used together with `smart-config` tooling to produce default / example configs,
diffs with default param values etc. See [the example](examples/cli.rs) for a couple of use cases.

![Example of fancy-printed YAML](examples/ser-yaml.svg)

## License

Distributed under the terms of either

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

[`smart-config`]: ../smart-config