preftool 0.2.0

Configuration library for CLI tools/servers.
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

extern crate caseless;
extern crate slog;
#[macro_use]
extern crate lazy_static;
#[macro_use]
extern crate error_chain;

use std::collections::HashSet;
use std::ops::Deref;

pub use bind::Error as ValidationError;
pub use bind::Result as ValidationResult;
pub use bind::{ConfigProxy, FromConfig, Options, ValidateOptions};
pub use config::ConfigBuilder;
pub use provider::{ConfigurationProviderBuilder, DefaultConfigurationProvider};
pub use strings::ConfigKey;
pub use values::Settings;

/// Common trait used by several objects throughout preftool that owns a slog::Logger instance.
pub trait LogOwner {
  fn logger(&self) -> &slog::Logger;
}

/// Configuration trait. Configuration is thread safe, and cloneable.
/// Clones *should* be cheap (default config object consits of cloning an
/// Arc and 3 String instances).
pub trait Configuration: Sized + Send + Sync + Clone {
  /// Type used for configuration sections.
  type Section: Configuration;

  /// Iterator type used to get child sections.
  type Sections: IntoIterator<Item = Self::Section>;

  /// Get a value from the configuration, if it exists.
  fn get<K: Into<ConfigKey>>(&self, key: K) -> Option<&str>;

  /// Get a sub-section from the configuration. This always returns a section,
  /// even if it is empty.
  fn section<K: Into<ConfigKey>>(&self, key: K) -> Self::Section;

  /// Get all child sections of this configuration, as an iterator.
  fn sections(&self) -> Self::Sections;

  /// Get the current section key.
  fn key(&self) -> &ConfigKey;

  /// Get the current section path.
  fn path(&self) -> &ConfigKey;

  /// Get the current section value (if any).
  fn value(&self) -> Option<&str>;
}

/// A configuration provider.
pub trait ConfigurationProvider: Send + Sync {
  /// Try to get a value for a given key.
  fn try_get(&self, key: &ConfigKey) -> Option<&str>;

  /// Get all child keys of a given key.
  fn get_child_keys(&self, key: &ConfigKey, keys: &mut HashSet<ConfigKey>);
}

impl<P: ConfigurationProvider> ConfigurationProvider for Box<P> {
  fn try_get(&self, key: &ConfigKey) -> Option<&str> {
    self.deref().try_get(key)
  }

  fn get_child_keys(&self, key: &ConfigKey, keys: &mut HashSet<ConfigKey>) {
    self.deref().get_child_keys(key, keys)
  }
}

impl ConfigurationProvider for Box<dyn ConfigurationProvider> {
  fn try_get(&self, key: &ConfigKey) -> Option<&str> {
    self.deref().try_get(key)
  }

  fn get_child_keys(&self, key: &ConfigKey, keys: &mut HashSet<ConfigKey>) {
    self.deref().get_child_keys(key, keys)
  }
}

/// A configuration source. Produces one or more configuration providers.
pub trait ConfigurationSource {
  fn build<B: ConfigurationBuilder>(self, builder: B) -> std::io::Result<B>;
}

/// A configuration builder.
pub trait ConfigurationBuilder: Sized {
  /// Resulting configuration type.
  type Config: Configuration;

  // TODO: IntoConfigurationProvider trait?
  /// Add a configuration provider to the builder.
  fn push_provider<P: ConfigurationProvider + 'static>(self, source: P) -> Self;

  /// Add a configuration source to the builder.
  fn add<S: ConfigurationSource>(self, source: S) -> std::io::Result<Self> {
    source.build(self)
  }

  /// Build the configuration.
  fn build(self) -> std::io::Result<Self::Config>;
}

pub mod bind;
mod config;
mod macros;
mod provider;
mod strings;
mod values;