Struct Settings

pub struct Settings<T>
where
    T: Format + Clone,
{ /* private fields */ }

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

impl<T> Settings<T>

where T: Format + Clone,

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().

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.

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

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.

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

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

pub fn save(&self) -> Result<(), Error>

Saves the setting to a file defined in the configuraton.

pub fn save_to(&self, file: &File) -> Result<(), Error>

saves the setting to a file buffer.

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.

pub fn get_value_or<A>(&self, key_path: &str, default_value: &A) -> Type

where A: SupportedType + ?Sized,

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

pub fn set_value<A>(&mut self, key_path: &str, value: &A) -> Result<(), Error>

where A: SupportedType + ?Sized,

sets the value of a key, uses a generic that must implement the SupportedType trait

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.

pub fn delete_file(&self) -> bool

Deletes the physical file from the disk

pub fn keys(&self) -> Vec<String>

Trait Implementations

impl<T> Add for Settings<T>

where T: Format + Clone,

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.

type Output = Settings<T>

The resulting type after applying the + operator.

impl<T> AddAssign for Settings<T>

where T: Format + Clone,

fn add_assign(&mut self, other: Settings<T>)

AddAssign follows the same logic as Add, and allows you to use += with Settings

impl<T> Clone for Settings<T>

where T: Format + Clone + Clone,

fn clone(&self) -> Settings<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'de, T> Deserialize<'de> for Settings<T>

where T: Format + Clone + Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Serialize for Settings<T>

where T: Format + Clone + Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.