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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

//! The [`Pass`] trait: a single stage in a parse schedule.

use crate::outcome::Outcome;
use crate::span::Span;

/// One stage of a parse schedule.
///
/// A pass is a pure function from a source region plus its context to an
/// [`Outcome`]: the region either expands into smaller child regions, is
/// accepted as parsed, or fails (later passes may retry it).
///
/// `increparse` is deliberately combinator-agnostic: a pass can wrap any
/// parsing technique — `nom`, `chumsky`, a PEG, regexes, or hand-rolled
/// scanning — behind this trait. The engine only cares about the outcome.
///
/// # Contract
///
/// * Passes must be pure: they must not mutate shared state and must produce
///   the same output for the same `(source, span, ctx)` input.
/// * Every child span returned from [`Outcome::Expand`] must be contained in
///   the input span and on the same source revision. By default a child may
///   cover its parent exactly; with
///   [`EngineConfig::enforce_shrink`](crate::EngineConfig::enforce_shrink)
///   it must be strictly smaller. The engine rejects outcomes that violate
///   this, marking the node [`Failed`](crate::Status::Failed).
/// * Passes must be `Send + Sync` so the engine can run batches on any
///   [`Executor`](crate::Executor).
///
/// # Examples
///
/// ```
/// use increparse::{Outcome, Pass, Span};
///
/// /// Accepts any region whose text starts with "ok".
/// struct AcceptOk;
///
/// impl Pass for AcceptOk {
///     type Ctx = ();
///
///     fn parse(&self, source: &str, span: Span, _ctx: &()) -> Outcome<()> {
///         let text = &source[span.to_range()];
///         if text.starts_with("ok") {
///             Outcome::Done
///         } else {
///             Outcome::Failed
///         }
///     }
/// }
/// ```
pub trait Pass {
    /// Context threaded into every node this pass processes.
    type Ctx;

    /// Attempts to parse `source[span]` given the node's context.
    ///
    /// `source` is a snapshot of the full source text the tree was built
    /// against; `span` selects this node's region within it.
    fn parse(&self, source: &str, span: Span, ctx: &Self::Ctx) -> Outcome<Self::Ctx>;

    /// A human-readable name used in diagnostics; defaults to the type name.
    fn name(&self) -> &'static str {
        std::any::type_name::<Self>()
    }
}

/// Creates a pass from a closure — no struct, no impl block.
///
/// The closure receives the same arguments as [`Pass::parse`] and returns
/// the same [`Outcome`]; captures are allowed, which makes stateful passes
/// (counters, lookup tables) trivial. Passes built this way are named
/// `"PassFn"` in diagnostics.
///
/// # Examples
///
/// ```
/// use increparse::{pass_fn, Outcome, Pass, Span};
///
/// let accept = pass_fn(|_source: &str, _span, _ctx: &()| Outcome::Done);
/// assert!(matches!(accept.parse("abc", Span::new(0, 3, 0), &()), Outcome::Done));
/// ```
pub fn pass_fn<C, F>(f: F) -> PassFn<C, F>
where
    F: for<'a> Fn(&'a str, Span, &'a C) -> Outcome<C> + Send + Sync,
{
    PassFn {
        f,
        phantom: std::marker::PhantomData,
    }
}

/// A [`Pass`] built from a closure. See [`pass_fn`].
pub struct PassFn<C, F> {
    f: F,
    phantom: std::marker::PhantomData<fn(&C)>,
}

impl<C, F> Pass for PassFn<C, F>
where
    F: for<'a> Fn(&'a str, Span, &'a C) -> Outcome<C> + Send + Sync,
{
    type Ctx = C;

    fn parse(&self, source: &str, span: Span, ctx: &C) -> Outcome<C> {
        (self.f)(source, span, ctx)
    }

    fn name(&self) -> &'static str {
        "PassFn"
    }
}