Struct StreamParser 

pub struct StreamParser<T: StreamReference = String> { /* private fields */ }

Incrementally emits complete top-level Links Notation records.

A record can acquire indented children, so a terminating newline is not by itself a safe boundary. A record is committed when the next non-indented content line begins, and the canonical parser validates every committed segment. Set collection off for bounded-memory callback or iterator use.

StreamParser::new() emits LiNo<String>, like parse_lino_to_links. StreamParser::syntax emits LiNo<SyntaxReference>, like parse_lino_to_syntax_links, so every link remembers how its ID was written:

use links_notation::StreamParser;

let mut stream = StreamParser::syntax();
stream.write("(t 1 '1')\n").unwrap();
let links = stream.finish().unwrap();
assert_eq!(links[0].to_string(), "(t 1 1)");
let links_notation::LiNo::Link { values, .. } = &links[0] else { unreachable!() };
assert_eq!(values[2].raw_id(), Some("'1'"));
assert_eq!(values[2].quote(), Some('\''));

Implementations

impl StreamParser

pub fn new() -> Self

Create a parser with the canonical default options.

Examples found in repository

examples/streaming_parser.rs (line 15)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let document = "first loves data\nprofile:\n  name Ada\nlast sees first";

    // Disabling collection retains only the unresolved top-level record.
    let count = Arc::new(AtomicUsize::new(0));
    let callback_count = Arc::clone(&count);
    let mut stream = StreamParser::new();
    stream.set_collect(false).on_link(move |link| {
        callback_count.fetch_add(1, Ordering::Relaxed);
        println!("callback: {link}");
    });

    // Chunk boundaries are arbitrary: this writes one Unicode scalar at a time.
    let mut encoded = [0; 4];
    for symbol in document.chars() {
        stream.write(symbol.encode_utf8(&mut encoded))?;
    }
    stream.finish()?;
    println!("parsed {} links", count.load(Ordering::Relaxed));

    // Iteration is lazy and automatically disables collection.
    let chunks = ["one link\npro", "file:\n  name Ada\n", "two link"];
    for link in StreamParser::parse_chunks(chunks) {
        println!("iterator: {}", link?);
    }

    Ok(())
}

pub fn with_config(config: ParserConfig) -> Self

Create a parser with explicit canonical parser options.

pub fn parse_chunks<I, S>(chunks: I) -> StreamIterator<I::IntoIter>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Lazily parse any iterator of string-like chunks.

Examples found in repository

examples/streaming_parser.rs (line 31)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let document = "first loves data\nprofile:\n  name Ada\nlast sees first";

    // Disabling collection retains only the unresolved top-level record.
    let count = Arc::new(AtomicUsize::new(0));
    let callback_count = Arc::clone(&count);
    let mut stream = StreamParser::new();
    stream.set_collect(false).on_link(move |link| {
        callback_count.fetch_add(1, Ordering::Relaxed);
        println!("callback: {link}");
    });

    // Chunk boundaries are arbitrary: this writes one Unicode scalar at a time.
    let mut encoded = [0; 4];
    for symbol in document.chars() {
        stream.write(symbol.encode_utf8(&mut encoded))?;
    }
    stream.finish()?;
    println!("parsed {} links", count.load(Ordering::Relaxed));

    // Iteration is lazy and automatically disables collection.
    let chunks = ["one link\npro", "file:\n  name Ada\n", "two link"];
    for link in StreamParser::parse_chunks(chunks) {
        println!("iterator: {}", link?);
    }

    Ok(())
}

impl StreamParser<SyntaxReference>

pub fn syntax() -> Self

Create a parser whose links record how each ID was written.

pub fn syntax_with_config(config: ParserConfig) -> Self

Create a parser with explicit options whose links record how each ID was written.

pub fn parse_syntax_chunks<I, S>( chunks: I, ) -> StreamIterator<I::IntoIter, SyntaxReference>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Lazily parse any iterator of string-like chunks into links that record how each ID was written.

impl<T: StreamReference> StreamParser<T>

pub fn on_link<F>(&mut self, callback: F) -> &mut Self

where F: FnMut(&LiNo<T>) + Send + 'static,

Register a callback invoked once for every completed link.

Examples found in repository

examples/streaming_parser.rs (lines 16-19)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let document = "first loves data\nprofile:\n  name Ada\nlast sees first";

    // Disabling collection retains only the unresolved top-level record.
    let count = Arc::new(AtomicUsize::new(0));
    let callback_count = Arc::clone(&count);
    let mut stream = StreamParser::new();
    stream.set_collect(false).on_link(move |link| {
        callback_count.fetch_add(1, Ordering::Relaxed);
        println!("callback: {link}");
    });

    // Chunk boundaries are arbitrary: this writes one Unicode scalar at a time.
    let mut encoded = [0; 4];
    for symbol in document.chars() {
        stream.write(symbol.encode_utf8(&mut encoded))?;
    }
    stream.finish()?;
    println!("parsed {} links", count.load(Ordering::Relaxed));

    // Iteration is lazy and automatically disables collection.
    let chunks = ["one link\npro", "file:\n  name Ada\n", "two link"];
    for link in StreamParser::parse_chunks(chunks) {
        println!("iterator: {}", link?);
    }

    Ok(())
}

