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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
use std::env;
use std::ffi::OsString;
#[cfg(feature = "convert-case")]
use convert_case::{Case, Casing};
use crate::ConfigError;
use crate::error::Result;
use crate::map::Map;
use crate::source::Source;
use crate::value::{Value, ValueKind};
/// An environment source collects a dictionary of environment variables values into a hierarchical
/// config Value type. We have to be aware how the config tree is created from the environment
/// dictionary, therefore we are mindful about prefixes for the environment keys, level separators,
/// encoding form (kebab, snake case) etc.
///
/// For prefixes take a look at [`with_prefix`](Environment::with_prefix()).
/// For level separators take a look at [`separator`](Environment::separator()).
#[must_use]
#[derive(Clone, Debug, Default)]
pub struct Environment {
/// Optional prefix that will limit access to the environment to only keys that
/// begin with the defined prefix.
///
/// The prefix is tested to be present on each key before it's considered to be part of the
/// source environment. The separator character can be set through
/// [`prefix_separator`](Environment::prefix_separator()).
///
/// For example, the key `CONFIG_DEBUG` would become `DEBUG` with a prefix of `config`.
prefix: Option<String>,
/// Optional character sequence that separates the prefix from the rest of the key.
///
/// Defaults to [`separator`](Environment::separator()) if that is set, otherwise `_`.
prefix_separator: Option<String>,
/// Optional character sequence that separates each key segment in an environment key pattern.
/// Consider a nested configuration such as `redis.password`, a separator of `_` would allow
/// an environment key of `REDIS_PASSWORD` to match.
///
/// If unset, `.` (a dot) is used. In such case `REDIS.PASSWORD` would be the correct key
/// for the example above.
separator: Option<String>,
/// Optional directive to translate collected keys into a form that matches what serializers
/// that the configuration would expect. For example if you have the `kebab-case` attribute
/// for your serde config types, you may want to pass `Case::Kebab` here.
#[cfg(feature = "convert-case")]
convert_case: Option<Case>,
/// Optional character sequence that separates each env value into a vector. only works when `try_parsing` is set to true
/// Once set, you cannot have type String on the same environment, unless you set `list_parse_keys`.
list_separator: Option<String>,
/// A list of keys which should always be parsed as a list. If not set you can have only `Vec<String>` or `String` (not both) in one environment.
list_parse_keys: Option<Vec<String>>,
/// Ignore empty env values (treat as unset).
ignore_empty: bool,
/// Parses booleans, integers and floats if they're detected (can be safely parsed).
try_parsing: bool,
// Preserve the prefix while parsing
keep_prefix: bool,
/// Alternate source for the environment. This can be used when you want to test your own code
/// using this source, without the need to change the actual system environment variables.
///
/// ## Example
///
/// ```rust
/// # use config::{Environment, Config};
/// # use serde::Deserialize;
/// # use std::collections::HashMap;
/// # use std::convert::TryInto;
/// #
/// #[test]
/// fn test_config() -> Result<(), config::ConfigError> {
/// #[derive(Clone, Debug, Deserialize)]
/// struct MyConfig {
/// pub my_string: String,
/// }
///
/// let source = Environment::default()
/// .source(Some({
/// let mut env = HashMap::new();
/// env.insert("MY_STRING".into(), "my-value".into());
/// env
/// }));
///
/// let config: MyConfig = Config::builder()
/// .add_source(source)
/// .build()?
/// .try_into()?;
/// assert_eq!(config.my_string, "my-value");
///
/// Ok(())
/// }
/// ```
source: Option<Map<String, String>>,
}
impl Environment {
/// Optional prefix that will limit access to the environment to only keys that
/// begin with the defined prefix.
///
/// The prefix is tested to be present on each key before it's considered to be part of the
/// source environment. The separator character can be set through
/// [`prefix_separator`](Environment::prefix_separator()).
///
/// For example, the key `CONFIG_DEBUG` would become `DEBUG` with a prefix of `config`.
pub fn with_prefix(s: &str) -> Self {
Self {
prefix: Some(s.into()),
..Self::default()
}
}
/// See [`Environment::with_prefix`]
pub fn prefix(mut self, s: &str) -> Self {
self.prefix = Some(s.into());
self
}
#[cfg(feature = "convert-case")]
pub fn with_convert_case(tt: Case) -> Self {
Self::default().convert_case(tt)
}
#[cfg(feature = "convert-case")]
pub fn convert_case(mut self, tt: Case) -> Self {
self.convert_case = Some(tt);
self
}
/// Optional character sequence that separates the prefix from the rest of the key.
///
/// Defaults to [`separator`](Environment::separator()) if that is set, otherwise `_`.
pub fn prefix_separator(mut self, s: &str) -> Self {
self.prefix_separator = Some(s.into());
self
}
/// Optional character sequence that separates each key segment in an environment key pattern.
/// Consider a nested configuration such as `redis.password`, a separator of `_` would allow
/// an environment key of `REDIS_PASSWORD` to match.
///
/// If unset, `.` (a dot) is used. In such case `REDIS.PASSWORD` would be the correct key
/// for the example above.
pub fn separator(mut self, s: &str) -> Self {
self.separator = Some(s.into());
self
}
/// When set and `try_parsing` is true, then all environment variables will be parsed as [`Vec<String>`] instead of [`String`].
/// See
/// [`with_list_parse_key`](Self::with_list_parse_key)
/// when you want to use [`Vec<String>`] in combination with [`String`].
pub fn list_separator(mut self, s: &str) -> Self {
self.list_separator = Some(s.into());
self
}
/// Add a key which should be parsed as a list when collecting [`Value`]s from the environment.
/// Once `list_separator` is set, the type for string is [`Vec<String>`].
/// To switch the default type back to type Strings you need to provide the keys which should be [`Vec<String>`] using this function.
pub fn with_list_parse_key(mut self, key: &str) -> Self {
let keys = self.list_parse_keys.get_or_insert_with(Vec::new);
keys.push(key.into());
self
}
/// Ignore empty env values (treat as unset).
pub fn ignore_empty(mut self, ignore: bool) -> Self {
self.ignore_empty = ignore;
self
}
/// Note: enabling `try_parsing` can reduce performance it will try and parse
/// each environment variable 3 times (bool, i64, f64)
pub fn try_parsing(mut self, try_parsing: bool) -> Self {
self.try_parsing = try_parsing;
self
}
// Preserve the prefix while parsing
pub fn keep_prefix(mut self, keep: bool) -> Self {
self.keep_prefix = keep;
self
}
/// Alternate source for the environment. This can be used when you want to test your own code
/// using this source, without the need to change the actual system environment variables.
///
/// ## Example
///
/// ```rust
/// # use config::{Environment, Config};
/// # use serde::Deserialize;
/// # use std::collections::HashMap;
/// # use std::convert::TryInto;
/// #
/// #[test]
/// fn test_config() -> Result<(), config::ConfigError> {
/// #[derive(Clone, Debug, Deserialize)]
/// struct MyConfig {
/// pub my_string: String,
/// }
///
/// let source = Environment::default()
/// .source(Some({
/// let mut env = HashMap::new();
/// env.insert("MY_STRING".into(), "my-value".into());
/// env
/// }));
///
/// let config: MyConfig = Config::builder()
/// .add_source(source)
/// .build()?
/// .try_into()?;
/// assert_eq!(config.my_string, "my-value");
///
/// Ok(())
/// }
/// ```
pub fn source(mut self, source: Option<Map<String, String>>) -> Self {
self.source = source;
self
}
}
impl Source for Environment {
fn clone_into_box(&self) -> Box<dyn Source + Send + Sync> {
Box::new((*self).clone())
}
fn collect(&self) -> Result<Map<String, Value>> {
let mut m = Map::new();
let uri: String = "the environment".into();
let separator = self.separator.as_deref().unwrap_or("");
#[cfg(feature = "convert-case")]
let convert_case = &self.convert_case;
let prefix_separator = match (self.prefix_separator.as_deref(), self.separator.as_deref()) {
(Some(pre), _) => pre,
(None, Some(sep)) => sep,
(None, None) => "_",
};
// Define a prefix pattern to test and exclude from keys
let prefix_pattern = self
.prefix
.as_ref()
.map(|prefix| format!("{prefix}{prefix_separator}").to_lowercase());
let collector = |(key, value): (OsString, OsString)| {
let key = match key.into_string() {
Ok(key) => key,
// Key is not valid unicode, skip it
Err(_) => return Ok(()),
};
// Treat empty environment variables as unset
if self.ignore_empty && value.is_empty() {
return Ok(());
}
let mut key = key.to_lowercase();
// Check for prefix
if let Some(ref prefix_pattern) = prefix_pattern {
if key.starts_with(prefix_pattern) {
if !self.keep_prefix {
// Remove this prefix from the key
key = key[prefix_pattern.len()..].to_string();
}
} else {
// Skip this key
return Ok(());
}
}
// At this point, we don't know if the key is required or not.
// Therefore if the value is not a valid unicode string, we error out.
let value = value.into_string().map_err(|os_string| {
ConfigError::Message(format!(
"env variable {key:?} contains non-Unicode data: {os_string:?}"
))
})?;
// If separator is given replace with `.`
if !separator.is_empty() {
key = key.replace(separator, ".");
}
#[cfg(feature = "convert-case")]
if let Some(convert_case) = convert_case {
key = key.to_case(*convert_case);
}
let value = if self.try_parsing {
// convert to lowercase because bool parsing expects all lowercase
if let Ok(parsed) = value.to_lowercase().parse::<bool>() {
ValueKind::Boolean(parsed)
} else if let Ok(parsed) = value.parse::<i64>() {
ValueKind::I64(parsed)
} else if let Ok(parsed) = value.parse::<f64>() {
ValueKind::Float(parsed)
} else if let Some(separator) = &self.list_separator {
if let Some(keys) = &self.list_parse_keys {
if keys.contains(&key) {
let v: Vec<Value> = value
.split(separator)
.map(|s| Value::new(Some(&uri), ValueKind::String(s.to_owned())))
.collect();
ValueKind::Array(v)
} else {
ValueKind::String(value)
}
} else {
let v: Vec<Value> = value
.split(separator)
.map(|s| Value::new(Some(&uri), ValueKind::String(s.to_owned())))
.collect();
ValueKind::Array(v)
}
} else {
ValueKind::String(value)
}
} else {
ValueKind::String(value)
};
m.insert(key, Value::new(Some(&uri), value));
Ok(())
};
match &self.source {
Some(source) => source
.clone()
.into_iter()
.map(|(key, value)| (key.into(), value.into()))
.try_for_each(collector),
None => env::vars_os().try_for_each(collector),
}?;
Ok(m)
}
}