diff --git a/src/dvmql/datasources.rs b/src/dvmql/datasources.rs index 370fe55..0ad7a8a 100644 --- a/src/dvmql/datasources.rs +++ b/src/dvmql/datasources.rs @@ -1,12 +1,16 @@ -use std::collections::HashMap; +//! # Datasources +//! +//! This module containts deserialization logic for the datasources XML file. use anyhow::Result; use serde::Deserialize; +use std::collections::HashMap; use super::helpers::read_xml_file; +/// Helper function for loading and deserializing the datasources XML file pub fn load_datasources_xml(datasources_path: String) -> Result> { - let init_datasources: InitDatasources = read_xml_file(datasources_path)?; + let init_datasources: DeserializedDatasources = read_xml_file(datasources_path)?; let res: HashMap = init_datasources .datasource .iter() @@ -25,13 +29,15 @@ pub fn load_datasources_xml(datasources_path: String) -> Result, +struct DeserializedDatasources { + datasource: Vec, } +/// Intermediate representation of a datasource in the deserialized datasources XML file. #[derive(Deserialize, Debug, PartialEq)] -struct InitDatasource { +struct DeserializedDatasource { #[serde(rename = "@type", default)] ds_type: String, id: u8, @@ -48,8 +54,7 @@ struct InitDatasource { database: Option, } -impl InitDatasource {} - +/// Enum representing the different types of datasources. #[derive(Debug, PartialEq)] pub enum Datasource { Csv(Csv), @@ -58,6 +63,7 @@ pub enum Datasource { Database(Database), } +/// CSV datasource (Also used for XML for now) #[derive(Debug, PartialEq)] pub struct Csv { id: u8, @@ -68,8 +74,8 @@ pub struct Csv { headings: String, } -impl From<&InitDatasource> for Csv { - fn from(ds: &InitDatasource) -> Csv { +impl From<&DeserializedDatasource> for Csv { + fn from(ds: &DeserializedDatasource) -> Csv { Csv { id: ds.id, name: ds.name.to_owned(), @@ -93,6 +99,7 @@ impl From<&InitDatasource> for Csv { } } +/// Excel datasource #[derive(Debug, PartialEq)] pub struct Excel { id: u8, @@ -102,8 +109,8 @@ pub struct Excel { sheet: String, headings: String, } -impl From<&InitDatasource> for Excel { - fn from(ds: &InitDatasource) -> Excel { +impl From<&DeserializedDatasource> for Excel { + fn from(ds: &DeserializedDatasource) -> Excel { Excel { id: ds.id, name: ds.name.to_owned(), @@ -127,6 +134,7 @@ impl From<&InitDatasource> for Excel { } } +/// Database datasource #[derive(Debug, PartialEq)] pub struct Database { id: u8, @@ -138,8 +146,8 @@ pub struct Database { database: String, } -impl From<&InitDatasource> for Database { - fn from(ds: &InitDatasource) -> Database { +impl From<&DeserializedDatasource> for Database { + fn from(ds: &DeserializedDatasource) -> Database { Database { id: ds.id, name: ds.name.to_owned(), @@ -173,10 +181,10 @@ mod tests { use super::*; - fn get_init_datasources() -> InitDatasources { - InitDatasources { + fn get_init_datasources() -> DeserializedDatasources { + DeserializedDatasources { datasource: vec![ - InitDatasource { + DeserializedDatasource { ds_type: String::from("csv"), id: 1, name: String::from("myCSV"), @@ -191,7 +199,7 @@ mod tests { password: None, database: None, }, - InitDatasource { + DeserializedDatasource { ds_type: String::from("excel"), id: 2, name: String::from("myExcel"), @@ -206,7 +214,7 @@ mod tests { password: None, database: None, }, - InitDatasource { + DeserializedDatasource { ds_type: String::from("xml"), id: 3, name: String::from("myCSV2"), @@ -221,7 +229,7 @@ mod tests { password: None, database: None, }, - InitDatasource { + DeserializedDatasource { ds_type: String::from("db"), id: 4, name: String::from("sqlDb"), @@ -298,7 +306,7 @@ mod tests { #[test] fn test_loading_initial_datasource_structs() { let path = get_test_file_path(); - let datasources: InitDatasources = read_xml_file(path).unwrap(); + let datasources: DeserializedDatasources = read_xml_file(path).unwrap(); assert_eq!(datasources, get_init_datasources()); } diff --git a/src/dvmql/helpers.rs b/src/dvmql/helpers.rs index 39790ee..7272e5d 100644 --- a/src/dvmql/helpers.rs +++ b/src/dvmql/helpers.rs @@ -1,9 +1,9 @@ -use std::{fs::File, io::BufReader}; - use anyhow::{Context, Result}; use quick_xml::de::from_reader; use serde::de::DeserializeOwned; +use std::{fs::File, io::BufReader}; +/// Helper function for reading an XML file and deserializing it into a struct. pub fn read_xml_file(xml_file_path: String) -> Result { let file = File::open(&xml_file_path) .with_context(|| format!("Failed to open file: {}", &xml_file_path))?; diff --git a/src/dvmql/mod.rs b/src/dvmql/mod.rs index fae8cdc..a8d1fff 100644 --- a/src/dvmql/mod.rs +++ b/src/dvmql/mod.rs @@ -1,3 +1,8 @@ +//! # DVMQL +//! +//! DVMQL is a query language for the DVM. It relies on XML files for +//! defining queries and the data sources to be queried. + pub mod datasources; pub mod query; diff --git a/src/dvmql/query/deserialization.rs b/src/dvmql/query/deserialization.rs index 972cdc6..a21d05a 100644 --- a/src/dvmql/query/deserialization.rs +++ b/src/dvmql/query/deserialization.rs @@ -1,19 +1,19 @@ -use std::str::FromStr; +//! # Query deserialization +//! +//! This module containts deserialization logic for the query XML file. use anyhow::Result; - use serde::de::Deserializer; use serde::Deserialize; +use std::str::FromStr; -use crate::dvmql::helpers::read_xml_file; use crate::transform::aggregate::AggregationType; use crate::transform::Transformation; -pub fn load_query_xml(query_path: String) -> Result { - let query: Query = read_xml_file(query_path)?; - Ok(query) -} - +/// Intermediate representation of the deserialized query XML file. +/// +/// This struct is used to deserialize the XML file into a more +/// usable format. #[derive(Deserialize, Debug, PartialEq)] pub struct Query { #[serde(rename = "rootnode")] @@ -22,6 +22,7 @@ pub struct Query { pub nodes: Vec, } +/// Intermediate representation of a node in the deserialized query XML file. #[derive(Deserialize, Debug, PartialEq)] pub struct DeserializedNode { #[serde(rename = "onnode")] @@ -37,6 +38,7 @@ pub struct DeserializedNode { pub output: bool, } +/// Deserialization helper function for the theta fn deserialize_theta<'de, D>(deserializer: D) -> Result, D::Error> where D: Deserializer<'de>, @@ -48,6 +50,7 @@ where Ok(Some(s)) } +/// Deserialization helper function for nodes' children fn deserialize_children<'de, D>(deserializer: D) -> Result, D::Error> where D: Deserializer<'de>, @@ -59,6 +62,7 @@ where Ok(s.split(',').map(|part| part.trim().to_string()).collect()) } +/// Deserialization helper function for nodes' transformations fn deserialize_transformations<'de, D>(deserializer: D) -> Result, D::Error> where D: Deserializer<'de>, @@ -89,6 +93,7 @@ where Ok(transformations) } +/// Deserialization helper function for nodes' output fn deserialize_output<'de, D>(deserializer: D) -> Result where D: Deserializer<'de>, @@ -145,12 +150,14 @@ mod tests { } } + use crate::dvmql::helpers::read_xml_file; + #[test] fn test_load_query_xml() { let mut path = PathBuf::from(env!("CARGO_MANIFEST_DIR")); path.push("test_data/example_query.xml"); let path = path.to_str().unwrap().to_string(); let expected_query = get_expected_query(); - assert_eq!(load_query_xml(path).unwrap(), expected_query) + assert_eq!(read_xml_file::(path).unwrap(), expected_query) } } diff --git a/src/dvmql/query/mod.rs b/src/dvmql/query/mod.rs index 30f65fe..84d6654 100644 --- a/src/dvmql/query/mod.rs +++ b/src/dvmql/query/mod.rs @@ -1,12 +1,18 @@ +//! # Query +//! +//! This module containts deserialization logic for query XML files. + mod deserialization; pub mod tree; use anyhow::Result; -use self::tree::TreeNode; +use self::{deserialization::Query, tree::TreeNode}; +use crate::dvmql::helpers::read_xml_file; +/// Helper function for loading a query XML file and building the tree structure. pub fn load_query_xml(query_path: String) -> Result { - let query = deserialization::load_query_xml(query_path)?; + let query: Query = read_xml_file(query_path)?; let tree = tree::build_tree(query)?; Ok(tree) } diff --git a/src/dvmql/query/tree.rs b/src/dvmql/query/tree.rs index 1afb1d2..0e15d14 100644 --- a/src/dvmql/query/tree.rs +++ b/src/dvmql/query/tree.rs @@ -1,10 +1,14 @@ +//! # Tree structure produced by DVMQL query +//! +//! This module contains the logic for building the tree structure defined in a DVMQL query. + use anyhow::{Context, Result}; use std::collections::HashMap; use crate::{dvmql::query::deserialization::DeserializedNode, transform::Transformation}; - use super::deserialization::Query; +/// Node of the tree structure defined in a DVMQL query. pub struct TreeNode { pub name: String, pub label: String, @@ -34,6 +38,7 @@ impl TreeNode { } } +/// Helper function for taking a deserialized query and building the tree structure. pub fn build_tree(query: Query) -> Result { let mut deserialized_nodes_map: HashMap = query .nodes @@ -54,6 +59,7 @@ pub fn build_tree(query: Query) -> Result { Ok(root_node) } +/// Helper function for building a node of the tree structure. fn build_node( node: DeserializedNode, nodes_map: &mut HashMap,