Added Spanned combinator (#713)

zesterer · Hedgehogo · web-flow · commit c7ccffb2ad84 · 2025-11-19T23:47:01.000Z
* Added Spanned combinator

* Fixed doc test

* refactor: move `&lt;T&gt;` from `Spanned` to `WrappingSpan`

* Added Input::split_spanned

---------

Co-authored-by: Hedgehogo &lt;lologlek8@gmail.com&gt;
diff --git a/examples/mini_ml.rs b/examples/mini_ml.rs
@@ -50,8 +50,6 @@ impl fmt::Display for Token<'_> {
     }
 }
 
-pub type Spanned<T> = (T, SimpleSpan);
-
 fn lexer<'src>(
 ) -> impl Parser<'src, &'src str, Vec<Spanned<Token<'src>>>, extra::Err<Rich<'src, char>>> {
     recursive(|token| {
@@ -82,7 +80,7 @@ fn lexer<'src>(
                 .as_context()
                 .map(Token::Parens),
         ))
-        .map_with(|t, e| (t, e.span()))
+        .spanned()
         .padded()
     })
     .repeated()
@@ -128,7 +126,7 @@ fn parser<'tokens, 'src: 'tokens>() -> impl Parser<
             ident.map(Expr::Var),
             // let x = y in z
             just(Token::Let)
-                .ignore_then(ident.map_with(|x, e| (x, e.span())))
+                .ignore_then(ident.spanned())
                 .then_ignore(just(Token::Eq))
                 .then(expr.clone())
                 .then_ignore(just(Token::In))
@@ -141,45 +139,39 @@ fn parser<'tokens, 'src: 'tokens>() -> impl Parser<
         ));
 
         choice((
-            atom.map_with(|expr, e| (expr, e.span())),
+            atom.spanned(),
             // fn x y = z
-            just(Token::Fn).ignore_then(
-                ident.map_with(|x, e| (x, e.span())).repeated().foldr_with(
-                    just(Token::Eq).ignore_then(expr.clone()),
-                    |arg, body, e| {
-                        (
-                            Expr::Func {
-                                arg: Box::new(arg),
-                                body: Box::new(body),
-                            },
-                            e.span(),
-                        )
-                    },
-                ),
-            ),
+            just(Token::Fn).ignore_then(ident.spanned().repeated().foldr_with(
+                just(Token::Eq).ignore_then(expr.clone()),
+                |arg, body, e| {
+                    Expr::Func {
+                        arg: Box::new(arg),
+                        body: Box::new(body),
+                    }
+                    .with_span(e.span())
+                },
+            )),
             // ( x )
-            expr.nested_in(select_ref! { Token::Parens(ts) = e => ts.split_token_span(e.span()) }),
+            expr.nested_in(select_ref! { Token::Parens(ts) = e => ts.split_spanned(e.span()) }),
         ))
         .pratt(vec![
             // Multiply
             infix(left(10), just(Token::Asterisk), |x, _, y, e| {
-                (Expr::Mul(Box::new(x), Box::new(y)), e.span())
+                Expr::Mul(Box::new(x), Box::new(y)).with_span(e.span())
             })
             .boxed(),
             // Add
             infix(left(9), just(Token::Plus), |x, _, y, e| {
-                (Expr::Add(Box::new(x), Box::new(y)), e.span())
+                Expr::Add(Box::new(x), Box::new(y)).with_span(e.span())
             })
             .boxed(),
             // Calls
             infix(left(1), empty(), |x, _, y, e| {
-                (
-                    Expr::Apply {
-                        func: Box::new(x),
-                        arg: Box::new(y),
-                    },
-                    e.span(),
-                )
+                Expr::Apply {
+                    func: Box::new(x),
+                    arg: Box::new(y),
+                }
+                .with_span(e.span())
             })
             .boxed(),
         ])