pub fn on_error<F>(&mut self, callback: F) -> &mut Self

where F: FnMut(&StreamParseError) + Send + 'static,

Register a callback invoked when parsing fails.

pub fn set_collect(&mut self, collect: bool) -> &mut Self

Enable or disable retaining links for finish and drain.

Examples found in repository

examples/streaming_parser.rs (line 16)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let document = "first loves data\nprofile:\n  name Ada\nlast sees first";

    // Disabling collection retains only the unresolved top-level record.
    let count = Arc::new(AtomicUsize::new(0));
    let callback_count = Arc::clone(&count);
    let mut stream = StreamParser::new();
    stream.set_collect(false).on_link(move |link| {
        callback_count.fetch_add(1, Ordering::Relaxed);
        println!("callback: {link}");
    });

    // Chunk boundaries are arbitrary: this writes one Unicode scalar at a time.
    let mut encoded = [0; 4];
    for symbol in document.chars() {
        stream.write(symbol.encode_utf8(&mut encoded))?;
    }
    stream.finish()?;
    println!("parsed {} links", count.load(Ordering::Relaxed));

    // Iteration is lazy and automatically disables collection.
    let chunks = ["one link\npro", "file:\n  name Ada\n", "two link"];
    for link in StreamParser::parse_chunks(chunks) {
        println!("iterator: {}", link?);
    }

    Ok(())
}

pub fn set_max_buffer_size( &mut self, max_buffer_size: usize, ) -> Result<&mut Self, StreamParseError>

Set the largest unresolved record accepted by the stream.

pub fn write(&mut self, chunk: &str) -> Result<Vec<LiNo<T>>, StreamParseError>

Consume a string chunk and return links made complete by it.

Examples found in repository

examples/streaming_parser.rs (line 24)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let document = "first loves data\nprofile:\n  name Ada\nlast sees first";

    // Disabling collection retains only the unresolved top-level record.
    let count = Arc::new(AtomicUsize::new(0));
    let callback_count = Arc::clone(&count);
    let mut stream = StreamParser::new();
    stream.set_collect(false).on_link(move |link| {
        callback_count.fetch_add(1, Ordering::Relaxed);
        println!("callback: {link}");
    });

    // Chunk boundaries are arbitrary: this writes one Unicode scalar at a time.
    let mut encoded = [0; 4];
    for symbol in document.chars() {
        stream.write(symbol.encode_utf8(&mut encoded))?;
    }
    stream.finish()?;
    println!("parsed {} links", count.load(Ordering::Relaxed));

    // Iteration is lazy and automatically disables collection.
    let chunks = ["one link\npro", "file:\n  name Ada\n", "two link"];
    for link in StreamParser::parse_chunks(chunks) {
        println!("iterator: {}", link?);
    }

    Ok(())
}

pub fn finish(&mut self) -> Result<Vec<LiNo<T>>, StreamParseError>

Finish the stream and return all undrained or newly emitted links.

Examples found in repository

examples/streaming_parser.rs (line 26)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let document = "first loves data\nprofile:\n  name Ada\nlast sees first";

    // Disabling collection retains only the unresolved top-level record.
    let count = Arc::new(AtomicUsize::new(0));
    let callback_count = Arc::clone(&count);
    let mut stream = StreamParser::new();
    stream.set_collect(false).on_link(move |link| {
        callback_count.fetch_add(1, Ordering::Relaxed);
        println!("callback: {link}");
    });

    // Chunk boundaries are arbitrary: this writes one Unicode scalar at a time.
    let mut encoded = [0; 4];
    for symbol in document.chars() {
        stream.write(symbol.encode_utf8(&mut encoded))?;
    }
    stream.finish()?;
    println!("parsed {} links", count.load(Ordering::Relaxed));

    // Iteration is lazy and automatically disables collection.
    let chunks = ["one link\npro", "file:\n  name Ada\n", "two link"];
    for link in StreamParser::parse_chunks(chunks) {
        println!("iterator: {}", link?);
    }

    Ok(())
}

pub fn drain(&mut self) -> Vec<LiNo<T>>

Return and forget retained links.

pub fn reset(&mut self) -> &mut Self

Reuse this parser while preserving its configuration and callbacks.

pub fn position(&self) -> StreamPosition

Return the absolute stream position and unresolved buffer size.

Trait Implementations

impl Default for StreamParser

fn default() -> Self

Returns the “default value” for a type.