Skip to main content

qualia_core_db/sparql_library/parsers/
ntriples_star.rs

1use crate::lexicon::{generate_60bit_token, generate_embedded_triple_id};
2use crate::rdf_star::{RdfStarParseError, RdfStarParser};
3///
4/// Implements RDF-Star (SPARQL 1.2) parsing for N-Triples syntax with embedded triples.
5/// N-Triples-Star is a line-based format with strict syntax:
6/// - Regular triple: `<subject> <predicate> <object> .`
7/// - Embedded triple: `<<<subject> <predicate> <object>>> <predicate> <object> .`
8use crate::NQuin;
9/// N-Triples-Star Parser for QualiaDB
10use std::io::BufReader;
11
12/// Human-readable term strings from the most recent successful parse.
13#[derive(Debug, Clone, Default)]
14pub struct NTriplesLineTerms {
15    pub subject: String,
16    pub predicate: String,
17    pub object: String,
18    pub outer_predicate: String,
19    pub outer_object: String,
20}
21
22/// N-Triples-Star parser implementation
23pub struct NTriplesStarParser {
24    /// Context hash for the current parsing session
25    context_hash: u64,
26    last_terms: Option<NTriplesLineTerms>,
27}
28
29impl NTriplesStarParser {
30    /// Create a new N-Triples-Star parser
31    pub fn new(context_hash: u64) -> Self {
32        Self {
33            context_hash,
34            last_terms: None,
35        }
36    }
37
38    /// Session context hash stamped onto emitted quads.
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<&NTriplesLineTerms> {
45        self.last_terms.as_ref()
46    }
47
48    /// Parse an N-Triples line (subject, predicate, object)
49    ///
50    /// Handles both regular triples and embedded triples
51    fn parse_line(&mut self, line: &str) -> Result<ParseResult, RdfStarParseError> {
52        let line = line.trim();
53        if line.is_empty() || line.starts_with('#') {
54            return Ok(ParseResult::Comment);
55        }
56
57        // Check for embedded triple start marker
58        if line.starts_with("<<<") {
59            self.parse_embedded_triple_line(line)
60        } else {
61            self.parse_regular_triple_line(line)
62        }
63    }
64
65    /// Parse a regular N-Triples triple
66    fn parse_regular_triple_line(&mut self, line: &str) -> Result<ParseResult, RdfStarParseError> {
67        // Format: <subject> <predicate> <object> .
68        let parts: Vec<&str> = line.split_whitespace().collect();
69        if parts.len() < 4 {
70            return Err(RdfStarParseError::InvalidSyntax);
71        }
72
73        let subject_str = parts[0];
74        let predicate_str = parts[1];
75        let object_str = parts[2];
76
77        // Strip angle brackets
78        let subject = subject_str.trim_start_matches('<').trim_end_matches('>');
79        let predicate = predicate_str.trim_start_matches('<').trim_end_matches('>');
80        let object = object_str.trim_start_matches('<').trim_end_matches('>');
81
82        let subject_hash = generate_60bit_token(subject.as_bytes());
83        let predicate_hash = generate_60bit_token(predicate.as_bytes());
84        let object_hash = generate_60bit_token(object.as_bytes());
85        self.last_terms = Some(NTriplesLineTerms {
86            subject: subject.to_string(),
87            predicate: predicate.to_string(),
88            object: object.to_string(),
89            ..Default::default()
90        });
91
92        Ok(ParseResult::RegularTriple {
93            subject: subject_hash,
94            predicate: predicate_hash,
95            object: object_hash,
96        })
97    }
98
99    /// Parse an embedded triple line
100    fn parse_embedded_triple_line(&mut self, line: &str) -> Result<ParseResult, RdfStarParseError> {
101        // Format: <<<subject> <predicate> <object>>> <predicate> <object> .
102        // This is complex - need to find the closing >>> and then parse the outer triple
103
104        // Find the closing >>> for the embedded triple
105        let end_embedded = line
106            .find(">>>")
107            .ok_or(RdfStarParseError::MalformedEmbeddedTriple)?;
108
109        // Extract the embedded triple part
110        let embedded_part = &line[3..end_embedded]; // Skip <<<
111
112        // Parse the embedded triple components
113        let embedded_parts: Vec<&str> = embedded_part.split_whitespace().collect();
114        if embedded_parts.len() < 3 {
115            return Err(RdfStarParseError::MalformedEmbeddedTriple);
116        }
117
118        let subject = embedded_parts[0]
119            .trim_start_matches('<')
120            .trim_end_matches('>');
121        let predicate = embedded_parts[1]
122            .trim_start_matches('<')
123            .trim_end_matches('>');
124        let object = embedded_parts[2]
125            .trim_start_matches('<')
126            .trim_end_matches('>');
127
128        let subject_hash = generate_60bit_token(subject.as_bytes());
129        let predicate_hash = generate_60bit_token(predicate.as_bytes());
130        let object_hash = generate_60bit_token(object.as_bytes());
131
132        // Generate Virtual ID for the embedded triple
133        let virtual_id = generate_embedded_triple_id(subject_hash, predicate_hash, object_hash);
134
135        // Parse the outer triple (the part after >>>)
136        let remaining = &line[end_embedded + 3..]; // Skip >>>
137        let outer_parts: Vec<&str> = remaining.split_whitespace().collect();
138        if outer_parts.len() < 2 {
139            return Err(RdfStarParseError::MalformedEmbeddedTriple);
140        }
141
142        let outer_predicate = outer_parts[0].trim_start_matches('<').trim_end_matches('>');
143        let outer_object = outer_parts[1].trim_start_matches('<').trim_end_matches('>');
144
145        let outer_predicate_hash = generate_60bit_token(outer_predicate.as_bytes());
146        let outer_object_hash = generate_60bit_token(outer_object.as_bytes());
147        self.last_terms = Some(NTriplesLineTerms {
148            outer_predicate: outer_predicate.to_string(),
149            outer_object: outer_object.to_string(),
150            ..Default::default()
151        });
152
153        Ok(ParseResult::EmbeddedTriple {
154            virtual_id,
155            components: [subject_hash, predicate_hash, object_hash],
156            outer_predicate: outer_predicate_hash,
157            outer_object: outer_object_hash,
158        })
159    }
160}
161
162impl RdfStarParser for NTriplesStarParser {
163    fn parse_embedded_triple(
164        &mut self,
165        input: &[u8],
166    ) -> Result<(u64, [u64; 3]), RdfStarParseError> {
167        let line = std::str::from_utf8(input).map_err(|_| RdfStarParseError::InvalidUtf8)?;
168
169        match self.parse_line(line)? {
170            ParseResult::EmbeddedTriple {
171                virtual_id,
172                components,
173                ..
174            } => Ok((virtual_id, components)),
175            _ => Err(RdfStarParseError::MalformedEmbeddedTriple),
176        }
177    }
178
179    fn parse_triple(&mut self, input: &[u8]) -> Result<(u64, u64, u64), RdfStarParseError> {
180        let line = std::str::from_utf8(input).map_err(|_| RdfStarParseError::InvalidUtf8)?;
181
182        match self.parse_line(line)? {
183            ParseResult::RegularTriple {
184                subject,
185                predicate,
186                object,
187                ..
188            } => Ok((subject, predicate, object)),
189            _ => Err(RdfStarParseError::InvalidSyntax),
190        }
191    }
192
193    fn parse_quad(&mut self, _input: &[u8]) -> Result<(u64, u64, u64, u64), RdfStarParseError> {
194        // N-Triples-Star doesn't support quads natively (use N-Quads-Star for that)
195        Err(RdfStarParseError::UnsupportedFeature)
196    }
197
198    fn supports_quads(&self) -> bool {
199        false
200    }
201
202    fn supports_named_graphs(&self) -> bool {
203        false
204    }
205
206    fn format_name(&self) -> &'static str {
207        "N-Triples-Star"
208    }
209}
210
211/// Parse result for N-Triples-Star
212enum ParseResult {
213    Comment,
214    RegularTriple {
215        subject: u64,
216        predicate: u64,
217        object: u64,
218    },
219    EmbeddedTriple {
220        virtual_id: u64,
221        components: [u64; 3],
222        outer_predicate: u64,
223        outer_object: u64,
224    },
225}
226
227/// Parse N-Triples-Star into any `QuinSink()` (bounded collector or external sorter).
228pub fn parse_ntriples_star_into<R: std::io::Read, S: crate::sparql_library::quin_sink::QuinSink>(
229    reader: R,
230    context_hash: u64,
231    sink: &mut S,
232) -> Result<u64, Box<dyn std::error::Error>> {
233    use std::io::BufRead;
234
235    let mut parser = NTriplesStarParser::new(context_hash);
236    let mut count = 0;
237    let buf_reader = BufReader::new(reader);
238
239    for line in buf_reader.lines() {
240        let line = line?;
241        match parser.parse_line(&line)? {
242            ParseResult::Comment => continue,
243            ParseResult::RegularTriple {
244                subject,
245                predicate,
246                object,
247                ..
248            } => {
249                if let Some(t) = parser.last_line_terms() {
250                    sink.push_lex(subject, &t.subject);
251                    sink.push_lex(predicate, &t.predicate);
252                    sink.push_lex(object, &t.object);
253                }
254                let metadata = 0b10 << 61;
255                sink.push(NQuin {
256                    subject,
257                    predicate,
258                    object,
259                    context: context_hash,
260                    metadata,
261                    parity: NQuin::calculate_parity(
262                        subject,
263                        predicate,
264                        object,
265                        context_hash,
266                        metadata,
267                    ),
268                })?;
269                count += 1;
270            }
271            ParseResult::EmbeddedTriple {
272                virtual_id,
273                components,
274                outer_predicate,
275                outer_object,
276                ..
277            } => {
278                if let Some(t) = parser.last_line_terms() {
279                    if !t.outer_predicate.is_empty() {
280                        sink.push_lex(outer_predicate, &t.outer_predicate);
281                    }
282                    if !t.outer_object.is_empty() {
283                        sink.push_lex(outer_object, &t.outer_object);
284                    }
285                }
286                let metadata = 0b10 << 61;
287                sink.push(NQuin {
288                    subject: virtual_id,
289                    predicate: outer_predicate,
290                    object: outer_object,
291                    context: context_hash,
292                    metadata,
293                    parity: NQuin::calculate_parity(
294                        virtual_id,
295                        outer_predicate,
296                        outer_object,
297                        context_hash,
298                        metadata,
299                    ),
300                })?;
301                count += 1;
302
303                sink.push(NQuin {
304                    subject: components[0],
305                    predicate: components[1],
306                    object: components[2],
307                    context: context_hash,
308                    metadata,
309                    parity: NQuin::calculate_parity(
310                        components[0],
311                        components[1],
312                        components[2],
313                        context_hash,
314                        metadata,
315                    ),
316                })?;
317                count += 1;
318            }
319        }
320    }
321
322    Ok(count)
323}
324
325/// Parse N-Triples-Star stream and emit Quins via external sort.
326pub fn parse_ntriples_star_stream<R: std::io::Read>(
327    reader: R,
328    context_hash: u64,
329    sorter: &mut crate::external_sort::ExternalSorter,
330) -> Result<u64, Box<dyn std::error::Error>> {
331    parse_ntriples_star_into(reader, context_hash, sorter)
332}
333
334#[cfg(test)]
335mod tests {
336    use super::*;
337    use crate::rdf_star::RdfStarParser;
338
339    #[test]
340    fn test_ntriples_star_parser_creation() {
341        let parser = NTriplesStarParser::new(0);
342        assert_eq!(parser.format_name(), "N-Triples-Star");
343        assert!(!parser.supports_quads());
344        assert!(!parser.supports_named_graphs());
345    }
346
347    #[test]
348    fn test_parse_regular_triple() {
349        let mut parser = NTriplesStarParser::new(0);
350        let input =
351            b"<http://example.org/Alice> <http://example.org/knows> <http://example.org/Bob> .";
352        let result = parser.parse_triple(input);
353        assert!(result.is_ok());
354        let (s, p, o) = result.unwrap();
355        assert_ne!(s, 0);
356        assert_ne!(p, 0);
357        assert_ne!(o, 0);
358    }
359
360    #[test]
361    fn test_parse_embedded_triple() {
362        let mut parser = NTriplesStarParser::new(0);
363        let input = b"<<<http://example.org/Alice> <http://example.org/knows> <http://example.org/Bob>>> <http://example.org/saidBy> <http://example.org/Charlie> .";
364        let result = parser.parse_embedded_triple(input);
365        assert!(result.is_ok());
366        let (virtual_id, components) = result.unwrap();
367        assert_ne!(virtual_id, 0);
368        assert_ne!(components[0], 0);
369        assert_ne!(components[1], 0);
370        assert_ne!(components[2], 0);
371    }
372}