diff --git a/.gitignore b/.gitignore index 8f819b5..e878122 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ Cargo.lock *.log *.yaml *.yml +*.json diff --git a/src/lib.rs b/src/lib.rs index bdde25a..334a3f8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,17 @@ +#![crate_name = "lang_evolve_core"] + +//! # LangEvolveCore +//! +//! `lang_evolve_core` is the core crate used by two other crates: +//! `lang_evolve_cli` and `lang_evolve_gui`. +//! +//! # What it does +//! +//! LangEvolveCore is the crate that hosts all the core logic behind LangEvolve, +//! a conlanging software developped after the +//! [original software](https://github.com/ceronyon/LangEvolve) which applies +//! user-defined sound changes to words and texts based on regex expressions. + use std::fs::File; use std::io::Result; use std::path::PathBuf; @@ -7,13 +21,28 @@ extern crate simplelog; use log::{info, warn}; use simplelog::*; -#[cfg(test)] -mod tests; - pub mod settings; use settings::utils; -#[allow(dead_code)] +/// Initializes the crate +/// +/// # What it does +/// +/// Initializing the crate allows to initialize its logging system. All its logs +/// will be written to the file `core.log` while the errors will also be shown +/// in the terminal. +/// +/// # Return type +/// +/// This function returns a null object if it succeeds. However, if it does not, +/// it will send a `log::SetLoggerError` back. +/// +/// # Example usage +/// +/// Its usage is extremely simple, just call it before you do anything with it: +/// ``` +/// lang_evolve_core::init(); +/// ``` pub fn init() -> std::result::Result<(), log::SetLoggerError> { match CombinedLogger::init(vec![ TermLogger::new( @@ -39,6 +68,7 @@ pub fn init() -> std::result::Result<(), log::SetLoggerError> { } } +/// Import user input from a text file and return them as a String pub fn import_input(path: PathBuf) -> Result { utils::read_file(&path) } diff --git a/src/settings/mod.rs b/src/settings/mod.rs index 66c72dd..b94a164 100644 --- a/src/settings/mod.rs +++ b/src/settings/mod.rs @@ -23,7 +23,22 @@ pub struct Settings { rules: Vec<(String, String)>, } +/// Representation inside the crate of LangEvolve’s settings. impl Settings { + /// Creates a new empty instance of `Settings` + /// + /// # Example + /// + /// ``` + /// let s = lang_evolve_core::settings::Settings::new(); + /// let content_yaml = r#"--- + /// version: "1" + /// categories: [] + /// rules: []"#; + /// let content_json = r#"{"version":"1","categories":[],"rules":[]}"#; + /// assert_eq!(content_yaml, serde_yaml::to_string(&s).unwrap()); + /// assert_eq!(content_json, serde_json::to_string(&s).unwrap()); + /// ``` pub fn new() -> Self { Self { version: Self::get_ruleset_version(), @@ -32,39 +47,31 @@ impl Settings { } } - fn get_ruleset_version() -> String { - String::from(RULESET_CURRENT_VERSION) - } - - pub fn export(&self, path: &std::path::Path) -> std::io::Result<()> { - let filetype = utils::get_file_type(&path).unwrap(); - let content = match filetype { - SettingsType::Yaml => match serde_yaml::to_string(&self) { - Err(e) => { - warn!("Could not serialize settings: {}", e.to_string()); - return Err(std::io::Error::new( - std::io::ErrorKind::InvalidData, - e, - )); - } - Ok(val) => val, - }, - SettingsType::Json => match serde_json::to_string(&self) { - Err(e) => { - warn!("Could not serialize settings: {}", e.to_string()); - return Err(std::io::Error::new( - std::io::ErrorKind::InvalidData, - e, - )); - } - Ok(val) => val, - }, - }; - - utils::write_file(&path, content) - } - - #[allow(dead_code)] + /// 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. + /// + /// # Arguments + /// + /// * `path` - File to open and load settings from + /// + /// # Example + /// + /// ```no_run + /// use std::path::Path; + /// use lang_evolve_core::settings::Settings; + /// let path_json = Path::new("settings.json"); + /// let _s_json = Settings::import(&path_json).unwrap(); + /// + /// let path_yaml = Path::new("settings.yaml"); + /// let _s_yaml = Settings::import(&path_yaml).unwrap(); + /// + /// let path_yml = Path::new("settings.yml"); + /// let _s_yml = Settings::import(&path_yml).unwrap(); + /// ``` pub fn import(path: &std::path::Path) -> std::io::Result { use SettingsType::*; let display = path.display(); @@ -102,6 +109,65 @@ impl Settings { 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. + /// + /// # Arguments + /// + /// * `path` - Path to write and export settings to + /// + /// # Example + /// + /// ``` + /// use std::path::Path; + /// let s = lang_evolve_core::settings::Settings::new(); + /// + /// // Export to JSON + /// let path_json = Path::new("./output.json"); + /// s.export(&path_json).unwrap(); + /// + /// // Export to Yaml, both ".yml" and ".yaml" work + /// let path_yaml = Path::new("./output.yaml"); + /// s.export(&path_yaml).unwrap(); + /// let path_yml = Path::new("./output.yml"); + /// s.export(&path_yml).unwrap(); + /// ``` + pub fn export(&self, path: &std::path::Path) -> std::io::Result<()> { + let filetype = utils::get_file_type(&path).unwrap(); + let content = match filetype { + SettingsType::Yaml => match serde_yaml::to_string(&self) { + Err(e) => { + warn!("Could not serialize settings: {}", e.to_string()); + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidData, + e, + )); + } + Ok(val) => val, + }, + SettingsType::Json => match serde_json::to_string(&self) { + Err(e) => { + warn!("Could not serialize settings: {}", e.to_string()); + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidData, + e, + )); + } + Ok(val) => val, + }, + }; + utils::write_file(&path, &content) + } + + /// Get the current ruleset version of LangEvolve. + fn get_ruleset_version() -> String { + String::from(RULESET_CURRENT_VERSION) + } } impl PartialEq for Settings { @@ -126,3 +192,11 @@ rules: []"#; assert_eq!(settings, utils::read_file(&path).unwrap()); } +#[test] +fn read_settings() { + let s1 = Settings::new(); + let path = std::path::Path::new("test.yml"); + s1.export(&path).unwrap(); + let s2 = Settings::import(&path).unwrap(); + assert_eq!(s1, s2); +} diff --git a/src/settings/utils.rs b/src/settings/utils.rs index d22460c..e0aeda0 100644 --- a/src/settings/utils.rs +++ b/src/settings/utils.rs @@ -5,11 +5,23 @@ use std::fs::File; use std::io::{Read, Result}; use std::path::Path; +/// Type of supported settings format: yaml or json pub enum SettingsType { + /// Files ending with the `yml` or `yaml` extension Yaml, + + /// Files ending with the `json` extension Json, } +/// Read a file’s content into a `String` +/// +/// # Example +/// +/// ```no_run +/// let path = std::path::Path::new("./some/path/to/my/file.json"); +/// let content = lang_evolve_core::settings::utils::read_file(&path).unwrap(); +/// ``` pub fn read_file(path: &Path) -> Result { let display = path.display(); let mut file = match File::open(&path) { @@ -33,6 +45,15 @@ pub fn read_file(path: &Path) -> Result { } pub fn write_file(path: &Path, content: String) -> Result<()> { +/// Write a `String` into a file +/// +/// # Example +/// +/// ```no_run +/// let content = String::from("This is my content"); +/// let path = std::path::Path::new("./path/to/my/file.txt"); +/// lang_evolve_core::settings::utils::write_file(&path, &content).unwrap(); +/// ``` use std::io::prelude::*; let mut file = match File::create(&path) { Err(e) => { diff --git a/src/tests.rs b/src/tests.rs deleted file mode 100644 index 2837a57..0000000 --- a/src/tests.rs +++ /dev/null @@ -1,4 +0,0 @@ -#[test] -fn it_works() { - assert_eq!(2 + 2, 4); -}