@@ -270,17 +262,17 @@ impl Solver<'_> {
         expr: &Spanned<Expr<'src>>,
         env: &mut Vec<(&'src str, TyVar)>,
     ) -> TyVar {
-        match &expr.0 {
-            Expr::Num(_) => self.create_ty(TyInfo::Num, expr.1),
-            Expr::Bool(_) => self.create_ty(TyInfo::Bool, expr.1),
+        match &**expr {
+            Expr::Num(_) => self.create_ty(TyInfo::Num, expr.span),
+            Expr::Bool(_) => self.create_ty(TyInfo::Bool, expr.span),
             Expr::Var(name) => {
                 env.iter()
                     .rev()
                     .find(|(n, _)| n == name)
                     .unwrap_or_else(|| {
                         failure(
                             format!("No such local '{name}'"),
-                            ("not found in scope".to_string(), expr.1),
+                            ("not found in scope".to_string(), expr.span),
                             None,
                             self.src,
                         )
@@ -289,32 +281,32 @@ impl Solver<'_> {
             }
             Expr::Let { lhs, rhs, then } => {
                 let rhs_ty = self.check(rhs, env);
-                env.push((lhs.0, rhs_ty));
+                env.push((**lhs, rhs_ty));
                 let out_ty = self.check(then, env);
                 env.pop();
                 out_ty
             }
             Expr::Func { arg, body } => {
-                let arg_ty = self.create_ty(TyInfo::Unknown, arg.1);
-                env.push((arg.0, arg_ty));
+                let arg_ty = self.create_ty(TyInfo::Unknown, arg.span);
+                env.push((&**arg, arg_ty));
                 let body_ty = self.check(body, env);
                 env.pop();
-                self.create_ty(TyInfo::Func(arg_ty, body_ty), expr.1)
+                self.create_ty(TyInfo::Func(arg_ty, body_ty), expr.span)
             }
             Expr::Apply { func, arg } => {
                 let func_ty = self.check(func, env);
                 let arg_ty = self.check(arg, env);
-                let out_ty = self.create_ty(TyInfo::Unknown, expr.1);
-                let func_req_ty = self.create_ty(TyInfo::Func(arg_ty, out_ty), func.1);
-                self.unify(func_req_ty, func_ty, expr.1);
+                let out_ty = self.create_ty(TyInfo::Unknown, expr.span);
+                let func_req_ty = self.create_ty(TyInfo::Func(arg_ty, out_ty), func.span);
+                self.unify(func_req_ty, func_ty, expr.span);
                 out_ty
             }
             Expr::Add(l, r) | Expr::Mul(l, r) => {
-                let out_ty = self.create_ty(TyInfo::Num, expr.1);
+                let out_ty = self.create_ty(TyInfo::Num, expr.span);
                 let l_ty = self.check(l, env);
-                self.unify(out_ty, l_ty, expr.1);
+                self.unify(out_ty, l_ty, expr.span);
                 let r_ty = self.check(r, env);
-                self.unify(out_ty, r_ty, expr.1);
+                self.unify(out_ty, r_ty, expr.span);
                 out_ty
             }
         }
@@ -363,14 +355,14 @@ pub struct Vm<'src> {
 
 impl<'src> Vm<'src> {
     pub fn eval(&mut self, expr: &'src Spanned<Expr<'src>>) -> Value<'src> {
-        match &expr.0 {
+        match &**expr {
             Expr::Num(x) => Value::Num(*x),
             Expr::Bool(x) => Value::Bool(*x),
             Expr::Var(var) => self
                 .stack
                 .iter()
                 .rev()
-                .find(|(v, _)| v.0 == *var)
+                .find(|(v, _)| **v == *var)
                 .unwrap()
                 .1
                 .clone(),
@@ -456,7 +448,7 @@ fn main() {
         .unwrap_or_else(|errs| parse_failure(&errs[0], src));
 
     let expr = parser()
-        .parse(tokens[..].split_token_span((0..src.len()).into()))
+        .parse(tokens[..].split_spanned((0..src.len()).into()))
         .into_result()
         .unwrap_or_else(|errs| parse_failure(&errs[0], src));
 
diff --git a/src/combinator.rs b/src/combinator.rs
@@ -539,13 +539,51 @@ where
     #[inline(always)]
     fn go<M: Mode>(&self, inp: &mut InputRef<'src, '_, I, E>) -> PResult<M, I::Span> {
         let before = inp.cursor();
-        self.parser.go::<M>(inp)?;
+        self.parser.go::<Check>(inp)?;
         Ok(M::bind(|| inp.span_since(&before)))
     }
 
     go_extra!(I::Span);
 }
 
+/// See [`Parser::spanned`].
+pub struct Spanned<A, OA> {
+    pub(crate) parser: A,
+    #[allow(dead_code)]
+    pub(crate) phantom: EmptyPhantom<OA>,
+}
+
+impl<A: Copy, OA> Copy for Spanned<A, OA> {}
+impl<A: Clone, OA> Clone for Spanned<A, OA> {
+    fn clone(&self) -> Self {
+        Self {
+            parser: self.parser.clone(),
+            phantom: EmptyPhantom::new(),
+        }
+    }
+}
+
+impl<'src, I, OA, E, A> Parser<'src, I, <I::Span as WrappingSpan<OA>>::Spanned, E>
+    for Spanned<A, OA>
+where
+    I: Input<'src>,
+    E: ParserExtra<'src, I>,
+    A: Parser<'src, I, OA, E>,
+    I::Span: WrappingSpan<OA>,
+{
+    #[inline(always)]
+    fn go<M: Mode>(
+        &self,
+        inp: &mut InputRef<'src, '_, I, E>,
+    ) -> PResult<M, <I::Span as WrappingSpan<OA>>::Spanned> {
+        let before = inp.cursor();
+        let out = self.parser.go::<M>(inp)?;
+        Ok(M::map(out, |out| inp.span_since(&before).make_wrapped(out)))
+    }
+
+    go_extra!(<I::Span as WrappingSpan<OA>>::Spanned);
+}
+
 /// See [`Parser::try_foldl`].
 pub struct TryFoldl<F, A, B, OB, E> {
     pub(crate) parser_a: A,
diff --git a/src/input.rs b/src/input.rs
@@ -257,6 +257,18 @@ pub trait Input<'src>: 'src {
         self.map(eoi, |(t, s)| (t, s))
     }
 
+    /// Take an input (such as a slice) with token type `T` where `T` is a spanned type, and split it into its inner value and token.
+    ///
+    /// See the documentation for [`Input::split_token_span`], which is nearly identical in concept.
+    fn split_spanned<T, S>(self, eoi: S) -> MappedInput<'src, T, S, Self>
+    where
+        Self: Input<'src, Token = S::Spanned, MaybeToken = &'src S::Spanned> + Sized,
+        T: 'src,
+        S: WrappingSpan<T> + 'src,
+    {
+        self.map(eoi, |spanned| (S::inner_of(spanned), S::span_of(spanned)))
+    }
+
     /// Map the spans output for this input to a different output span.
     ///
     /// This is useful if you wish to include extra context that applies to all spans emitted during a parse, such as
diff --git a/src/inspector.rs b/src/inspector.rs
@@ -6,10 +6,6 @@
 //! beside his pillar and woken him with a start."*
 use super::*;
 use crate::input::{Checkpoint, Cursor};
-use core::ops::{Deref, DerefMut};
-
-#[allow(unused)] // for intra-doc links
-use crate::Parser;
 
 /// A type that receives event hooks when certain parsing actions occur.
 ///
diff --git a/src/lib.rs b/src/lib.rs
@@ -80,7 +80,7 @@ pub mod prelude {
         },
         recovery::{nested_delimiters, skip_then_retry_until, skip_until, via_parser},
         recursive::{recursive, Recursive},
-        span::{SimpleSpan, Span as _},
+        span::{SimpleSpan, Span as _, SpanWrap as _, Spanned},
         text, Boxed, ConfigIterParser, ConfigParser, IterParser, ParseResult, Parser,
     };
     pub use crate::{select, select_ref};
@@ -104,7 +104,7 @@ use core::{
     hash::Hash,
     marker::PhantomData,
     mem::MaybeUninit,
-    ops::{Range, RangeFrom},
+    ops::{Deref, DerefMut, Range, RangeFrom},
     panic::Location,
     str::FromStr,
 };
@@ -126,7 +126,7 @@ use self::{
     primitive::Any,
     private::{Check, Emit, IPResult, Located, MaybeUninitExt, Mode, PResult, Sealed},
     recovery::{RecoverWith, Strategy},
-    span::Span,
+    span::{Span, WrappingSpan},
     text::*,
     util::{IntoMaybe, MaybeMut, MaybeRef},
 };
@@ -770,6 +770,22 @@ pub trait Parser<'src, I: Input<'src>, O, E: ParserExtra<'src, I> = extra::Defau
         }
     }
 
+    /// Wrap the output of this parser in the pattern's span.
+    ///
+    /// This is often used to preserve the span of AST nodes for error generation by future passes.
+    ///
+    /// The output type of this parser is `<I::Span as WrappingSpan>::Spanned<O>`. For parsers using [`SimpleSpan`],
+    /// that means the output type is [`Spanned<O, SimpleSpan>`].
+    fn spanned(self) -> combinator::Spanned<Self, O>
+    where
+        Self: Sized,
+    {
+        combinator::Spanned {
+            parser: self,
+            phantom: EmptyPhantom::new(),
+        }
+    }
+
     /// After a successful parse, apply a fallible function to the output. If the function produces an error, treat it
     /// as a parsing error.
     ///
diff --git a/src/span.rs b/src/span.rs
diff --git a/src/util.rs b/src/util.rs
