Removed comments, made Settings members public, doc

This commit is contained in:
Lucien Cartier-Tilet 2020-03-29 03:09:48 +02:00
parent f3e672e29c
commit d13836e433
Signed by: phundrak
GPG Key ID: BD7789E705CB8DCA

View File

@ -6,7 +6,6 @@ use serde::{Deserialize, Serialize};
extern crate log; extern crate log;
use log::{error, info}; use log::{error, info};
// mod utils;
pub mod utils; pub mod utils;
use utils::SettingsType; use utils::SettingsType;
@ -89,19 +88,45 @@ macro_rules! decode_settings {
}; };
} }
#[derive(Debug, Deserialize, Serialize)] /// Representation of the softwares 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 { 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")] #[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)] #[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)] #[serde(default)]
rules: Vec<(String, String)>, rules: Vec<(String, String)>,
} }
/// Representation inside the crate of LangEvolves settings. /// Representation inside the crate of LangEvolves settings.
impl Settings { impl Settings {
/// Creates a new empty instance of `Settings` /// Creates a new empty instance of [`Settings`]
/// ///
/// # Example /// # Example
/// ///
@ -115,6 +140,8 @@ impl Settings {
/// assert_eq!(content_yaml, serde_yaml::to_string(&s).unwrap()); /// assert_eq!(content_yaml, serde_yaml::to_string(&s).unwrap());
/// assert_eq!(content_json, serde_json::to_string(&s).unwrap()); /// assert_eq!(content_json, serde_json::to_string(&s).unwrap());
/// ``` /// ```
///
/// [`Settings`]: ./settings/struct.Settings.html
pub fn new() -> Self { pub fn new() -> Self {
Self { Self {
version: Self::get_ruleset_version(), version: Self::get_ruleset_version(),
@ -123,12 +150,11 @@ impl Settings {
} }
} }
/// Import settings from an imput file. The currently allowed file formats /// Import settings from an imput file.
/// are: ///
/// - JSON - with the `.json` extension /// The currently allowed file formats are described in the
/// - Yaml - with the `.yaml` or `.yml` extension /// [`utils::SettingsType`] enum. If the ruleset version is higher than the
/// The format will be automatically detected based on the filename /// current version (see [`Settings.version`]), then an error is returned.
/// extension.
/// ///
/// # Arguments /// # Arguments
/// ///
@ -148,6 +174,9 @@ impl Settings {
/// let path_yml = Path::new("settings.yml"); /// let path_yml = Path::new("settings.yml");
/// let _s_yml = Settings::import(&path_yml).unwrap(); /// 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<Self> { pub fn import(path: &std::path::Path) -> std::io::Result<Self> {
use utils::SettingsType::{Json, Yaml}; use utils::SettingsType::{Json, Yaml};
let file_type = utils::get_file_type(&path); 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()); info!("Successfuly imported {}", path.display());
Ok(settings) Ok(settings)
} }
/// Export the current rules to a file. The allowed file formats are either /// Import settings from file path described by the argument `path`
/// a YAML file or a Json file, hence the allowed filename extension are: ///
/// * "yml" or "yaml" for Yaml files /// # Arguments
/// * "json" for Json files ///
/// The format is detected automatically depending on the extension of the /// * `path` - path to the file from which settings should be imported
/// filename. ///
/// # Example
///
/// ```no_run
/// let s = lang_evolve_core::settings::Settings::from("settings.yml");
/// ```
pub fn from<S>(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 /// # Arguments
/// ///
@ -203,6 +256,8 @@ impl Settings {
/// let path_yml = Path::new("./output.yml"); /// let path_yml = Path::new("./output.yml");
/// s.export(&path_yml).unwrap(); /// s.export(&path_yml).unwrap();
/// ``` /// ```
///
/// [`SettingsType`]: ./utils/enum.SettingsType.html
pub fn export(&self, path: &std::path::Path) -> std::io::Result<()> { pub fn export(&self, path: &std::path::Path) -> std::io::Result<()> {
let filetype = utils::get_file_type(&path); let filetype = utils::get_file_type(&path);
let content = match filetype { let content = match filetype {