From 959605f6a0bf4d7a1b70ef35b4d350ea16a7ef01 Mon Sep 17 00:00:00 2001 From: Matt Burridge <81111055+mburridge96@users.noreply.github.com> Date: Wed, 20 Nov 2024 12:53:37 +0000 Subject: [PATCH] updated doc strings --- src/ro_crate/constraints.rs | 2 - src/ro_crate/contextual_entity.rs | 1 + src/ro_crate/data_entity.rs | 1 + src/ro_crate/graph_vector.rs | 20 +++++--- src/ro_crate/metadata_descriptor.rs | 1 + src/ro_crate/modify.rs | 4 +- src/ro_crate/rocrate.rs | 77 +++++++++++++++++++++++++---- src/ro_crate/root.rs | 3 ++ 8 files changed, 88 insertions(+), 21 deletions(-) diff --git a/src/ro_crate/constraints.rs b/src/ro_crate/constraints.rs index b7aacc3..090abdd 100644 --- a/src/ro_crate/constraints.rs +++ b/src/ro_crate/constraints.rs @@ -7,8 +7,6 @@ use serde::de::{self, MapAccess, SeqAccess, Visitor}; use serde::ser::{SerializeMap, SerializeSeq}; use serde::{Deserialize, Deserializer, Serialize, Serializer}; -use serde_json::from_str; -use serde_json::Error; use std::collections::HashMap; use std::fmt; diff --git a/src/ro_crate/contextual_entity.rs b/src/ro_crate/contextual_entity.rs index 5e43eed..163a6bb 100644 --- a/src/ro_crate/contextual_entity.rs +++ b/src/ro_crate/contextual_entity.rs @@ -47,6 +47,7 @@ impl fmt::Display for ContextualEntity { } impl ContextualEntity { + /// Gets id and value of a specific property pub fn get_property_value(&self, property: &str) -> Option<(String, EntityValue)> { // Check the `type` field if it matches the property. match property { diff --git a/src/ro_crate/data_entity.rs b/src/ro_crate/data_entity.rs index dcf4350..639ee73 100644 --- a/src/ro_crate/data_entity.rs +++ b/src/ro_crate/data_entity.rs @@ -43,6 +43,7 @@ impl DynamicEntityManipulation for DataEntity { } impl DataEntity { + /// Gets ID and value of specific target property pub fn get_property_value(&self, property: &str) -> Option<(String, EntityValue)> { // Check the `type` field if it matches the property. match property { diff --git a/src/ro_crate/graph_vector.rs b/src/ro_crate/graph_vector.rs index 8c837fb..1b3721c 100644 --- a/src/ro_crate/graph_vector.rs +++ b/src/ro_crate/graph_vector.rs @@ -79,7 +79,7 @@ impl GraphVector { } } - /// Get entity + /// Get mutable entity pub fn get_entity_mutable(&mut self, id: &str) -> Option<&mut GraphVector> { match self { GraphVector::MetadataDescriptor(entity) if id == entity.id => Some(self), @@ -89,11 +89,8 @@ impl GraphVector { _ => None, } } - /// Retrieves a list of all entity IDs within the RO-Crate. - /// - /// This method compiles a list of the IDs of all entities contained within the RO-Crate. It is useful - /// for operations that need to process or reference every entity in the crate, such as data validation - /// or integrity checks. + + /// Gets ID of target entity pub fn get_id(&self) -> &String { match self { GraphVector::MetadataDescriptor(entity) => &entity.id, @@ -103,6 +100,7 @@ impl GraphVector { } } + /// Updates the ID of target entity pub fn update_id(&mut self, new_id: String) { match self { GraphVector::MetadataDescriptor(entity) => entity.id = new_id, @@ -112,6 +110,7 @@ impl GraphVector { }; } + /// Searches through entity and updates any IDs that match old with new pub fn update_id_link(&mut self, old_id: &str, new_id: &str) { match self { GraphVector::MetadataDescriptor(entity) => entity.update_matching_id(old_id, new_id), @@ -121,6 +120,7 @@ impl GraphVector { }; } + /// Gets the schema type of the entity pub fn get_type(&self) -> &DataType { match self { GraphVector::MetadataDescriptor(entity) => &entity.type_, @@ -130,6 +130,7 @@ impl GraphVector { } } + /// Adds a type to the entity pub fn add_type(&mut self, new_type: String) { match self { GraphVector::MetadataDescriptor(entity) => entity.type_.add_type(new_type), @@ -139,6 +140,7 @@ impl GraphVector { } } + /// Removes a type from entity if there is a match pub fn remove_type(&mut self, remove_type: String) -> Result { match self { GraphVector::MetadataDescriptor(entity) => entity.type_.remove_type(remove_type), @@ -188,8 +190,8 @@ impl GraphVector { }; } - /// Adds new information to an entity identified by ID. The new info is given as a - /// map (key-value pairs) and is added to the entity's dynamic_entity hashmap. + /// Adds new information or updates already present key in an entity identified by ID. + /// The new info is given as a map (key-value pairs) and is added to the entity's dynamic_entity hashmap. pub fn update_dynamic_entity_field(&mut self, key: String, values: EntityValue) { match self { GraphVector::MetadataDescriptor(descriptor) => { @@ -215,6 +217,7 @@ impl GraphVector { }; } + /// Returns id and value of a specific property within the entity pub fn get_specific_property(&self, property: &str) -> Option<(String, EntityValue)> { match self { GraphVector::MetadataDescriptor(entity) => entity.get_property_value(property), @@ -261,6 +264,7 @@ impl GraphVector { properties } + /// Returns id and property of a specific value within the entity pub fn get_specific_value(&self, value: &str) -> Option<(String, String)> { if let Some(entity_value) = EntityValue::parse(value) { match self { diff --git a/src/ro_crate/metadata_descriptor.rs b/src/ro_crate/metadata_descriptor.rs index ee3555b..262157b 100644 --- a/src/ro_crate/metadata_descriptor.rs +++ b/src/ro_crate/metadata_descriptor.rs @@ -55,6 +55,7 @@ impl DynamicEntityManipulation for MetadataDescriptor { } impl MetadataDescriptor { + /// Gets ID and value of specific property pub fn get_property_value(&self, property: &str) -> Option<(String, EntityValue)> { // Check the `type` field if it matches the property. match property { diff --git a/src/ro_crate/modify.rs b/src/ro_crate/modify.rs index 4830edd..7879787 100644 --- a/src/ro_crate/modify.rs +++ b/src/ro_crate/modify.rs @@ -134,6 +134,7 @@ pub trait DynamicEntityManipulation: Serialize { None } + /// Get all keys containing within a dynamic_entity fn get_all_keys(&self) -> Vec { let mut key_vec: Vec = Vec::new(); @@ -356,6 +357,7 @@ fn remove_matching_value_from_json(value: &mut Value, target_value: &str) { } } +/// Returns key from dynamic_entity pub fn search_dynamic_entity_for_key( dynamic_entity: &HashMap, target_value: &EntityValue, @@ -368,7 +370,7 @@ pub fn search_dynamic_entity_for_key( // If the value is a nested object, search recursively if let EntityValue::EntityObject(inner_object) = value { if let Some(inner_key) = search_dynamic_entity_for_key(inner_object, target_value) { - return Some(format!("{}.{}", key, inner_key)); + return Some(inner_key); } } } diff --git a/src/ro_crate/rocrate.rs b/src/ro_crate/rocrate.rs index cb5193f..9491d48 100644 --- a/src/ro_crate/rocrate.rs +++ b/src/ro_crate/rocrate.rs @@ -62,7 +62,7 @@ pub enum RoCrateContext { /// /// - `EmbeddedContext`: A map containing definitions directly. This is for defining terms right within the crate, making it self-contained. /// -#[derive(Serialize, Deserialize, Debug, Clone)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] #[serde(untagged)] pub enum ContextItem { /// A URI string for referencing external JSON-LD contexts @@ -72,6 +72,62 @@ pub enum ContextItem { EmbeddedContext(HashMap), } +impl RoCrateContext { + /// Adds a new context to the `RoCrateContext`. + pub fn add_context(&mut self, new_context: ContextItem) { + match self { + RoCrateContext::ReferenceContext(current) => { + // Convert to `ExtendedContext` if necessary + *self = RoCrateContext::ExtendedContext(vec![ + ContextItem::ReferenceItem(current.clone()), + new_context, + ]); + } + RoCrateContext::ExtendedContext(contexts) => { + // Add the new item to the extended context + contexts.push(new_context); + } + RoCrateContext::EmbeddedContext(embedded_contexts) => { + // Merge new key-value pairs into the existing embedded context + if let ContextItem::EmbeddedContext(new_map) = new_context { + embedded_contexts.push(new_map); + } + } + } + } + + /// Removes a context item from the `RoCrateContext`. + pub fn remove_context(&mut self, target: &ContextItem) -> Result<(), String> { + match self { + RoCrateContext::ReferenceContext(_) => Err( + "ReferenceContext cannot be removed as the crate requires a context.".to_string(), + ), + RoCrateContext::ExtendedContext(contexts) => { + let initial_len = contexts.len(); + contexts.retain(|item| item != target); + if contexts.len() < initial_len { + Ok(()) + } else { + Err("Context item not found in ExtendedContext.".to_string()) + } + } + RoCrateContext::EmbeddedContext(embedded_contexts) => { + if let ContextItem::EmbeddedContext(target_map) = target { + let initial_len = embedded_contexts.len(); + embedded_contexts.retain(|map| map != target_map); + if embedded_contexts.len() < initial_len { + Ok(()) + } else { + Err("Target map not found in EmbeddedContext.".to_string()) + } + } else { + Err("Invalid target type for EmbeddedContext.".to_string()) + } + } + } + } +} + /// This allows direct manipulation of each node of the GraphVector impl RoCrate { /// Creates a new struct with a given context and empty Graph vec (i.e no entities) @@ -93,20 +149,17 @@ impl RoCrate { match &self.context { RoCrateContext::EmbeddedContext(context) => { for map in context { - for (key, _value) in map { + for key in map.keys() { valid_context.push(key.to_string()); } } } RoCrateContext::ExtendedContext(context) => { for map in context { - match map { - ContextItem::EmbeddedContext(context) => { - for (key, _value) in context { - valid_context.push(key.to_string()); - } + if let ContextItem::EmbeddedContext(context) = map { + for key in context.keys() { + valid_context.push(key.to_string()); } - _ => (), } } } @@ -245,6 +298,7 @@ impl RoCrate { }; } + /// Gets all properties found within RO-Crate pub fn get_all_properties(&self) -> Vec { let mut properties: Vec = Vec::new(); for graph_vector in &self.graph { @@ -256,6 +310,7 @@ impl RoCrate { properties } + /// Gets all the values of a specific property from within the RO-Crate pub fn get_all_property_values(&self, property: &str) -> Vec<(String, EntityValue)> { let mut property_values: Vec<(String, EntityValue)> = Vec::new(); for graph_vector in &self.graph { @@ -267,6 +322,7 @@ impl RoCrate { property_values } + /// Gets ID and Key of the specific value searched pub fn get_specific_value(&self, value: &str) -> Vec<(String, String)> { let mut property_values: Vec<(String, String)> = Vec::new(); for graph_vector in &self.graph { @@ -278,9 +334,8 @@ impl RoCrate { property_values } + /// Overwrites an entity with another entity by ID pub fn overwrite_by_id(&mut self, id: &str, entity: GraphVector) -> bool { - println!("id: {}", id); - println!("Entity: {:?}", entity); if let Some(index) = self.find_entity_index(id) { self.graph[index] = entity; true @@ -289,6 +344,7 @@ impl RoCrate { } } + /// Adds a new key:value pair to a entity based on ID pub fn add_dynamic_entity_property( &mut self, id: &str, @@ -302,6 +358,7 @@ impl RoCrate { } } + /// Removes a key:value pair of an entity based on its ID pub fn remove_dynamic_entity_property(&mut self, id: &str, property: &str) -> bool { if let Some(index) = self.find_entity_index(id) { self.graph[index].remove_dynamic_entity_field(property); diff --git a/src/ro_crate/root.rs b/src/ro_crate/root.rs index fb731b3..1330db7 100644 --- a/src/ro_crate/root.rs +++ b/src/ro_crate/root.rs @@ -55,6 +55,7 @@ impl fmt::Display for RootDataEntity { } } impl RootDataEntity { + /// Adds the ID of an entity to the part of vec of the RootDataEntity pub fn add_entity_to_partof(&mut self, id_target: String) { let dynamic_entity = self.dynamic_entity.get_or_insert_with(HashMap::new); @@ -75,6 +76,8 @@ impl RootDataEntity { } } } + + /// Gets value and id of specific property pub fn get_property_value(&self, property: &str) -> Option<(String, EntityValue)> { // Check the `type` field if it matches the property. match property {