Skip to content

Commit 94c306f

Browse files
Merge pull request #410 from matthiasbeyer/fix-environment-docs
Copy member docs to builder functions
2 parents 040958c + 2bb2a63 commit 94c306f

File tree

1 file changed

+48
-0
lines changed

1 file changed

+48
-0
lines changed

src/env.rs

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,13 +96,21 @@ impl Environment {
9696
Self::default()
9797
}
9898

99+
/// Optional prefix that will limit access to the environment to only keys that
100+
/// begin with the defined prefix.
101+
///
102+
/// A prefix with a separator of `_` is tested to be present on each key before its considered
103+
/// to be part of the source environment.
104+
///
105+
/// For example, the key `CONFIG_DEBUG` would become `DEBUG` with a prefix of `config`.
99106
pub fn with_prefix(s: &str) -> Self {
100107
Self {
101108
prefix: Some(s.into()),
102109
..Self::default()
103110
}
104111
}
105112

113+
/// See [Environment::with_prefix]
106114
pub fn prefix(mut self, s: &str) -> Self {
107115
self.prefix = Some(s.into());
108116
self
@@ -119,11 +127,15 @@ impl Environment {
119127
self
120128
}
121129

130+
/// Optional character sequence that separates the prefix from the rest of the key
122131
pub fn prefix_separator(mut self, s: &str) -> Self {
123132
self.prefix_separator = Some(s.into());
124133
self
125134
}
126135

136+
/// Optional character sequence that separates each key segment in an environment key pattern.
137+
/// Consider a nested configuration such as `redis.password`, a separator of `_` would allow
138+
/// an environment key of `REDIS_PASSWORD` to match.
127139
pub fn separator(mut self, s: &str) -> Self {
128140
self.separator = Some(s.into());
129141
self
@@ -151,6 +163,7 @@ impl Environment {
151163
self
152164
}
153165

166+
/// Ignore empty env values (treat as unset).
154167
pub fn ignore_empty(mut self, ignore: bool) -> Self {
155168
self.ignore_empty = ignore;
156169
self
@@ -163,11 +176,46 @@ impl Environment {
163176
self
164177
}
165178

179+
// Preserve the prefix while parsing
166180
pub fn keep_prefix(mut self, keep: bool) -> Self {
167181
self.keep_prefix = keep;
168182
self
169183
}
170184

185+
/// Alternate source for the environment. This can be used when you want to test your own code
186+
/// using this source, without the need to change the actual system environment variables.
187+
///
188+
/// ## Example
189+
///
190+
/// ```rust
191+
/// # use config::{Environment, Config};
192+
/// # use serde::Deserialize;
193+
/// # use std::collections::HashMap;
194+
/// # use std::convert::TryInto;
195+
/// #
196+
/// #[test]
197+
/// fn test_config() -> Result<(), config::ConfigError> {
198+
/// #[derive(Clone, Debug, Deserialize)]
199+
/// struct MyConfig {
200+
/// pub my_string: String,
201+
/// }
202+
///
203+
/// let source = Environment::default()
204+
/// .source(Some({
205+
/// let mut env = HashMap::new();
206+
/// env.insert("MY_STRING".into(), "my-value".into());
207+
/// env
208+
/// }));
209+
///
210+
/// let config: MyConfig = Config::builder()
211+
/// .add_source(source)
212+
/// .build()?
213+
/// .try_into()?;
214+
/// assert_eq!(config.my_string, "my-value");
215+
///
216+
/// Ok(())
217+
/// }
218+
/// ```
171219
pub fn source(mut self, source: Option<Map<String, String>>) -> Self {
172220
self.source = source;
173221
self

0 commit comments

Comments
 (0)