Skip to main content

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>;