diff --git a/src/settings/mod.rs b/src/settings/mod.rs index 7846c63..b2a74ff 100644 --- a/src/settings/mod.rs +++ b/src/settings/mod.rs @@ -6,7 +6,6 @@ use serde::{Deserialize, Serialize}; extern crate log; use log::{error, info}; -// mod utils; pub mod utils; use utils::SettingsType; @@ -89,19 +88,45 @@ macro_rules! decode_settings { }; } -#[derive(Debug, Deserialize, Serialize)] +/// Representation of the software’s settings +/// +/// This struct represents all the settings the software has to follow +/// while running, which includes the phoneme categories as well as +/// the soundchange rules to apply to the input text. +#[derive(Clone, Debug, Deserialize, Serialize)] pub struct Settings { + /// Represents the version of the loaded ruleset. + /// + /// It is used to detect obsolete ruleset representations or if a + /// loaded ruleset comes from a newer version of lang_evolve_core + /// than the one used by the user. #[serde(default = "Settings::get_ruleset_version")] - version: String, + pub version: String, + + /// Categories of phonemes + /// + /// This is a vector of categories of phonemes, represented + /// themselves as pairs of strings. Each pair of strings has its + /// first element represent the name of the category, which is + /// generally represented by a single capital letter. The second + /// element is a string where all its characters represent + /// phonemes. It is currently not possible to have more than one + /// character to be considered as one sound. #[serde(default)] - categories: Vec<(String, String)>, + pub categories: Vec<(String, String)>, + + /// Soundchange rules + /// + /// This is a vector of pairs of strings, the first one represents + /// a regex to be matched while the second represents the change + /// to be made to the input data. #[serde(default)] rules: Vec<(String, String)>, } /// Representation inside the crate of LangEvolve’s settings. impl Settings { - /// Creates a new empty instance of `Settings` + /// Creates a new empty instance of [`Settings`] /// /// # Example /// @@ -115,6 +140,8 @@ impl Settings { /// assert_eq!(content_yaml, serde_yaml::to_string(&s).unwrap()); /// assert_eq!(content_json, serde_json::to_string(&s).unwrap()); /// ``` + /// + /// [`Settings`]: ./settings/struct.Settings.html pub fn new() -> Self { Self { version: Self::get_ruleset_version(), @@ -123,12 +150,11 @@ impl Settings { } } - /// Import settings from an imput file. The currently allowed file formats - /// are: - /// - JSON - with the `.json` extension - /// - Yaml - with the `.yaml` or `.yml` extension - /// The format will be automatically detected based on the filename - /// extension. + /// Import settings from an imput file. + /// + /// The currently allowed file formats are described in the + /// [`utils::SettingsType`] enum. If the ruleset version is higher than the + /// current version (see [`Settings.version`]), then an error is returned. /// /// # Arguments /// @@ -148,6 +174,9 @@ impl Settings { /// let path_yml = Path::new("settings.yml"); /// let _s_yml = Settings::import(&path_yml).unwrap(); /// ``` + /// + /// [`utils::SettingsTYpe`]: ./utils/enum.SettingsType.html + /// [`Settings.version`]: ./struct.Settings.html#structfield.version pub fn import(path: &std::path::Path) -> std::io::Result { use utils::SettingsType::{Json, Yaml}; let file_type = utils::get_file_type(&path); @@ -172,16 +201,40 @@ impl Settings { } }, }; + if settings.version > Self::get_ruleset_version() { + error!("Ruleset version too high!"); + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidData, + "Ruleset version too high!", + )); + } info!("Successfuly imported {}", path.display()); Ok(settings) } - /// Export the current rules to a file. The allowed file formats are either - /// a YAML file or a Json file, hence the allowed filename extension are: - /// * "yml" or "yaml" for Yaml files - /// * "json" for Json files - /// The format is detected automatically depending on the extension of the - /// filename. + /// Import settings from file path described by the argument `path` + /// + /// # Arguments + /// + /// * `path` - path to the file from which settings should be imported + /// + /// # Example + /// + /// ```no_run + /// let s = lang_evolve_core::settings::Settings::from("settings.yml"); + /// ``` + pub fn from(s: S) -> Self + where + S: ToString, + { + let s = s.to_string(); + let path = std::path::Path::new(&s); + Self::import(&path).unwrap() + } + + /// Export current settings to a file. + /// + /// The allowed file formats are described in the [`SettingsType`] enum. /// /// # Arguments /// @@ -203,6 +256,8 @@ impl Settings { /// let path_yml = Path::new("./output.yml"); /// s.export(&path_yml).unwrap(); /// ``` + /// + /// [`SettingsType`]: ./utils/enum.SettingsType.html pub fn export(&self, path: &std::path::Path) -> std::io::Result<()> { let filetype = utils::get_file_type(&path); let content = match filetype {