Skip to main content

n_quads/
lib.rs

1//! N-Quads parsing.
2//!
3//! N-Quads is a line-based, plain text format for encoding an RDF dataset.
4//! This library provides a [W3C Recommendation](https://www.w3.org/TR/n-quads/)
5//! compliant parser built on [`rdfx`] terms. Parsing also returns a
6//! [`CodeMap`] recording the source span of every quad *and* of each of its
7//! components, so a downstream validation error can be reported against the
8//! exact byte range that caused it.
9//!
10//! Both the standard grammar and the generalized (gRDF) grammar are supported.
11//! gRDF lifts the restrictions on which term kinds may appear where: any term
12//! may be a subject, predicate, object or graph label.
13//!
14//! # RDF version
15//!
16//! The grammar implemented here is the RDF 1.1 one. [`rdfx`] models RDF 1.2,
17//! so its term types can represent triple terms and directional language
18//! strings, but this parser never produces them — the three RDF 1.2 syntax
19//! additions are rejected:
20//!
21//! | Syntax | Example | Status |
22//! | ------ | ------- | ------ |
23//! | Triple terms | `<<( :a :b :c )>>` | rejected |
24//! | Directional language strings | `"x"@en--ltr` | rejected |
25//! | Reifiers | `:s :p "x" ~ :r` | rejected |
26//!
27//! # Usage
28//!
29//! ```
30//! let source = r#"<http://example.com/#a> <http://example.com/#b> "value"@en ."#;
31//!
32//! let (document, code_map) = n_quads::document_from_str(source)?;
33//! assert_eq!(document.len(), 1);
34//!
35//! // Span of the whole quad, then of its subject, predicate and object.
36//! let (quad_span, components) = code_map[0];
37//! assert_eq!(&source[quad_span.range()], source);
38//! assert_eq!(&source[components.0.range()], "<http://example.com/#a>");
39//! assert_eq!(&source[components.2.range()], r#""value"@en"#);
40//! # Ok::<_, n_quads::Error>(())
41//! ```
42//!
43//! For the generalized grammar, use [`grdf_document_from_str`]. For input that
44//! is not already a `&str` — a fallible byte stream, UTF-16, a custom decoder
45//! — use the [`Parse`] trait directly.
46#![warn(missing_docs)]
47
48pub mod lexing;
49mod parsing;
50
51pub use lexing::LexingError;
52pub use parsing::*;
53pub use rdfx::BlankIdBuf;
54use rdfx::{GeneralizedQuad, LexicalQuad};
55
56/// N-Quads document.
57///
58/// A document is just the list of its quads, in source order.
59pub type Document = Vec<LexicalQuad>;
60
61/// gRDF N-Quads document.
62///
63/// Like [`Document`], but parsed with the generalized grammar, where any term
64/// may occupy any position of the quad.
65pub type GrdfDocument = Vec<GeneralizedQuad>;
66
67/// Parses an N-Quads document from a string.
68///
69/// Returns the quads along with the [`CodeMap`] describing where each one came
70/// from.
71pub fn document_from_str(string: &str) -> Result<(Document, CodeMap), parsing::Error> {
72	Document::parse_str(string)
73}
74
75/// Parses a generalized (gRDF) N-Quads document from a string.
76///
77/// Returns the quads along with the [`CodeMap`] describing where each one came
78/// from.
79pub fn grdf_document_from_str(string: &str) -> Result<(GrdfDocument, CodeMap), parsing::Error> {
80	GrdfDocument::parse_str(string)
81}