sparql_results/lib.rs
1#![doc = include_str!("../README.md")]
2
3//! Standalone parsers and serializers for the W3C SPARQL Query
4//! Results interchange formats.
5//!
6//! This crate owns two formats:
7//!
8//! - SPARQL Query Results XML Format (quick-xml).
9//! - SPARQL Query Results JSON Format (`serde_json`).
10//!
11//! The public API is async-first: readers consume Tokio async readers,
12//! sinks are awaited before the next row is read, and serializers write
13//! directly to Tokio async writers. Complete-document materialization is
14//! isolated in the explicit [`bounded`] module.
15
16mod head;
17mod literal;
18mod row;
19mod types;
20
21pub mod bounded;
22
23mod srj;
24mod srx;
25
26pub use head::{
27 HeaderError,
28 ResultHead,
29};
30pub use literal::LiteralError;
31pub use row::RowError;
32pub use srj::{
33 SrjStreamKind,
34 SrjStreamSink,
35 SrjStreamSummary,
36 SrjWriter,
37 parse_srj_streaming,
38};
39pub use srx::{
40 SrxStreamKind,
41 SrxStreamSink,
42 SrxStreamSummary,
43 SrxWriter,
44 canonicalize_srx,
45 parse_srx_streaming,
46};
47pub use types::{
48 BaseDirection,
49 ParseBaseDirectionError,
50 ResultRow,
51 ResultValue,
52};
53
54/// Errors raised while parsing or serializing SPARQL query result
55/// documents in SRX or SRJ form.
56#[derive(Debug, thiserror::Error)]
57pub enum SparqlResultsError {
58 /// The underlying XML reader or writer failed.
59 #[error("XML error: {0}")]
60 Xml(String),
61 /// The underlying JSON reader or writer failed.
62 #[error("JSON error: {0}")]
63 Json(String),
64 /// An element or field was not valid in the current document context.
65 #[error("unexpected element: {0}")]
66 UnexpectedElement(String),
67 /// A required element or field was absent.
68 #[error("missing element: {0}")]
69 MissingElement(String),
70 /// The document structure is internally inconsistent.
71 #[error("invalid document: {0}")]
72 InvalidDocument(String),
73 /// A literal's language tag, datatype, or base direction is invalid
74 /// or contradictory.
75 #[error("invalid literal: {0}")]
76 InvalidLiteral(#[from] LiteralError),
77 /// The result header is invalid, or does not fit the result kind.
78 #[error("invalid header: {0}")]
79 InvalidHeader(#[from] HeaderError),
80 /// A row cannot be written under its header.
81 #[error("invalid row: {0}")]
82 InvalidRow(#[from] RowError),
83}
84
85/// Result type used by all public parser and serializer operations.
86pub type Result<T> = std::result::Result<T, SparqlResultsError>;