oxiland 0.8.0

Embedded RDF datasets, SPARQL, persistence, and streaming I/O for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

//! Embedded RDF datasets, SPARQL, persistence, and streaming I/O for Rust.
//!
//! Oxiland provides a safe application facade powered by Oxigraph. RDF term
//! types are re-exported so callers can move data into and out of the broader
//! Oxigraph ecosystem without adapters. Redland workflow mappings are retained
//! as an evidence-scoped migration surface without copying manual-memory
//! ownership rules into Rust (ADR-004).
//!
//! # Module layout (1.0 naming freeze intent — ADR-020)
//!
//! Stable public modules: [`terms`], [`io`], [`storage`], [`utility`], plus root
//! re-exports such as [`Model`], [`World`], [`Query`], [`Update`], and [`Error`].
//! Breaking renames after 0.6 require an ADR and CHANGELOG entry.
//!
//! # Quick start
//!
//! ```
//! use oxiland::terms::{self, Literal, Triple};
//! use oxiland::{Model, Query, QueryResults};
//!
//! # fn main() -> oxiland::Result<()> {
//! let model = Model::new()?;
//! model.add(Triple::new(
//!     terms::named_node("https://example.com/alice")?,
//!     terms::named_node("https://example.com/name")?,
//!     Literal::new_simple_literal("Alice"),
//! ))?;
//!
//! assert!(matches!(
//!     Query::new("ASK { ?s ?p ?o }").execute(&model)?,
//!     QueryResults::Boolean(true)
//! ));
//! # Ok(())
//! # }
//! ```

#![forbid(unsafe_code)]
#![warn(missing_docs)]

mod error;
pub mod io;
mod model;
mod query;
pub mod storage;
pub mod utility;
mod world;

pub use error::{Error, ParseError, Result};
pub use model::{Model, ModelTransaction, StatementMatches, StatementPattern};
pub use query::{
    Query, QueryResults, ResultsFormat, Update, serialize_graph_results_to_writer,
    serialize_query_results_to_string, serialize_query_results_to_writer,
};
pub use storage::{
    OpenOptions, StorageBackend, StorageCapabilities, compiled_backends, is_known_backend_name,
};
pub use world::{FeatureValue, LogFacility, LogLevel, LogRecord, World};

/// RDF term, triple, quad, and graph-name types used by Oxiland.
///
/// These are direct re-exports of Oxigraph types (ADR-004). Prefer the helpers
/// below when you want Oxiland [`Error`] categories instead of Oxigraph errors.
pub mod terms {
    pub use oxigraph::model::{
        BlankNode, GraphName, GraphNameRef, Literal, NamedNode, NamedNodeRef, NamedOrBlankNode,
        NamedOrBlankNodeRef, Quad, QuadRef, Term, TermRef, Triple, TripleRef, Variable,
    };

    use crate::{Error, Result};

    /// Creates a [`NamedNode`], mapping IRI failures to [`Error::InvalidRdf`].
    pub fn named_node(iri: impl AsRef<str>) -> Result<NamedNode> {
        NamedNode::new(iri.as_ref()).map_err(|error| Error::InvalidRdf(error.to_string()))
    }

    /// Creates a [`BlankNode`] from an optional identifier.
    ///
    /// When `id` is `None`, Oxigraph allocates a fresh blank node. Invalid
    /// identifiers map to [`Error::InvalidRdf`].
    pub fn blank_node(id: Option<&str>) -> Result<BlankNode> {
        match id {
            Some(id) => BlankNode::new(id).map_err(|error| Error::InvalidRdf(error.to_string())),
            None => Ok(BlankNode::default()),
        }
    }
}

/// Oxigraph SPARQL primitives for advanced use cases.
///
/// Prefer [`Query`], [`Update`], and [`ResultsFormat`] for the documented
/// Oxiland API. This module is an engine escape hatch, not the compatibility
/// or stability surface.
pub mod sparql {
    pub use oxigraph::sparql::results::{QueryResultsFormat, QueryResultsSerializer};
    pub use oxigraph::sparql::{
        CancellationToken, QueryResults, QuerySolution, QuerySolutionIter, QueryTripleIter,
        SparqlEvaluator,
    };
}