Skip to main content

qualia_core_db/sparql_library/parsers/
nquads_star.rs

1use crate::lexicon::{generate_60bit_token, generate_embedded_triple_id};
2use crate::rdf_star::{RdfStarParseError, RdfStarParser};
3/// N-Quads-Star Parser for QualiaDB
4///
5/// Implements RDF-Star (SPARQL 1.2) parsing for N-Quads syntax with embedded triples.
6/// N-Quads-Star extends N-Triples-Star with a fourth component (graph/context).
7/// Format: `<subject> <predicate> <object> <graph> .`
8use crate::NQuin;
9
10/// Human-readable term strings from the most recent successful parse.
11#[derive(Debug, Clone, Default)]
12pub struct NQuadsLineTerms {
13    pub subject: String,
14    pub predicate: String,
15    pub object: String,
16    pub graph: String,
17    pub outer_predicate: String,
18    pub outer_object: String,
19    pub outer_graph: String,
20}
21
22/// N-Quads-Star parser implementation
23pub struct NQuadsStarParser {
24    /// Context hash for the current parsing session
25    context_hash: u64,
26    last_terms: Option<NQuadsLineTerms>,
27}
28
29impl NQuadsStarParser {
30    /// Create a new N-Quads-Star parser
31    pub fn new(context_hash: u64) -> Self {
32        Self {
33            context_hash,
34            last_terms: None,
35        }
36    }
37
38    /// Session default graph hash (used when a line omits an explicit graph).
39    pub fn session_context(&self) -> u64 {
40        self.context_hash
41    }
42
43    /// Term strings from the last successfully parsed line.
44    pub fn last_line_terms(&self) -> Option<&NQuadsLineTerms> {
45        self.last_terms.as_ref()
46    }
47
48    fn graph_hash_from_token(&self, graph: &str) -> u64 {
49        if graph.is_empty() {
50            self.context_hash
51        } else {
52            generate_60bit_token(graph.as_bytes())
53        }
54    }
55
56    fn store_regular_terms(
57        &mut self,
58        subject_str: &str,
59        predicate_str: &str,
60        object_str: &str,
61        graph_str: &str,
62    ) {
63        self.last_terms = Some(NQuadsLineTerms {
64            subject: subject_str.to_string(),
65            predicate: predicate_str.to_string(),
66            object: object_str.to_string(),
67            graph: graph_str.to_string(),
68            ..Default::default()
69        });
70    }
71
72    fn store_embedded_terms(
73        &mut self,
74        outer_predicate_str: &str,
75        outer_object_str: &str,
76        outer_graph_str: &str,
77    ) {
78        self.last_terms = Some(NQuadsLineTerms {
79            outer_predicate: outer_predicate_str.to_string(),
80            outer_object: outer_object_str.to_string(),
81            outer_graph: outer_graph_str.to_string(),
82            ..Default::default()
83        });
84    }
85
86    /// Parse an N-Quads line (subject, predicate, object, graph)
87    fn parse_line(&mut self, line: &str) -> Result<ParseResult, RdfStarParseError> {
88        let line = line.trim();
89        if line.is_empty() || line.starts_with('#') {
90            return Ok(ParseResult::Comment);
91        }
92
93        // Check for embedded triple start marker
94        if line.starts_with("<<<") {
95            self.parse_embedded_triple_line(line)
96        } else {
97            self.parse_quad_line(line)
98        }
99    }
100
101    /// Parse a regular N-Quads line.
102    ///
103    /// Accepts standards-valid default-graph triples (`s p o .`) and named-graph
104    /// quads (`s p o g .`). A trailing `.` may be a separate token or omitted when
105    /// tools emit bare terms (rio-compatible).
106    fn parse_quad_line(&mut self, line: &str) -> Result<ParseResult, RdfStarParseError> {
107        let parts = tokenize_nquads_terms(line)?;
108        if parts.is_empty() {
109            return Err(RdfStarParseError::InvalidSyntax);
110        }
111        let ends_dot = parts.last().copied() == Some(".");
112        let terms = if ends_dot {
113            &parts[..parts.len() - 1]
114        } else {
115            &parts[..]
116        };
117        // Triple in the default graph, or quad with an explicit graph IRI.
118        let (subject_str, predicate_str, object_str, graph_str) = match terms.len() {
119            3 => (terms[0], terms[1], terms[2], ""),
120            4 => (terms[0], terms[1], terms[2], terms[3]),
121            _ => return Err(RdfStarParseError::InvalidSyntax),
122        };
123
124        let subject = normalise_term(subject_str);
125        let predicate = normalise_term(predicate_str);
126        let object = normalise_term(object_str);
127        let graph = normalise_term(graph_str);
128
129        let subject_hash = generate_60bit_token(subject.as_bytes());
130        let predicate_hash = generate_60bit_token(predicate.as_bytes());
131        let object_hash = generate_60bit_token(object.as_bytes());
132        let graph_hash = self.graph_hash_from_token(graph);
133        self.store_regular_terms(subject, predicate, object, graph);
134
135        Ok(ParseResult::RegularQuad {
136            subject: subject_hash,
137            predicate: predicate_hash,
138            object: object_hash,
139            graph: graph_hash,
140        })
141    }
142
143    /// Parse an embedded triple line with graph context
144    fn parse_embedded_triple_line(&mut self, line: &str) -> Result<ParseResult, RdfStarParseError> {
145        // Format: <<<subject> <predicate> <object>>> <predicate> <object> <graph> .
146
147        // Find the closing >>> for the embedded triple
148        let end_embedded = line
149            .find(">>>")
150            .ok_or(RdfStarParseError::MalformedEmbeddedTriple)?;
151
152        // Extract the embedded triple part
153        let embedded_part = &line[3..end_embedded]; // Skip <<<
154
155        // Parse the embedded triple components
156        let embedded_parts: Vec<&str> = embedded_part.split_whitespace().collect();
157        if embedded_parts.len() < 3 {
158            return Err(RdfStarParseError::MalformedEmbeddedTriple);
159        }
160
161        let subject = embedded_parts[0]
162            .trim_start_matches('<')
163            .trim_end_matches('>');
164        let predicate = embedded_parts[1]
165            .trim_start_matches('<')
166            .trim_end_matches('>');
167        let object = embedded_parts[2]
168            .trim_start_matches('<')
169            .trim_end_matches('>');
170
171        let subject_hash = generate_60bit_token(subject.as_bytes());
172        let predicate_hash = generate_60bit_token(predicate.as_bytes());
173        let object_hash = generate_60bit_token(object.as_bytes());
174
175        // Generate Virtual ID for the embedded triple
176        let virtual_id = generate_embedded_triple_id(subject_hash, predicate_hash, object_hash);
177
178        // Parse the outer triple (the part after >>>)
179        let remaining = &line[end_embedded + 3..]; // Skip >>>
180        let outer_parts: Vec<&str> = remaining.split_whitespace().collect();
181        if outer_parts.len() < 3 {
182            return Err(RdfStarParseError::MalformedEmbeddedTriple);
183        }
184
185        let outer_predicate = outer_parts[0].trim_start_matches('<').trim_end_matches('>');
186        let outer_object = outer_parts[1].trim_start_matches('<').trim_end_matches('>');
187        let outer_graph = outer_parts[2].trim_start_matches('<').trim_end_matches('>');
188
189        let outer_predicate_hash = generate_60bit_token(outer_predicate.as_bytes());
190        let outer_object_hash = generate_60bit_token(outer_object.as_bytes());
191        let outer_graph_hash = self.graph_hash_from_token(outer_graph);
192        self.store_embedded_terms(outer_predicate, outer_object, outer_graph);
193
194        Ok(ParseResult::EmbeddedQuad {
195            virtual_id,
196            components: [subject_hash, predicate_hash, object_hash],
197            outer_predicate: outer_predicate_hash,
198            outer_object: outer_object_hash,
199            outer_graph: outer_graph_hash,
200        })
201    }
202}
203
204/// Return N-Quads terms without splitting the lexical form of a literal.
205///
206/// A literal can contain spaces and escaped quotes, and can be followed by a
207/// language tag or datatype IRI. Those components are one RDF term and must
208/// remain one Q42LEX entry.
209fn tokenize_nquads_terms(line: &str) -> Result<Vec<&str>, RdfStarParseError> {
210    let bytes = line.as_bytes();
211    let mut terms = Vec::new();
212    let mut cursor = 0;
213
214    while cursor < bytes.len() {
215        while cursor < bytes.len() && bytes[cursor].is_ascii_whitespace() {
216            cursor += 1;
217        }
218        if cursor >= bytes.len() || bytes[cursor] == b'#' {
219            break;
220        }
221
222        let start = cursor;
223        match bytes[cursor] {
224            b'"' => {
225                cursor += 1;
226                let mut escaped = false;
227                let mut closed = false;
228                while cursor < bytes.len() {
229                    let byte = bytes[cursor];
230                    cursor += 1;
231                    if escaped {
232                        escaped = false;
233                    } else if byte == b'\\' {
234                        escaped = true;
235                    } else if byte == b'"' {
236                        closed = true;
237                        break;
238                    }
239                }
240                if !closed {
241                    return Err(RdfStarParseError::InvalidSyntax);
242                }
243                if cursor < bytes.len() && bytes[cursor] == b'@' {
244                    cursor += 1;
245                    while cursor < bytes.len() && !bytes[cursor].is_ascii_whitespace() {
246                        cursor += 1;
247                    }
248                } else if cursor + 1 < bytes.len()
249                    && bytes[cursor] == b'^'
250                    && bytes[cursor + 1] == b'^'
251                {
252                    cursor += 2;
253                    if cursor >= bytes.len() || bytes[cursor] != b'<' {
254                        return Err(RdfStarParseError::InvalidSyntax);
255                    }
256                    cursor += 1;
257                    while cursor < bytes.len() && bytes[cursor] != b'>' {
258                        cursor += 1;
259                    }
260                    if cursor >= bytes.len() {
261                        return Err(RdfStarParseError::InvalidSyntax);
262                    }
263                    cursor += 1;
264                }
265            }
266            b'<' => {
267                cursor += 1;
268                while cursor < bytes.len() && bytes[cursor] != b'>' {
269                    cursor += 1;
270                }
271                if cursor >= bytes.len() {
272                    return Err(RdfStarParseError::InvalidSyntax);
273                }
274                cursor += 1;
275            }
276            _ => {
277                while cursor < bytes.len() && !bytes[cursor].is_ascii_whitespace() {
278                    cursor += 1;
279                }
280            }
281        }
282        terms.push(&line[start..cursor]);
283    }
284
285    Ok(terms)
286}
287
288fn normalise_term(term: &str) -> &str {
289    term.strip_prefix('<')
290        .and_then(|value| value.strip_suffix('>'))
291        .unwrap_or(term)
292}
293
294impl RdfStarParser for NQuadsStarParser {
295    fn parse_embedded_triple(
296        &mut self,
297        input: &[u8],
298    ) -> Result<(u64, [u64; 3]), RdfStarParseError> {
299        let line = std::str::from_utf8(input).map_err(|_| RdfStarParseError::InvalidUtf8)?;
300
301        match self.parse_line(line)? {
302            ParseResult::EmbeddedQuad {
303                virtual_id,
304                components,
305                ..
306            } => Ok((virtual_id, components)),
307            _ => Err(RdfStarParseError::MalformedEmbeddedTriple),
308        }
309    }
310
311    fn parse_triple(&mut self, input: &[u8]) -> Result<(u64, u64, u64), RdfStarParseError> {
312        let line = std::str::from_utf8(input).map_err(|_| RdfStarParseError::InvalidUtf8)?;
313
314        match self.parse_line(line)? {
315            ParseResult::RegularQuad {
316                subject,
317                predicate,
318                object,
319                ..
320            } => Ok((subject, predicate, object)),
321            _ => Err(RdfStarParseError::InvalidSyntax),
322        }
323    }
324
325    fn parse_quad(&mut self, input: &[u8]) -> Result<(u64, u64, u64, u64), RdfStarParseError> {
326        let line = std::str::from_utf8(input).map_err(|_| RdfStarParseError::InvalidUtf8)?;
327
328        match self.parse_line(line)? {
329            ParseResult::RegularQuad {
330                subject,
331                predicate,
332                object,
333                graph,
334                ..
335            } => Ok((subject, predicate, object, graph)),
336            ParseResult::EmbeddedQuad {
337                outer_predicate,
338                outer_object,
339                outer_graph,
340                ..
341            } => Ok((0, outer_predicate, outer_object, outer_graph)),
342            _ => Err(RdfStarParseError::InvalidSyntax),
343        }
344    }
345
346    fn supports_quads(&self) -> bool {
347        true
348    }
349
350    fn supports_named_graphs(&self) -> bool {
351        true
352    }
353
354    fn format_name(&self) -> &'static str {
355        "N-Quads-Star"
356    }
357}
358
359/// Parse result for N-Quads-Star
360enum ParseResult {
361    Comment,
362    RegularQuad {
363        subject: u64,
364        predicate: u64,
365        object: u64,
366        graph: u64,
367    },
368    EmbeddedQuad {
369        virtual_id: u64,
370        components: [u64; 3],
371        outer_predicate: u64,
372        outer_object: u64,
373        outer_graph: u64,
374    },
375}
376
377/// Parse N-Quads-Star into any `QuinSink()`.
378pub fn parse_nquads_star_into<R: std::io::Read, S: crate::sparql_library::quin_sink::QuinSink>(
379    reader: R,
380    context_hash: u64,
381    sink: &mut S,
382) -> Result<u64, Box<dyn std::error::Error>> {
383    use std::io::BufRead;
384
385    let mut parser = NQuadsStarParser::new(context_hash);
386    let mut count = 0;
387    let buf_reader = BufReader::new(reader);
388    let mut line_no: u32 = 0;
389
390    for line in buf_reader.lines() {
391        let line = line?;
392        line_no = line_no.saturating_add(1);
393        let parsed = match parser.parse_line(&line) {
394            Ok(p) => p,
395            Err(RdfStarParseError::InvalidSyntax) => {
396                let snippet: String = line.chars().take(120).collect();
397                return Err(format!(
398                    "N-Quads InvalidSyntax at line {line_no}: expected `s p o .` (default graph) or `s p o g .` (named graph); got: {snippet}"
399                )
400                .into());
401            }
402            Err(e) => return Err(e.into()),
403        };
404        match parsed {
405            ParseResult::Comment => continue,
406            ParseResult::RegularQuad {
407                subject,
408                predicate,
409                object,
410                graph,
411                ..
412            } => {
413                if let Some(t) = parser.last_line_terms() {
414                    sink.push_lex(subject, &t.subject);
415                    sink.push_lex(predicate, &t.predicate);
416                    sink.push_lex(object, &t.object);
417                    if !t.graph.is_empty() {
418                        sink.push_lex(graph, &t.graph);
419                    }
420                }
421                let metadata = 0b10 << 61;
422                sink.push(NQuin {
423                    subject,
424                    predicate,
425                    object,
426                    context: graph, // Use graph as context in NQuin
427                    metadata,
428                    parity: NQuin::calculate_parity(subject, predicate, object, graph, metadata),
429                })?;
430                count += 1;
431            }
432            ParseResult::EmbeddedQuad {
433                virtual_id,
434                components,
435                outer_predicate,
436                outer_object,
437                outer_graph,
438                ..
439            } => {
440                if let Some(t) = parser.last_line_terms() {
441                    if !t.outer_predicate.is_empty() {
442                        sink.push_lex(outer_predicate, &t.outer_predicate);
443                    }
444                    if !t.outer_object.is_empty() {
445                        sink.push_lex(outer_object, &t.outer_object);
446                    }
447                    if !t.outer_graph.is_empty() {
448                        sink.push_lex(outer_graph, &t.outer_graph);
449                    }
450                }
451                let metadata = 0b10 << 61;
452                sink.push(NQuin {
453                    subject: virtual_id,
454                    predicate: outer_predicate,
455                    object: outer_object,
456                    context: outer_graph,
457                    metadata,
458                    parity: NQuin::calculate_parity(
459                        virtual_id,
460                        outer_predicate,
461                        outer_object,
462                        outer_graph,
463                        metadata,
464                    ),
465                })?;
466                count += 1;
467
468                sink.push(NQuin {
469                    subject: components[0],
470                    predicate: components[1],
471                    object: components[2],
472                    context: outer_graph,
473                    metadata,
474                    parity: NQuin::calculate_parity(
475                        components[0],
476                        components[1],
477                        components[2],
478                        outer_graph,
479                        metadata,
480                    ),
481                })?;
482                count += 1;
483            }
484        }
485    }
486
487    Ok(count)
488}
489
490/// Parse N-Quads-Star stream via external sort.
491pub fn parse_nquads_star_stream<R: std::io::Read>(
492    reader: R,
493    context_hash: u64,
494    sorter: &mut crate::external_sort::ExternalSorter,
495) -> Result<u64, Box<dyn std::error::Error>> {
496    parse_nquads_star_into(reader, context_hash, sorter)
497}
498
499#[cfg(test)]
500mod tests {
501    use super::*;
502    use crate::rdf_star::RdfStarParser;
503
504    #[test]
505    fn test_nquads_star_parser_creation() {
506        let parser = NQuadsStarParser::new(0);
507        assert_eq!(parser.format_name(), "N-Quads-Star");
508        assert!(parser.supports_quads());
509        assert!(parser.supports_named_graphs());
510    }
511
512    #[test]
513    fn test_parse_regular_quad() {
514        let mut parser = NQuadsStarParser::new(0);
515        let input = b"<http://example.org/Alice> <http://example.org/knows> <http://example.org/Bob> <http://example.org/Graph1> .";
516        let result = parser.parse_quad(input);
517        assert!(result.is_ok());
518        let (s, p, o, g) = result.unwrap();
519        assert_ne!(s, 0);
520        assert_ne!(p, 0);
521        assert_ne!(o, 0);
522        assert_ne!(g, 0);
523    }
524
525    #[test]
526    fn accepts_triple_only_default_graph_nquads() {
527        // RDF dataset interchange often ships default-graph triples inside .nq files.
528        let mut parser = NQuadsStarParser::new(0xABCDu64);
529        let input =
530            b"<http://example.org/Alice> <http://example.org/knows> <http://example.org/Bob> .";
531        let (s, p, o, g) = parser.parse_quad(input).expect("triple-only N-Quads");
532        assert_ne!(s, 0);
533        assert_ne!(p, 0);
534        assert_ne!(o, 0);
535        assert_eq!(g, 0xABCDu64, "omitted graph uses session default");
536    }
537
538    #[test]
539    fn rejects_malformed_nquads_with_clear_failure() {
540        let mut parser = NQuadsStarParser::new(0);
541        assert!(parser
542            .parse_quad(b"<http://example.org/Alice> <http://example.org/knows> .")
543            .is_err());
544    }
545
546    #[test]
547    fn accepts_literals_with_spaces_language_and_datatype() {
548        let mut parser = NQuadsStarParser::new(0);
549        for input in [
550            b"<https://example.org/s> <https://example.org/p> \"A plain literal\" .".as_slice(),
551            b"<https://example.org/s> <https://example.org/p> \"Bonjour le monde\"@fr .".as_slice(),
552            b"<https://example.org/s> <https://example.org/p> \"2026\"^^<http://www.w3.org/2001/XMLSchema#integer> .".as_slice(),
553        ] {
554            let (_, _, object, _) = parser.parse_quad(input).expect("literal N-Quads");
555            assert_ne!(object, 0);
556            assert!(parser.last_line_terms().unwrap().object.starts_with('\"'));
557        }
558    }
559
560    #[test]
561    fn test_parse_embedded_quad() {
562        let mut parser = NQuadsStarParser::new(0);
563        let input = b"<<<http://example.org/Alice> <http://example.org/knows> <http://example.org/Bob>>> <http://example.org/saidBy> <http://example.org/Charlie> <http://example.org/Graph1> .";
564        let result = parser.parse_embedded_triple(input);
565        assert!(result.is_ok());
566        let (virtual_id, components) = result.unwrap();
567        assert_ne!(virtual_id, 0);
568        assert_ne!(components[0], 0);
569        assert_ne!(components[1], 0);
570        assert_ne!(components[2], 0);
571    }
572}
573use std::io::BufReader;