Struct settingsfile::Settings
source · Expand description
Basic one file settings
The main guts of Settingsfile-rs
. The Settings
struct
interacts with the file system to serialize / deserialize
configurations / settings and then allow easy navigation
and maniulation.
Settings
only reads data from one source and doesn’t do
any ‘shadowing’, so if you want to override settings based
on a local user configuration, use the
ShadowSettings
struct instead.
Examples
General Use
Say a file looked like this, and was defined in the Format Config
{
"user" : {
"name" : "user's name",
"email" : "user's email"
}
}
We could access the data like this.
use settingsfile::Settings;
use settingsfile::EmptyConfig; // dumb config for examples and testing
let app_settings = Settings::new(EmptyConfig{});
if let Some(value) = app_settings.get_value("user.name") {
// prints "username is user's name"
println!("username is {}",value);
}
And if we weren’t sure if the user would set a certain value, but would need something during running we can define a default value.
use settingsfile::Settings;
use settingsfile::EmptyConfig; // dumb config for examples and testing
let app_settings = Settings::new(EmptyConfig{});
let font_size = app_settings.get_value_or("font.size",&12);
println!("Font size is {}",font_size); // will either be 12 or whatever the user sets.
Data Validation
Rust is heavy on type safe, and so is settingsfile
. By default a settings file can only
contain the following types (defined in the Type enum)
- Text
- Int
- Float
- Switch
- Array (of any combination of above)
- HashMap (of any combination of above)
Every result of a get
will return a Type that you will need to match in
order to use the data. The only except is when you print / format it, as Type
implements
display.
Using the fontsize example above.
use settingsfile::Settings;
use settingsfile::Type;
use settingsfile::EmptyConfig; // dumb config for examples and testing
let app_settings = Settings::new(EmptyConfig{});
if let Type::Int(size) = app_settings.get_value_or("font.size",&12) {
println!("Setting font size to {}",size);
} else {
println!("Setting font.size must be an int!");
}
Implementations
sourceimpl<T> Settings<T>where
T: Format + Clone,
impl<T> Settings<T>where
T: Format + Clone,
sourcepub fn new(config: T) -> Settings<T>
pub fn new(config: T) -> Settings<T>
Creates an empty Settings
from a configuration.
Initally the settings doesn’t have any data and needs
to have data inserted, set
or loaded, ::load()
.
sourcepub fn new_and_load(config: T) -> Settings<T>
pub fn new_and_load(config: T) -> Settings<T>
A onliner to create a Settings
and load from the config location.
Basically the same thing as .new()
and .load()
. The main difference
is you don’t need to give your Settings mutability if you don’t need it.
Will return an empty setting if it fails loading the file for some reason.
A warn!()
(from the log crate) will be
used if the loading fails.
sourcepub fn create_from(file: &File, config: T) -> Result<Settings<T>, Error>
pub fn create_from(file: &File, config: T) -> Result<Settings<T>, Error>
Loads the content of a File
using the configuration, but doesn’t use
a path or doesn’t infer the path from the config.
Primariy made for testing serializing and deserializing the struture, but
can also because to force the setting
to load from a file buffer
sourcepub fn create_from_or_empty(file: &File, config: T) -> Settings<T>
pub fn create_from_or_empty(file: &File, config: T) -> Settings<T>
Wrapper around load_from
so the return value isn’t an result.
loads a new setting object from a path, or creates an empty object
if file doesn’t exist or errors in any way.
sourcepub fn load(&mut self) -> Result<(), Error>
pub fn load(&mut self) -> Result<(), Error>
Loads Setting
data from the file defined in the configuration.
If nothing exists it throws an error. This shouldn’t
be used for initalizing a new Settings
, look at create
and
create_from
for that.
Will override the existing data of a Setting
sourcepub fn load_from(&mut self, file: &mut File) -> Result<(), Error>
pub fn load_from(&mut self, file: &mut File) -> Result<(), Error>
Loads into the current Setting
from a file.
Will override the existing data of a Setting
sourcepub fn save(&self) -> Result<(), Error>
pub fn save(&self) -> Result<(), Error>
Saves the setting to a file defined in the configuraton.
sourcepub fn get_value(&self, key_path: &str) -> Option<Type>
pub fn get_value(&self, key_path: &str) -> Option<Type>
Get the saved value inside of a Setting
Looks for a key_path
in dot notation and returns an Option
containing the value if it exists.
sourcepub fn get_value_or<A: ?Sized>(&self, key_path: &str, default_value: &A) -> Typewhere
A: SupportedType,
pub fn get_value_or<A: ?Sized>(&self, key_path: &str, default_value: &A) -> Typewhere
A: SupportedType,
Wraps get_value
so instead of an Option
the result will always be a type.
The default value can be any type that implements SupportedType
sourcepub fn set_value<A: ?Sized>(
&mut self,
key_path: &str,
value: &A
) -> Result<(), Error>where
A: SupportedType,
pub fn set_value<A: ?Sized>(
&mut self,
key_path: &str,
value: &A
) -> Result<(), Error>where
A: SupportedType,
sets the value of a key, uses a generic that must implement the SupportedType trait
sourcepub fn delete_key(&mut self, key_path: &str) -> Option<Type>
pub fn delete_key(&mut self, key_path: &str) -> Option<Type>
Deletes the key and returns the current value, returns none if the key didn’t exist.
sourcepub fn delete_file(&self) -> bool
pub fn delete_file(&self) -> bool
Deletes the physical file from the disk
pub fn keys(&self) -> Vec<String>
Trait Implementations
sourceimpl<T> Add<Settings<T>> for Settings<T>where
T: Format + Clone,
impl<T> Add<Settings<T>> for Settings<T>where
T: Format + Clone,
sourcefn add(self, other: Settings<T>) -> Settings<T>
fn add(self, other: Settings<T>) -> Settings<T>
implementing add
so you should be able to use ‘+’ on two settings, useful
because you may want to combine settings from different locations.
Adding to Settings
works by overlaying the two Settings
on top of each
other, if the same “key” has multiple “values”, the “self” is overwritten with
the “other”. So Adding a Settings
means you are overlaying it ontop of the
existing data.
sourceimpl<T> AddAssign<Settings<T>> for Settings<T>where
T: Format + Clone,
impl<T> AddAssign<Settings<T>> for Settings<T>where
T: Format + Clone,
sourcefn add_assign(&mut self, other: Settings<T>)
fn add_assign(&mut self, other: Settings<T>)
AddAssign
follows the same logic as Add
, and allows you to use += with
Settings