Crate stap

stap

stap (stateful parser) is a library of stateful parser for streaming input using async syntax.

When a input isn’t enough for parsing, stap remembers the curent state and waits to more inputs and parses them when the input is supplied.

use futures::FutureExt;
use stap::{many1, Anchor, Cursor, Input, Parsing};

fn main() {
    let mut input = Input::new(Cursor {
        buf: Vec::<u8>::new(),
        index: 0,
    });

    let mut parsing = Parsing::new(&mut input, |mut iref| {
        async move {
            // anchoring the current index
            // restoring the index if parsing fails (= when dropped)
            let mut anchor = Anchor::new(&mut iref);

            let num = many1(&mut anchor, |b| b.is_ascii_digit()).await?;
            // Since the parser holds state, this output is showed up only once.
            dbg!(&num);
            let alpha = many1(&mut anchor, |b| b.is_ascii_alphabetic()).await?;
            dbg!(&alpha);

            // parsing is successful, so we can forget the anchor in other words, current index of the input is valid.
            anchor.forget();

            Ok::<_, ()>((num, alpha))
        }
        // This makes the future `Unpin`, currently this is required but any workaround is welcome.
        .boxed_local()
    });

    // There is no input to parse, so parsing should fail.
    assert!(!parsing.poll());

    parsing.cursor_mut().buf.extend_from_slice(b"123a");
    // The parser recognizing the input as a number followed by an alphabet. But because of there may be more alphabets, it should fail.
    assert!(!parsing.poll());

    parsing.cursor_mut().buf.extend_from_slice(b"bc;");
    // the parser should ends.
    assert!(parsing.poll());

    dbg!(parsing.into_result());
}

Structs

Anchor

Anchoring the current index of the cursor. Restore index when dropped.

Cursor

Data of input. Buffer and current index.

CursorRef

A reference of Cursor for parsers. This ensures you can’t get &mut buf in parsers.

Input

You need to wrap Cursor with this to parse.

InputRef

A reference of Input. This is used as input of parsers.

Parsing

Parsing state holds a reference of Input.

ParsingInput

Parsing state holds an Input.

Traits

Parser

Parser trait In this crate, a parser is defined as a function that takes an InputRef and returns a Future.

Functions

just

Match a single item Advance the cursor index if the item is matched.

many0

Match zero or more items until cond is true. Return the range of the matched items including zero range. Advance the cursor index as much as matched.

many1

Match one or more items until cond is true. Return the range of the matched items including or Err for no match at all. Advance the cursor index as much as matched.

tag

Match a sequence of items Advance the cursor index if the sequence is matched.