sophia_api/
serializer.rs

1//! API for serializing RDF syntaxes.
2//!
3//! This module specifies, through dedicated traits,
4//! how serialization of triples/graphs and quads/dataset is handled in sophia.
5//! These traits are designed with the idea that each serializer has a specific
6//! “target” (typically a file or something similar)
7//! associated to it.
8//! If you want to serialize to two different files,
9//! you must create two different serializers.
10//!
11//! Note however that this API does not cover the creation of serializers,
12//! and therefore does not cover how their target is specified.
13
14use crate::dataset::*;
15use crate::graph::*;
16use crate::source::*;
17
18/// A triple serializer writes triples according to a given format.
19pub trait TripleSerializer {
20    /// The error type that may be raised during serialization.
21    type Error: 'static + std::error::Error;
22
23    /// Serialize all triples from the given [`TripleSource`].
24    fn serialize_triples<TS>(
25        &mut self,
26        source: TS,
27    ) -> StreamResult<&mut Self, TS::Error, Self::Error>
28    where
29        TS: TripleSource,
30        Self: Sized;
31
32    /// Serialize a whole [`Graph`].
33    ///
34    /// While this method has a default implementation based on
35    /// [`serialize_triples`](Self::serialize_triples),
36    /// some implementations may override it in order to better use the structure of the Graph.
37    #[inline]
38    fn serialize_graph<G>(&mut self, graph: &G) -> StreamResult<&mut Self, G::Error, Self::Error>
39    where
40        G: Graph,
41        Self: Sized,
42    {
43        self.serialize_triples(&mut graph.triples())
44    }
45}
46
47/// A quad serializer writes quads according to a given format.
48pub trait QuadSerializer {
49    /// The error type that may be raised during serialization.
50    type Error: 'static + std::error::Error;
51
52    /// Serialize all quads from the given [`QuadSource`].
53    fn serialize_quads<QS>(
54        &mut self,
55        source: QS,
56    ) -> StreamResult<&mut Self, QS::Error, Self::Error>
57    where
58        QS: QuadSource,
59        Self: Sized;
60
61    /// Serialize a whole [`Dataset`].
62    ///
63    /// While this method has a default implementation based on
64    /// [`serialize_quads`](Self::serialize_quads),
65    /// some implementations may override it in order to better use the structure of the Dataset.
66    #[inline]
67    fn serialize_dataset<D>(
68        &mut self,
69        dataset: &D,
70    ) -> StreamResult<&mut Self, D::Error, Self::Error>
71    where
72        D: Dataset,
73        Self: Sized,
74    {
75        self.serialize_quads(&mut dataset.quads())
76    }
77}
78
79/// A stringifier is special kind of [`TripleSerializer`] or [`QuadSerializer`]:
80///
81/// + it uses a text-based format encoded in UTF8;
82/// + it stores the serialize data in memory;
83/// + it gives access to the serialized data as `str` or `String`.
84///
85/// [`TripleSerializer`]: trait.TripleSerializer.html
86/// [`QuadSerializer`]: trait.QuadSerializer.html
87pub trait Stringifier {
88    /// Borrows the internal serialized data.
89    ///
90    /// # Note to implementers
91    /// It is the responsibility of implementors to ensure that this data is valid UTF8.
92    /// The methods [`as_str`](#method.as_str) and
93    /// [`to_string`](#method.to_string) rely on this.
94    fn as_utf8(&self) -> &[u8];
95
96    /// Borrows the internal serialized data as a `str`.
97    fn as_str(&self) -> &str {
98        unsafe { std::str::from_utf8_unchecked(self.as_utf8()) }
99    }
100
101    /// Copy the internal serialized data to a `String`.
102    fn to_string(&self) -> String {
103        self.as_str().to_string()
104    }
105}
sophia_api/serializer.rs

sophia_api/
serializer.rs
