pub struct Configuration { /* private fields */ }Expand description
A parsed POM configuration.
Implementations§
Source§impl Configuration
impl Configuration
Sourcepub fn load<R: Read>(filename: &str, reader: R) -> Result<Self>
pub fn load<R: Read>(filename: &str, reader: R) -> Result<Self>
Load a configuration.
reader can be &[u8] or anything that implements std::io::BufRead
(if the std feature is enabled) such as std::io::BufReader<std::fs::File>.
filename is used in error messages.
Sourcepub fn load_path<P: AsRef<Path>>(path: P) -> Result<Self>
pub fn load_path<P: AsRef<Path>>(path: P) -> Result<Self>
Load a configuration from a file path.
Examples found in repository?
examples/read_conf.rs (line 6)
4fn try_main() -> Result<(), Box<dyn std::error::Error>> {
5 // Try editing examples/conf.pom and see how the output changes!
6 let conf = Configuration::load_path("examples/conf.pom")?;
7 // get looks up a key in a configuration file.
8 // it returns Some(value) if the key is set to value,
9 // and None otherwise.
10 println!(
11 "indenting with {}",
12 conf.get("indentation-type")
13 .ok_or("you must pick an indentation-type!")?
14 );
15 // get_int_or_default parses a key as an integer.
16 // It returns an Err if the key is set to something that’s not a valid integer.
17 println!("tab width is {}", conf.get_int_or_default("tab-size", 8)?);
18 // get_bool_or_default parses a key as a boolean.
19 // no, off, false all count as false, and yes, on, true count as true.
20 println!(
21 "show line numbers: {}",
22 conf.get_bool_or_default("show-line-numbers", false)?
23 );
24 // lists are comma-separated. they can use \, to escape literal commas.
25 println!("C++ extensions: {:?}", conf.get_list("file-extensions.Cpp"));
26
27 println!("===plug-ins===");
28 // extract out a section of a configuration
29 let plug_ins = conf.section("plug-in");
30 for plug_in in plug_ins.keys() {
31 // extract out just this plug-in's section
32 let plug_in_cfg = plug_ins.section(plug_in);
33 println!(
34 "{plug_in} is {}",
35 if plug_in_cfg.get_bool_or_default("enabled", true)? {
36 "enabled"
37 } else {
38 "disabled"
39 }
40 );
41 println!(
42 "{plug_in} plug-in path: {:?}",
43 plug_in_cfg
44 .get("path")
45 .ok_or_else(|| format!("no path set for plug-in {plug_in}!"))?
46 );
47 }
48 Ok(())
49}Sourcepub fn section(&self, key: &str) -> Configuration
pub fn section(&self, key: &str) -> Configuration
Extract a section out of a configuration.
More specifically, this will give you the configuration consisting of all
keys starting with key. in self, together with their values.
Examples found in repository?
examples/read_conf.rs (line 29)
4fn try_main() -> Result<(), Box<dyn std::error::Error>> {
5 // Try editing examples/conf.pom and see how the output changes!
6 let conf = Configuration::load_path("examples/conf.pom")?;
7 // get looks up a key in a configuration file.
8 // it returns Some(value) if the key is set to value,
9 // and None otherwise.
10 println!(
11 "indenting with {}",
12 conf.get("indentation-type")
13 .ok_or("you must pick an indentation-type!")?
14 );
15 // get_int_or_default parses a key as an integer.
16 // It returns an Err if the key is set to something that’s not a valid integer.
17 println!("tab width is {}", conf.get_int_or_default("tab-size", 8)?);
18 // get_bool_or_default parses a key as a boolean.
19 // no, off, false all count as false, and yes, on, true count as true.
20 println!(
21 "show line numbers: {}",
22 conf.get_bool_or_default("show-line-numbers", false)?
23 );
24 // lists are comma-separated. they can use \, to escape literal commas.
25 println!("C++ extensions: {:?}", conf.get_list("file-extensions.Cpp"));
26
27 println!("===plug-ins===");
28 // extract out a section of a configuration
29 let plug_ins = conf.section("plug-in");
30 for plug_in in plug_ins.keys() {
31 // extract out just this plug-in's section
32 let plug_in_cfg = plug_ins.section(plug_in);
33 println!(
34 "{plug_in} is {}",
35 if plug_in_cfg.get_bool_or_default("enabled", true)? {
36 "enabled"
37 } else {
38 "disabled"
39 }
40 );
41 println!(
42 "{plug_in} plug-in path: {:?}",
43 plug_in_cfg
44 .get("path")
45 .ok_or_else(|| format!("no path set for plug-in {plug_in}!"))?
46 );
47 }
48 Ok(())
49}Sourcepub fn keys(&self) -> Keys<'_> ⓘ
pub fn keys(&self) -> Keys<'_> ⓘ
Get all “direct keys” in this configuration.
More specifically, this returns an iterator of all unique
first components of keys in self.
(So if there were keys sheep.age, sheep.colour, and farmer-name,
this would give an iterator yielding
"farmer-name" and "sheep" in some order.)
The order of items returned is arbitrary and may change in future versions without notice.
Examples found in repository?
examples/read_conf.rs (line 30)
4fn try_main() -> Result<(), Box<dyn std::error::Error>> {
5 // Try editing examples/conf.pom and see how the output changes!
6 let conf = Configuration::load_path("examples/conf.pom")?;
7 // get looks up a key in a configuration file.
8 // it returns Some(value) if the key is set to value,
9 // and None otherwise.
10 println!(
11 "indenting with {}",
12 conf.get("indentation-type")
13 .ok_or("you must pick an indentation-type!")?
14 );
15 // get_int_or_default parses a key as an integer.
16 // It returns an Err if the key is set to something that’s not a valid integer.
17 println!("tab width is {}", conf.get_int_or_default("tab-size", 8)?);
18 // get_bool_or_default parses a key as a boolean.
19 // no, off, false all count as false, and yes, on, true count as true.
20 println!(
21 "show line numbers: {}",
22 conf.get_bool_or_default("show-line-numbers", false)?
23 );
24 // lists are comma-separated. they can use \, to escape literal commas.
25 println!("C++ extensions: {:?}", conf.get_list("file-extensions.Cpp"));
26
27 println!("===plug-ins===");
28 // extract out a section of a configuration
29 let plug_ins = conf.section("plug-in");
30 for plug_in in plug_ins.keys() {
31 // extract out just this plug-in's section
32 let plug_in_cfg = plug_ins.section(plug_in);
33 println!(
34 "{plug_in} is {}",
35 if plug_in_cfg.get_bool_or_default("enabled", true)? {
36 "enabled"
37 } else {
38 "disabled"
39 }
40 );
41 println!(
42 "{plug_in} plug-in path: {:?}",
43 plug_in_cfg
44 .get("path")
45 .ok_or_else(|| format!("no path set for plug-in {plug_in}!"))?
46 );
47 }
48 Ok(())
49}Sourcepub fn iter(&self) -> ConfigurationIter<'_> ⓘ
pub fn iter(&self) -> ConfigurationIter<'_> ⓘ
Get all defined keys in this configuration, including nested ones, and their values.
The order of items returned is arbitrary and may change in future versions without notice.
Sourcepub fn get(&self, key: &str) -> Option<&str>
pub fn get(&self, key: &str) -> Option<&str>
Get value associated with key, if any.
Examples found in repository?
examples/read_conf.rs (line 12)
4fn try_main() -> Result<(), Box<dyn std::error::Error>> {
5 // Try editing examples/conf.pom and see how the output changes!
6 let conf = Configuration::load_path("examples/conf.pom")?;
7 // get looks up a key in a configuration file.
8 // it returns Some(value) if the key is set to value,
9 // and None otherwise.
10 println!(
11 "indenting with {}",
12 conf.get("indentation-type")
13 .ok_or("you must pick an indentation-type!")?
14 );
15 // get_int_or_default parses a key as an integer.
16 // It returns an Err if the key is set to something that’s not a valid integer.
17 println!("tab width is {}", conf.get_int_or_default("tab-size", 8)?);
18 // get_bool_or_default parses a key as a boolean.
19 // no, off, false all count as false, and yes, on, true count as true.
20 println!(
21 "show line numbers: {}",
22 conf.get_bool_or_default("show-line-numbers", false)?
23 );
24 // lists are comma-separated. they can use \, to escape literal commas.
25 println!("C++ extensions: {:?}", conf.get_list("file-extensions.Cpp"));
26
27 println!("===plug-ins===");
28 // extract out a section of a configuration
29 let plug_ins = conf.section("plug-in");
30 for plug_in in plug_ins.keys() {
31 // extract out just this plug-in's section
32 let plug_in_cfg = plug_ins.section(plug_in);
33 println!(
34 "{plug_in} is {}",
35 if plug_in_cfg.get_bool_or_default("enabled", true)? {
36 "enabled"
37 } else {
38 "disabled"
39 }
40 );
41 println!(
42 "{plug_in} plug-in path: {:?}",
43 plug_in_cfg
44 .get("path")
45 .ok_or_else(|| format!("no path set for plug-in {plug_in}!"))?
46 );
47 }
48 Ok(())
49}Sourcepub fn location(&self, key: &str) -> Option<Location>
pub fn location(&self, key: &str) -> Option<Location>
Get location in the configuration file where key is defined, if any.
Sourcepub fn get_or_default<'a>(&'a self, key: &str, default: &'a str) -> &'a str
pub fn get_or_default<'a>(&'a self, key: &str, default: &'a str) -> &'a str
Get value associated with key, or else use default if it isn’t defined.
Sourcepub fn get_int(&self, key: &str) -> Option<Result<i64>>
pub fn get_int(&self, key: &str) -> Option<Result<i64>>
Get value associated with key, and parse it as an integer.
Returns None if key is not defined,
and Some(Err(…)) if key is defined but not an integer.
Sourcepub fn get_int_or_default(&self, key: &str, default: i64) -> Result<i64>
pub fn get_int_or_default(&self, key: &str, default: i64) -> Result<i64>
Get value associated with key, and parse it as an integer, or else use default.
Returns Err(…) if key is defined but not an integer.
Examples found in repository?
examples/read_conf.rs (line 17)
4fn try_main() -> Result<(), Box<dyn std::error::Error>> {
5 // Try editing examples/conf.pom and see how the output changes!
6 let conf = Configuration::load_path("examples/conf.pom")?;
7 // get looks up a key in a configuration file.
8 // it returns Some(value) if the key is set to value,
9 // and None otherwise.
10 println!(
11 "indenting with {}",
12 conf.get("indentation-type")
13 .ok_or("you must pick an indentation-type!")?
14 );
15 // get_int_or_default parses a key as an integer.
16 // It returns an Err if the key is set to something that’s not a valid integer.
17 println!("tab width is {}", conf.get_int_or_default("tab-size", 8)?);
18 // get_bool_or_default parses a key as a boolean.
19 // no, off, false all count as false, and yes, on, true count as true.
20 println!(
21 "show line numbers: {}",
22 conf.get_bool_or_default("show-line-numbers", false)?
23 );
24 // lists are comma-separated. they can use \, to escape literal commas.
25 println!("C++ extensions: {:?}", conf.get_list("file-extensions.Cpp"));
26
27 println!("===plug-ins===");
28 // extract out a section of a configuration
29 let plug_ins = conf.section("plug-in");
30 for plug_in in plug_ins.keys() {
31 // extract out just this plug-in's section
32 let plug_in_cfg = plug_ins.section(plug_in);
33 println!(
34 "{plug_in} is {}",
35 if plug_in_cfg.get_bool_or_default("enabled", true)? {
36 "enabled"
37 } else {
38 "disabled"
39 }
40 );
41 println!(
42 "{plug_in} plug-in path: {:?}",
43 plug_in_cfg
44 .get("path")
45 .ok_or_else(|| format!("no path set for plug-in {plug_in}!"))?
46 );
47 }
48 Ok(())
49}Sourcepub fn get_uint(&self, key: &str) -> Option<Result<u64>>
pub fn get_uint(&self, key: &str) -> Option<Result<u64>>
Get value associated with key, and parse it as an unsigned integer.
Returns None if key is not defined,
and Some(Err(…)) if key is defined but not an unsigned integer.
Sourcepub fn get_uint_or_default(&self, key: &str, default: u64) -> Result<u64>
pub fn get_uint_or_default(&self, key: &str, default: u64) -> Result<u64>
Get value associated with key, and parse it as an unsinged integer, or else use default.
Returns Err(…) if key is defined but not an unsigned integer.
Sourcepub fn get_float(&self, key: &str) -> Option<Result<f64>>
pub fn get_float(&self, key: &str) -> Option<Result<f64>>
Get value associated with key, and parse it as a float.
Returns None if key is not defined,
and Some(Err(…)) if key is defined but not a float.
Sourcepub fn get_float_or_default(&self, key: &str, default: f64) -> Result<f64>
pub fn get_float_or_default(&self, key: &str, default: f64) -> Result<f64>
Get value associated with key, and parse it as a float, or else use default.
Returns Err(…) if key is defined but not a float.
Sourcepub fn get_bool(&self, key: &str) -> Option<Result<bool>>
pub fn get_bool(&self, key: &str) -> Option<Result<bool>>
Get value associated with key, and parse it as a boolean.
Returns None if key is not defined,
and Some(Err(…)) if key is defined but not equal to one of
off, no, false, on, yes, true.
Sourcepub fn get_bool_or_default(&self, key: &str, default: bool) -> Result<bool>
pub fn get_bool_or_default(&self, key: &str, default: bool) -> Result<bool>
Get value associated with key, and parse it as a boolean, or else use default.
Returns Err(…) if key is defined but not equal to one of
off, no, false, on, yes, true.
Examples found in repository?
examples/read_conf.rs (line 22)
4fn try_main() -> Result<(), Box<dyn std::error::Error>> {
5 // Try editing examples/conf.pom and see how the output changes!
6 let conf = Configuration::load_path("examples/conf.pom")?;
7 // get looks up a key in a configuration file.
8 // it returns Some(value) if the key is set to value,
9 // and None otherwise.
10 println!(
11 "indenting with {}",
12 conf.get("indentation-type")
13 .ok_or("you must pick an indentation-type!")?
14 );
15 // get_int_or_default parses a key as an integer.
16 // It returns an Err if the key is set to something that’s not a valid integer.
17 println!("tab width is {}", conf.get_int_or_default("tab-size", 8)?);
18 // get_bool_or_default parses a key as a boolean.
19 // no, off, false all count as false, and yes, on, true count as true.
20 println!(
21 "show line numbers: {}",
22 conf.get_bool_or_default("show-line-numbers", false)?
23 );
24 // lists are comma-separated. they can use \, to escape literal commas.
25 println!("C++ extensions: {:?}", conf.get_list("file-extensions.Cpp"));
26
27 println!("===plug-ins===");
28 // extract out a section of a configuration
29 let plug_ins = conf.section("plug-in");
30 for plug_in in plug_ins.keys() {
31 // extract out just this plug-in's section
32 let plug_in_cfg = plug_ins.section(plug_in);
33 println!(
34 "{plug_in} is {}",
35 if plug_in_cfg.get_bool_or_default("enabled", true)? {
36 "enabled"
37 } else {
38 "disabled"
39 }
40 );
41 println!(
42 "{plug_in} plug-in path: {:?}",
43 plug_in_cfg
44 .get("path")
45 .ok_or_else(|| format!("no path set for plug-in {plug_in}!"))?
46 );
47 }
48 Ok(())
49}Sourcepub fn get_list(&self, key: &str) -> Option<Vec<String>>
pub fn get_list(&self, key: &str) -> Option<Vec<String>>
Get value associated with key, and parse it as a comma-separated list.
Commas in list entries can be escaped with \,.
Examples found in repository?
examples/read_conf.rs (line 25)
4fn try_main() -> Result<(), Box<dyn std::error::Error>> {
5 // Try editing examples/conf.pom and see how the output changes!
6 let conf = Configuration::load_path("examples/conf.pom")?;
7 // get looks up a key in a configuration file.
8 // it returns Some(value) if the key is set to value,
9 // and None otherwise.
10 println!(
11 "indenting with {}",
12 conf.get("indentation-type")
13 .ok_or("you must pick an indentation-type!")?
14 );
15 // get_int_or_default parses a key as an integer.
16 // It returns an Err if the key is set to something that’s not a valid integer.
17 println!("tab width is {}", conf.get_int_or_default("tab-size", 8)?);
18 // get_bool_or_default parses a key as a boolean.
19 // no, off, false all count as false, and yes, on, true count as true.
20 println!(
21 "show line numbers: {}",
22 conf.get_bool_or_default("show-line-numbers", false)?
23 );
24 // lists are comma-separated. they can use \, to escape literal commas.
25 println!("C++ extensions: {:?}", conf.get_list("file-extensions.Cpp"));
26
27 println!("===plug-ins===");
28 // extract out a section of a configuration
29 let plug_ins = conf.section("plug-in");
30 for plug_in in plug_ins.keys() {
31 // extract out just this plug-in's section
32 let plug_in_cfg = plug_ins.section(plug_in);
33 println!(
34 "{plug_in} is {}",
35 if plug_in_cfg.get_bool_or_default("enabled", true)? {
36 "enabled"
37 } else {
38 "disabled"
39 }
40 );
41 println!(
42 "{plug_in} plug-in path: {:?}",
43 plug_in_cfg
44 .get("path")
45 .ok_or_else(|| format!("no path set for plug-in {plug_in}!"))?
46 );
47 }
48 Ok(())
49}Sourcepub fn get_list_or_default<L>(&self, key: &str, default: L) -> Vec<String>
pub fn get_list_or_default<L>(&self, key: &str, default: L) -> Vec<String>
Get value associated with key, and parse it as a comma-separated list, or else use default.
If you want default = [], use Self::get_list_or_empty instead
(this method will be cumbersome to use since Rust can’t infer the type of []).
Commas in list entries can be escaped with \,.
default can be any iterable-of-strings (&[&str], Vec<String>, etc.).
Sourcepub fn get_list_or_empty(&self, key: &str) -> Vec<String>
pub fn get_list_or_empty(&self, key: &str) -> Vec<String>
Get value associated with key, and parse it as a comma-separated list, or else use [].
Sourcepub fn merge(&mut self, conf: &Configuration)
pub fn merge(&mut self, conf: &Configuration)
Merge conf into self, preferring values in conf.
Sourcepub fn unread_keys(&self) -> UnreadKeys<'_> ⓘ
pub fn unread_keys(&self) -> UnreadKeys<'_> ⓘ
Returns an iterator over all keys whose values have not been read.
This includes getting them through Self::get, Self::get_or_default, Self::get_int, etc.
It also includes getting them through Self::get called on a section obtained via Self::section.
The order of the items returned is arbitrary and may change in future versions without notice.
Beware of race conditions when using this function in a multithreaded program (you should wait for all threads to finish reading the configuration before calling this).
Trait Implementations§
Source§impl Clone for Configuration
impl Clone for Configuration
Source§fn clone(&self) -> Configuration
fn clone(&self) -> Configuration
Returns a duplicate of the value. Read more
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from
source. Read moreSource§impl Debug for Configuration
impl Debug for Configuration
Source§impl Default for Configuration
impl Default for Configuration
Source§fn default() -> Configuration
fn default() -> Configuration
Returns the “default value” for a type. Read more
Source§impl Display for Configuration
impl Display for Configuration
Source§impl<'a> IntoIterator for &'a Configuration
impl<'a> IntoIterator for &'a Configuration
Auto Trait Implementations§
impl Freeze for Configuration
impl RefUnwindSafe for Configuration
impl Send for Configuration
impl Sync for Configuration
impl Unpin for Configuration
impl UnwindSafe for Configuration
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more