diff --git a/Cargo.toml b/Cargo.toml index 1d17d5b0..d1a3fc1d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,10 +4,10 @@ version = "0.0.1" authors = ["Tpt "] license = "MIT/Apache-2.0" readme = "../README.md" -keywords = ["RDF"] +keywords = ["RDF", "N-Triples", "Turtle", "RDF/XML", "SPARQL"] repository = "https://github.com/Tpt/rudf" description = """ -An RDF library in Rust +An RDF and SPARQL library in Rust """ build = "build.rs" diff --git a/src/model/dataset.rs b/src/model/dataset.rs index 88ebe6e9..94394be6 100644 --- a/src/model/dataset.rs +++ b/src/model/dataset.rs @@ -4,6 +4,22 @@ use std::io::Read; use Result; /// Trait for [RDF graphs](https://www.w3.org/TR/rdf11-concepts/#dfn-graph) +/// +/// This crate currently provides a simple stand-alone in memory implementation of the `Graph` trait. +/// +/// Usage example: +/// ``` +/// use rudf::model::*; +/// use rudf::store::MemoryGraph; +/// use std::str::FromStr; +/// +/// let graph = MemoryGraph::default(); +/// let ex = NamedNode::from_str("http://example.com").unwrap(); +/// let triple = Triple::new(ex.clone(), ex.clone(), ex.clone()); +/// graph.insert(&triple); +/// let results: Vec = graph.triples_for_subject(&ex.into()).unwrap().map(|t| t.unwrap()).collect(); +/// assert_eq!(vec![triple], results); +/// ``` pub trait Graph { type TriplesIterator: Iterator>; type TriplesForSubjectIterator: Iterator>; @@ -13,10 +29,12 @@ pub trait Graph { type SubjectsForPredicateObjectIterator: Iterator>; type TriplesForObjectIterator: Iterator>; + /// Returns all triples contained by the graph fn iter(&self) -> Result { self.triples() } + /// Returns all triples contained by the graph fn triples(&self) -> Result; fn triples_for_subject( @@ -64,14 +82,19 @@ pub trait Graph { fn triples_for_object(&self, object: &Term) -> Result; + /// Checks if the graph contains the given triple fn contains(&self, triple: &Triple) -> Result; + /// Adds a triple to the graph fn insert(&self, triple: &Triple) -> Result<()>; + /// Removes a concrete triple from the graph fn remove(&self, triple: &Triple) -> Result<()>; + /// Returns the number of triples in this graph fn len(&self) -> Result; + /// Checks if this graph contains a triple fn is_empty(&self) -> Result; } @@ -81,6 +104,31 @@ pub trait NamedGraph: Graph { } /// Trait for [RDF datasets](https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset) +/// +/// This crate currently provides two implementation of the `Dataset` traits: +/// * One in memory: `rudf::store::MemoryDataset` +/// * One disk-based using [RocksDB](https://rocksdb.org/): `rudf::store::RocksDbDataset` +/// +/// Usage example with `rudf::store::MemoryDataset`: +/// ``` +/// use rudf::model::*; +/// use rudf::store::MemoryDataset; +/// use std::str::FromStr; +/// +/// let dataset = MemoryDataset::default(); +/// let default_graph = dataset.default_graph(); +/// let ex = NamedNode::from_str("http://example.com").unwrap(); +/// let triple = Triple::new(ex.clone(), ex.clone(), ex.clone()); +/// default_graph.insert(&triple); +/// let results: Vec = dataset.quads_for_subject(&ex.into()).unwrap().map(|t| t.unwrap()).collect(); +/// assert_eq!(vec![triple.in_graph(None)], results); +/// ``` +/// +/// The implementation backed by RocksDB could be built using `RocksDbDataset::open` and works just like its in-memory equivalent: +/// ``` +/// use rudf::store::RocksDbDataset; +/// let dataset = RocksDbDataset::open("foo.db"); +/// ``` pub trait Dataset { type NamedGraph: NamedGraph; type DefaultGraph: Graph; @@ -94,16 +142,23 @@ pub trait Dataset { type QuadsForPredicateObjectIterator: Iterator>; type QuadsForObjectIterator: Iterator>; + /// Returns an object for a [named graph](https://www.w3.org/TR/rdf11-concepts/#dfn-named-graph) of this dataset. + /// + /// This named graph may be empty if no triple is in the graph yet. fn named_graph(&self, name: &NamedOrBlankNode) -> Result; + /// Returns an object for the [default graph](https://www.w3.org/TR/rdf11-concepts/#dfn-default-graph) of this dataset fn default_graph(&self) -> Self::DefaultGraph; + /// Returns a graph that is the union of all graphs contained in this dataset, including the default graph fn union_graph(&self) -> Self::UnionGraph; + /// Returns all quads contained by the graph fn iter(&self) -> Result { self.quads() } + /// Returns all quads contained by the graph fn quads(&self) -> Result; fn quads_for_subject( @@ -141,14 +196,19 @@ pub trait Dataset { fn quads_for_object(&self, object: &Term) -> Result; + /// Checks if this dataset contains a given quad fn contains(&self, quad: &Quad) -> Result; + /// Adds a quad to this dataset fn insert(&self, quad: &Quad) -> Result<()>; + /// Removes a quad from this dataset fn remove(&self, quad: &Quad) -> Result<()>; + /// Returns the number of quads in this dataset fn len(&self) -> Result; + /// Checks if this dataset contains a quad fn is_empty(&self) -> Result; fn query(&self, query: impl Read) -> Result; diff --git a/src/model/mod.rs b/src/model/mod.rs index ff35f855..d30d5c9a 100644 --- a/src/model/mod.rs +++ b/src/model/mod.rs @@ -1,4 +1,5 @@ -//! Implements data structures for [RDF 1.1 Concepts](https://www.w3.org/TR/rdf11-concepts/) +//! Implements data structures for [RDF 1.1 Concepts](https://www.w3.org/TR/rdf11-concepts/). +//! //! Inspired by [RDFjs](http://rdf.js.org/) and [Apache Commons RDF](http://commons.apache.org/proper/commons-rdf/) mod blank_node; diff --git a/src/rio/mod.rs b/src/rio/mod.rs index c0b89c9f..f06a626e 100644 --- a/src/rio/mod.rs +++ b/src/rio/mod.rs @@ -1,3 +1,5 @@ +//! Implementations of serializers and deserializers for usual RDF syntaxes + pub mod ntriples; pub mod turtle; pub(crate) mod utils; diff --git a/src/rio/ntriples/mod.rs b/src/rio/ntriples/mod.rs index c122768f..bcd7c050 100644 --- a/src/rio/ntriples/mod.rs +++ b/src/rio/ntriples/mod.rs @@ -67,6 +67,7 @@ impl Iterator for NTriplesIterator { } } +/// Reads a N-Triples file from a Rust `Read` and returns an iterator on the read `Triple`s pub fn read_ntriples<'a, R: Read + 'a>(source: R) -> impl Iterator> { NTriplesIterator { buffer: String::default(), diff --git a/src/rio/turtle/mod.rs b/src/rio/turtle/mod.rs index a126e622..ee39365e 100644 --- a/src/rio/turtle/mod.rs +++ b/src/rio/turtle/mod.rs @@ -37,6 +37,9 @@ mod grammar { } } + /// Reads a Turtle file from a Rust `Read` and returns an iterator on the read `Triple`s + /// + /// Warning: this implementation has not been optimized yet and stores all the found triples in memory pub fn read_turtle<'a, R: Read + 'a>( source: R, base_uri: impl Into>, diff --git a/src/rio/xml.rs b/src/rio/xml.rs index f8d8c032..5af4c2de 100644 --- a/src/rio/xml.rs +++ b/src/rio/xml.rs @@ -12,6 +12,7 @@ use std::str::FromStr; use url::Url; use Result; +/// Reads a RDF/XML file from a Rust `Read` and returns an iterator on the read `Triple`s pub fn read_rdf_xml( source: impl BufRead, base_uri: impl Into>, diff --git a/src/store/memory.rs b/src/store/memory.rs index 08f3b2b2..d0daed62 100644 --- a/src/store/memory.rs +++ b/src/store/memory.rs @@ -5,7 +5,41 @@ use store::numeric_encoder::*; use store::store::*; use Result; +/// Memory based implementation of the `rudf::model::Dataset` trait. +/// They are cheap to build using the `MemoryDataset::default()` method. +/// +/// Usage example: +/// ``` +/// use rudf::model::*; +/// use rudf::store::MemoryDataset; +/// use std::str::FromStr; +/// +/// let dataset = MemoryDataset::default(); +/// let default_graph = dataset.default_graph(); +/// let ex = NamedNode::from_str("http://example.com").unwrap(); +/// let triple = Triple::new(ex.clone(), ex.clone(), ex.clone()); +/// default_graph.insert(&triple); +/// let results: Vec = dataset.quads_for_subject(&ex.into()).unwrap().map(|t| t.unwrap()).collect(); +/// assert_eq!(vec![triple.in_graph(None)], results); +/// ``` pub type MemoryDataset = StoreDataset; + +/// Memory based implementation of the `rudf::model::Graph` trait. +/// They are cheap to build using the `MemoryGraph::default()` method. +/// +/// Usage example: +/// ``` +/// use rudf::model::*; +/// use rudf::store::MemoryGraph; +/// use std::str::FromStr; +/// +/// let graph = MemoryGraph::default(); +/// let ex = NamedNode::from_str("http://example.com").unwrap(); +/// let triple = Triple::new(ex.clone(), ex.clone(), ex.clone()); +/// graph.insert(&triple); +/// let results: Vec = graph.triples_for_subject(&ex.into()).unwrap().map(|t| t.unwrap()).collect(); +/// assert_eq!(vec![triple], results); +/// ``` pub type MemoryGraph = StoreDefaultGraph; #[derive(Default)] diff --git a/src/store/mod.rs b/src/store/mod.rs index 25d932e5..ca46941e 100644 --- a/src/store/mod.rs +++ b/src/store/mod.rs @@ -1,3 +1,5 @@ +//! Provides implementations of the `rudf::model::Graph` and `rudf::model::Dataset` traits. + pub mod isomorphism; mod memory; mod numeric_encoder; diff --git a/src/store/rocksdb.rs b/src/store/rocksdb.rs index f597e2a3..4086eaee 100644 --- a/src/store/rocksdb.rs +++ b/src/store/rocksdb.rs @@ -15,6 +15,13 @@ use store::store::EncodedQuadsStore; use store::store::StoreDataset; use Result; +/// `rudf::model::Dataset` trait implementation based on the [RocksDB](https://rocksdb.org/) key-value store +/// +/// Usage example: +/// ``` +/// use rudf::store::RocksDbDataset; +/// let dataset = RocksDbDataset::open("example.db").unwrap(); +/// ``` pub type RocksDbDataset = StoreDataset; impl RocksDbDataset {