increparse 0.1.0

A combinator-agnostic, multi-pass fixpoint parsing engine: run schedules of parser passes over a growing parse tree.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

//! The quickest way to try a schedule out.

use crate::cancel::CancelToken;
use crate::engine::Passes;
use crate::engine::{Engine, RunReport};
use crate::executor::SerialExecutor;
use crate::tree::ParseTree;

/// Parses `source` from scratch with `passes` and returns the settled tree
/// plus the run report — the quickest way to try a schedule out, in a test,
/// a doctest, or a first experiment:
///
/// ```
/// use increparse::prelude::*;
///
/// let settle = pass_fn(|_source: &str, _span, _ctx: &()| Outcome::Done);
/// let (tree, report) = increparse::run("hello", (settle,), ());
///
/// assert!(report.reached_fixpoint);
/// assert_eq!(tree.status(tree.root()), Status::Done);
/// ```
///
/// It is exactly [`Engine::run`] over a fresh [`ParseTree::from_source`]
/// with the [`SerialExecutor`] — for cancellation, custom executors, or
/// incremental sessions, use [`Engine`](crate::Engine) and
/// [`Session`](crate::Session) directly.
pub fn run<C>(source: &str, passes: impl Passes<C>, root_ctx: C) -> (ParseTree<C>, RunReport)
where
    C: Clone + PartialEq + Send + 'static,
{
    let engine = Engine::with(passes);
    let mut tree = ParseTree::from_source(source, 0, root_ctx);
    let report = engine.run(source, &mut tree, &SerialExecutor, &CancelToken::new());
    (tree, report)
}