Trait settingsfile::Format

pub trait Format {
    fn filename(&self) -> String;
    fn folder(&self) -> String;
    fn to_string<T>(&self, object: &T) -> Result<String, Error>
    where
        T: SupportedType + Serialize;
    fn from_str<T>(&self, buffer: &str) -> Result<SettingsRaw, Error>
    where
        T: Format + Clone;

    fn extension(&self) -> Option<String> { ... }
    fn local_filename(&self) -> Option<String> { ... }
    fn local_extension(&self) -> Option<String> { ... }
    fn get_path(&self) -> String { ... }
    fn get_path_and_file(&self) -> String { ... }
    fn get_filename(&self) -> String { ... }
    fn get_local_filename(&self) -> Option<String> { ... }
    fn get_local_path_and_filename(&self) -> String { ... }
}

Trait for defining the physical properties of a Settings

Example Usage

This example uses the ron crate and is taken from the test testing_with_ron

use failure::Error;
use settingsfile::{Format,Settings,SettingsRaw,SupportedType};
 
#[derive(Clone)]
struct BasicConfig { }
 
// implementing the trait here, only doing the required methods
impl Format for BasicConfig {
    fn filename(&self) -> String { "config.ron".to_string() }
    fn folder(&self) -> String { ".config/app".to_string() }
 
    fn from_str<T>(&self,buffer:&str) -> Result<SettingsRaw,Error> 
        where T : Format + Clone 
    {
        let result : Result<SettingsRaw,ron::de::Error> = ron::de::from_str(&buffer);

        match result {
            Ok(result) => Ok(result),
            Err(error) => Err(format_err!("{}",error)),
        }
    }
 
    fn to_string<T:Sized>(&self,object:&T) -> Result<String,Error>
        where T : SupportedType + serde::ser::Serialize, 
    {
        let result : Result<String,ron::ser::Error> = ron::ser::to_string(object);
 
        match result {
            Ok(result) => Ok(result),
            Err(error) => Err(format_err!("{}",error)),
        }
    }
}
 
fn main() {
    let settings = Settings::new(BasicConfig{});
}

Required Methods

fn filename(&self) -> String

Should return the file name of the configuration file:

~/{.application_name}/{file_name}.{extension}

fn filename(&self) -> String {
    "config".to_string()
}

The entire name + extension can be used here as well if you don’t want to use the extension() function.

fn filename(&self) -> String {
    "settings.toml".to_string()
}

fn folder(&self) -> String

Should return the folder name of the configuration file with respect to the %user_directory% environmental variable:

~/{.application_name}/{file_name}.{extension}

The ‘.’ isn’t automatically added, and you would need to include it if desired.

If you want to nest into folders, you can do that too using either ‘/’ or ‘\’. It will be converted and parsed per platform.

~/.config/console_app/config

fn folder(&self) -> String {
    ".config/console_app".to_string()
}

fn to_string<T>(&self, object: &T) -> Result<String, Error>where
    T: SupportedType + Serialize,

Returns the seralized form of the passed in object. Because this uses Serde.rs the object must have the serde::de::Serialize trait, and must also implement the settingsfile::SupportedType trait.

Typically this is just a wrapped passthrough to the serde libray you are using. Example using ron-rs:

fn to_string<T:Sized>(&self,object:&T) -> Result<String,Error>
  where T : settingsfile::SupportedType + serde::ser::Serialize,
{
  match ron::ser::to_string(object) {
    Ok(string) => Ok(string),
    Err(error) => Err(format_err!("{}",error))
  }
}

You can see a working example in the test in the codebase testing_with_ron

fn from_str<T>(&self, buffer: &str) -> Result<SettingsRaw, Error>where
    T: Format + Clone,

The decoding function, will return a deserialized form of a the Settings Rust Struct.

Typically this is a wrapped passthrough to the serde library you are using. Example using ron-rs:

 
fn from_str<T>(&self,buffer:&str) -> Result<settingsfile::SettingsRaw,Error>
  where T : settingsfile::Format + Clone
{
let result : Result<settingsfile::SettingsRaw,ron::de::Error> = ron::de::from_str(&buffer);
  match result {
    Ok(result) => Ok(result),
    Err(error) => Err(format_err!("{}",error)),
  }
}

You can see a working example in the test in the codebase testing_with_ron

Provided Methods

fn extension(&self) -> Option<String>

Option to allow for an extension separate from filename, you can always put the extension in the filename if you perfer.

~/{.application_name}/{file_name}.{extension}

fn extension(&self) -> Option<String> {
    Some("toml".to_string())
}

If not defined then no extension will be used for the file. Settingsfile does not assume a file’s format by its extension so this is just a matter of user preference.

fn local_filename(&self) -> Option<String>

Option to allow for a different filename for a local file. only used with ShadowSetting. Functions the same as filename, does not include an extension.

fn local_extension(&self) -> Option<String>

Option to allow for an extension when using a different local file name. only used with ShadowSetting. Doesn’t do anything if local_filename is None

fn get_path(&self) -> String

Will give the correct path depending on what was implemented in the configuration

fn get_path_and_file(&self) -> String

Will give the correct path including file depending on what was implemented in the configuration

fn get_filename(&self) -> String

Returns the complete file name with or without the extension (if defined)

fn get_local_filename(&self) -> Option<String>

Assembles the local file name, will return None if local_filename is None

fn get_local_path_and_filename(&self) -> String

Returns the path where the local configuration would be.

Implementors

impl Format for EmptyConfig