feat: refactor and consistency

rdftk_core/src/error.rs

@@ -9,11 +9,32 @@ use std::fmt::{Debug, Display};
 // Public Types
 // ------------------------------------------------------------------------------------------------
 
+pub trait ErrorSource: std::error::Error {
+    fn as_error_source(&self) -> &(dyn std::error::Error + 'static);
+}
+
 ///
 /// The Error type for this crate.
 ///
 #[derive(Debug)]
 pub enum Error {
+    Tokenizer {
+        representation: String,
+        source: Box<dyn std::error::Error>,
+    },
+    ParserExpected {
+        rule_fn: String,
+        expecting: String,
+    },
+    ParserUnexpected {
+        rule_fn: String,
+        given: String,
+        expecting: Vec<String>,
+    },
+    ParserUnreachable {
+        rule_fn: String,
+        given: String,
+    },
     /// The String value provided is not a valid value for it's type.
     InvalidFromStr {
         value: String,
@@ -40,11 +61,7 @@ pub enum Error {
     AbsoluteIriExpected {
         uri: String,
     },
-    ///A failure occurred reading or writing a graph.
-    ReadWrite {
-        representation: String,
-        source: Option<Box<dyn std::error::Error>>,
-    },
+
     ///Some model element was in an invalid state for the requested operation.
     InvalidState,
     /// Statements as objects, from RDF*, are not supported by this representation.
@@ -161,35 +178,6 @@ where
     Error::AbsoluteIriExpected { uri: uri.into() }
 }
 
-///
-/// Create Error object.
-///
-#[inline(always)]
-pub fn read_write_error<S>(representation: S) -> Error
-where
-    S: Into<String>,
-{
-    Error::ReadWrite {
-        representation: representation.into(),
-        source: None,
-    }
-}
-
-///
-/// Create Error object.
-///
-#[inline(always)]
-pub fn read_write_error_with<S, E>(representation: S, source: E) -> Error
-where
-    S: Into<String>,
-    E: std::error::Error + 'static,
-{
-    Error::ReadWrite {
-        representation: representation.into(),
-        source: Some(Box::new(source)),
-    }
-}
-
 ///
 /// Create Error object.
 ///
@@ -273,6 +261,10 @@ impl Display for Error {
             f,
             "{}",
             match self {
+                Error::Tokenizer { representation, source } => format!("The tokenizer for {representation} generated an error: {source}"),
+                Error::ParserExpected { rule_fn, expecting } => format!("Parser was expecting `{expecting}` in function `{rule_fn}`."),
+                Error::ParserUnexpected { rule_fn, given, expecting } => format!("Parser was not expecting `{given}` in function `{rule_fn}`; expecting {expecting:?}."),
+                Error::ParserUnreachable { rule_fn, given } => format!("Parser should not have reached `{given}` in function `{rule_fn}`."),
                 Error::InvalidFromStr { value, name } => format!(
                     "The String value `{value}` is not a valid value for it's type: '{name}'."
                 ),
@@ -287,11 +279,6 @@ impl Display for Error {
                 Error::InvalidMatch => "The match combination is not valid.".to_string(),
                 Error::AbsoluteIriExpected { uri } =>
                     format!("An Absolute IRI was expected at, not '{uri}'."),
-                Error::ReadWrite { representation, source } =>
-                    format!("A failure occurred reading or writing a graph, for representation: {representation:?}.{}", match source {
-                        Some(source) => format!("Source: {source}"),
-    None => String::default(),
-                    }),
                 Error::InvalidState =>
                     "Some model element was in an invalid state for the requested operation.".to_string(),
                 Error::RdfStarNotSupported { representation } => format!("Statements as objects, from RDF*, are not supported by the {representation:?} representation."),
@@ -311,10 +298,7 @@ impl Display for Error {
 impl std::error::Error for Error {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
         match self {
-            Self::ReadWrite {
-                representation: _,
-                source,
-            } => source.as_ref().map(|e| e.as_ref()),
+            //Self::Tokenizer { source } => Some(source),
             Self::Borrow(source) => Some(source),
             Self::Io(source) => Some(source),
             Self::Iri(source) => Some(source),

rdftk_core/src/model/data_set/mod.rs

@@ -76,6 +76,18 @@ pub trait DataSetFactory: Debug + Provided {
         }
         data_set
     }
+
+    // --------------------------------------------------------------------------------------------
+    // Other Factories
+    // --------------------------------------------------------------------------------------------
+
+    ///
+    /// Return the factory that creates graphs managed by data set's of this kind.
+    ///
+    /// Note that this uses Arc as a reference as factories are explicitly intended for cross-thread
+    /// usage.
+    ///
+    fn graph_factory(&self) -> GraphFactoryRef;
 }
 
 ///
@@ -100,38 +112,45 @@ pub trait DataSet: Debug + Featured {
     ///
     fn len(&self) -> usize;
 
+    fn contains_graph(&self, name: &Option<GraphNameRef>) -> bool;
+
     ///
     /// Return `true` if this data set has a default graph, else `false`.
     ///
     fn has_default_graph(&self) -> bool {
-        self.default_graph().is_some()
+        self.contains_graph(&None)
     }
 
     ///
-    /// Return the default graph for this data set, if it exists.
+    /// Return `true` if this data set has a graph with the provided name, else `false`.
     ///
-    fn default_graph(&self) -> Option<&NamedGraphRef>;
+    fn has_graph_named(&self, name: &GraphNameRef) -> bool {
+        self.contains_graph(&Some(name.clone()))
+    }
 
     ///
-    /// Return `true` if this data set has a graph with the provided name, else `false`.
+    /// Return the default graph for this data set, if it exists.
     ///
-    fn has_graph_named(&self, name: &GraphNameRef) -> bool;
+    fn default_graph(&self) -> Option<&NamedGraphRef> {
+        self.graph(&None)
+    }
 
     ///
     /// Return the graph with the provided name from this data set, if it exists.
     ///
-    fn graph_named(&self, name: &GraphNameRef) -> Option<&NamedGraphRef>;
+    fn graph_named(&self, name: &GraphNameRef) -> Option<&NamedGraphRef> {
+        self.graph(&Some(name.clone()))
+    }
+
+    fn graph(&self, name: &Option<GraphNameRef>) -> Option<&NamedGraphRef>;
+
+    fn graph_mut(&mut self, name: &Option<GraphNameRef>) -> Option<&mut NamedGraphRef>;
 
     ///
     /// Return an iterator over all graphs.
     ///
     fn graphs(&self) -> Box<dyn Iterator<Item = &NamedGraphRef> + '_>;
 
-    ///
-    /// Return an iterator over graph names.
-    ///
-    fn graph_names(&self) -> Box<dyn Iterator<Item = &GraphNameRef> + '_>;
-
     ///
     /// Insert a new graph with it's associated name into the data set.
     ///
@@ -146,13 +165,7 @@ pub trait DataSet: Debug + Featured {
     /// Remove the graph with the provided name from this data set. This operation has no effect if
     /// no such graph is present.
     ///
-    fn remove(&mut self, named: &GraphNameRef);
-
-    ///
-    /// Remove the default graph from this data set. This operation has no effect if no default
-    /// graph is present.
-    ///
-    fn remove_default(&mut self);
+    fn remove(&mut self, named: &Option<GraphNameRef>);
 
     ///
     /// Remove all graphs from this data set.

rdftk_core/src/model/formulae/mod.rs

@@ -39,14 +39,6 @@ pub struct Formula {
 
 pub type FormulaRef = Rc<Formula>;
 
-// ------------------------------------------------------------------------------------------------
-// Private Types
-// ------------------------------------------------------------------------------------------------
-
-// ------------------------------------------------------------------------------------------------
-// Public Functions
-// ------------------------------------------------------------------------------------------------
-
 // ------------------------------------------------------------------------------------------------
 // Implementations
 // ------------------------------------------------------------------------------------------------
@@ -152,11 +144,3 @@ impl Formula {
         self.statements.is_empty()
     }
 }
-
-// ------------------------------------------------------------------------------------------------
-// Private Functions
-// ------------------------------------------------------------------------------------------------
-
-// ------------------------------------------------------------------------------------------------
-// Modules
-// ------------------------------------------------------------------------------------------------

rdftk_core/src/model/graph/mod.rs

@@ -72,6 +72,18 @@ pub trait GraphFactory: Debug + Provided {
         statements: &[StatementRef],
         prefix_mappings: Option<PrefixMappingRef>,
     ) -> NamedGraphRef;
+
+    // --------------------------------------------------------------------------------------------
+    // Other Factories
+    // --------------------------------------------------------------------------------------------
+
+    ///
+    /// Return the factory that creates statements using the same provider as `self`.
+    ///
+    /// Note that this uses Arc as a reference as factories are explicitly intended for cross-thread
+    /// usage.
+    ///
+    fn statement_factory(&self) -> StatementFactoryRef;
 }
 
 ///

rdftk_core/src/model/graph/named.rs

@@ -5,7 +5,7 @@ derived from [RDF 1.1 TriG](https://www.w3.org/TR/trig/), _RDF Dataset Language_
 */
 
 use crate::model::graph::Graph;
-use crate::model::statement::{BlankNode, BlankNodeRef};
+use crate::model::statement::{BlankNode, BlankNodeRef, SubjectNodeRef};
 use rdftk_iri::{Iri, IriRef, Name as NodeName};
 use std::cell::RefCell;
 use std::fmt::{Display, Formatter};
@@ -139,6 +139,18 @@ impl From<&IriRef> for GraphName {
     }
 }
 
+impl From<SubjectNodeRef> for GraphName {
+    fn from(value: SubjectNodeRef) -> Self {
+        if let Some(blank) = value.as_blank() {
+            GraphName(Name::BNode(blank.clone()))
+        } else if let Some(iri) = value.as_iri() {
+            GraphName(Name::Iri(iri.clone()))
+        } else {
+            unreachable!()
+        }
+    }
+}
+
 impl GraphName {
     ///
     /// Construct a new graph name, as a blank node with a randomly assigned name.

rdftk_core/src/model/graph/skolem.rs

@@ -7,7 +7,7 @@ and [Replacing Blank Nodes with IRIs](https://www.w3.org/TR/rdf11-concepts/#sect
 
 use crate::error::{invalid_state_error, Error};
 use crate::model::graph::{Graph, GraphRef};
-use crate::model::statement::{BlankNode, StatementRef};
+use crate::model::statement::{BlankNodeRef, StatementRef};
 use rdftk_iri::{genid, IriRef};
 use std::collections::HashMap;
 use std::rc::Rc;
@@ -22,7 +22,7 @@ use std::rc::Rc;
 /// entirely by a well-known format.
 ///
 pub fn skolemize(graph: &impl Graph, base: &IriRef) -> Result<GraphRef, Error> {
-    let mut mapping: HashMap<BlankNode, IriRef> = Default::default();
+    let mut mapping: HashMap<BlankNodeRef, IriRef> = Default::default();
 
     let factory = graph.factory();
 

rdftk_core/src/model/literal/mod.rs

@@ -147,10 +147,8 @@ impl Equiv<String> for dyn Literal {
 // Modules
 // ------------------------------------------------------------------------------------------------
 
-#[doc(hidden)]
 mod data_type;
 pub use data_type::*;
 
-#[doc(hidden)]
 mod factory;
 pub use factory::*;