cliconf 0.2.0

Dead-simple configuration for Rust CLI tools.
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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

# cliconf

Dead-simple configuration for Rust CLI tools.

# How it Works

Define a flag that your program accepts:

```rs
use cliconf::{Flag, FlagValue, Flags};

let mut flags = Flags::new();
flags.add(
    Flag::new("hello-name", FlagValue::String("world".into()))
        .shorthand('n')
        .description("Who to say hello to."),
);
```

Add one or more locations of config files:

```rs
flags.add_config_file("/var/lib/hello-world/config.json");
flags.add_home_config_file(".config/hello-world/config.json");
```

Load flags:

```rs
let env_vars: HashMap<String, String> = env::vars().collect();

let args: Vec<String> = env::args().collect();
let args = args[1..].to_vec(); // Exclude name of executable

flags.load(&env_vars, &args)?;
```

Get values:

```rs
let name = flags.get_string("hello-name");
println!("Hello, {name}!");
```

Get non-flag arguments:

```rs
let positionals = flags.positionals();
```

# Using Flags

Flags are always processed in the following order:

1. Configuration files (processed in the order they are added)
2. Environment variables
3. Command-line arguments

The following configuration methods all produce the same result:

1. Configuration files

```json
{
  "hello-name": "john"
}
```

2. Environment variables

```sh
HELLO_NAME="john" hello-world
```

3. Command-line arguments

```sh
hello-world --hello-name "john"
# or, using the shorthand
hello-world -n "john"
```

Flags processed later-on in the cycle take precedence, so command-line
arguments will override environment variables, which will override config
files:

```sh
HELLO_NAME=from_environment hello-world -n from_args
# Outputs: "Hello, from_args!"
```

# Types of Flags

There are 9 types of flag values: `Bool` `String` `Int64` `Int128` `Float64`
`StringArray` `Int64Array` `Int128Array` `Float64Array`. Set a flag's
`default_value` to select one.

The Rust types for each are as follows:

| FlagValue::  | Type          |
|--------------|---------------|
| Bool         | `bool`        |
| String       | `String`      |
| Int64        | `i64`         |
| Int128       | `i128`        |
| Float64      | `f64`         |
| StringArray  | `Vec<String>` |
| Int64Array   | `Vec<i64>`    |
| Int128Array  | `Vec<i128>`   |
| Float64Array | `Vec<f64>`    |

All flags must have default values. This is to ensure that your flags are
always the correct type and that your program always has good opinionated
defaults.

To get values for each type of flag:

```rs
// Single Values
let my_bool = flags.get_bool("my-bool");
let my_string = flags.get_string("my-string");
let my_int64 = flags.get_i64("my-int64");
let my_int128 = flags.get_i128("my-int128");
let my_float64 = flags.get_f64("my-float64");
// Arrays
let my_string_array = flags.get_string_array("my-string-array");
let my_int64_array = flags.get_i64_array("my-int64-array");
let my_int128_array = flags.get_i128_array("my-int128-array");
let my_float64_array = flags.get_f64_array("my-float64-array");
```