docs(comb): Add documentation to Pratt parser

Author: ssmendon

src/combinator/expression.rs

@@ -8,6 +8,59 @@ use crate::{
 };
 
 /// Parses an expression based on operator precedence.
+///
+/// It uses a Pratt parsing algorithm, where operators are
+/// associated with a binding power. The higher the power,
+/// the more tightly an operator will bind to its operands.
+///
+/// This method returns an [`Expression`], which configures
+/// the Pratt parser.
+///
+/// Each operator type is configured with [`Prefix`], [`Postfix`],
+/// and [`Infix`]. These describe the operator's binding power,
+/// a function that applies the operator to its operand, and the
+/// operator's associativity (infix only).
+///
+/// # Example
+///
+/// Parsing a simple arithmetic expression without parenthesis.
+///
+/// ```rust
+/// # use winnow::prelude::*;
+/// # use winnow::error::ContextError;
+/// # use winnow::ascii::digit1;
+/// # use winnow::combinator::{dispatch, fail};
+/// # use winnow::token::any;
+/// use winnow::combinator::expression;
+/// use winnow::combinator::{Prefix, Postfix, Infix};
+///
+/// fn parser<'i>() -> impl Parser<&'i str, i32, ContextError> {
+///     move |i: &mut &str| {
+///         use Infix::*;
+///         expression(digit1.parse_to::<i32>()) // operands are 32-bit integers
+///             .prefix(dispatch! {any;
+///                 '-' => Prefix(12, |_, a: i32| Ok(-a)),
+///                 _ => fail,
+///             })
+///             .infix(dispatch! {any;
+///                 '+' => Left(5, |_, a, b| Ok(a + b)),
+///                 '-' => Left(5, |_, a, b| Ok(a - b)),
+///                 '*' => Left(7, |_, a, b| Ok(a * b)),
+///                 '/' => Left(7, |_, a: i32, b| Ok(a.checked_div(b).unwrap_or_default())),
+///                 _ => fail,
+///             })
+///             .postfix(dispatch! {any;
+///                 '!' => Postfix(15, |_, a| if a < 1 { Ok(1) } else { Ok((1..=a).fold(1, |acc, a| acc*a)) }),
+///                 _ => fail,
+///             })
+///             .parse_next(i)
+///     }
+/// }
+///
+/// assert_eq!(parser().parse("1+1"), Ok(2));
+/// assert_eq!(parser().parse("0!"), Ok(1));
+/// assert_eq!(parser().parse("-1*5*2*10+30/3!"), Ok(-95));
+/// ```
 #[doc(alias = "pratt")]
 #[doc(alias = "separated")]
 #[doc(alias = "shunting_yard")]
@@ -41,6 +94,15 @@ where
     }
 }
 
+/// A helper struct for [`expression()`].
+///
+/// Holds the configuration for the Pratt parser, including
+/// the operator and operand parsers. A precedence level can
+/// also be set, which is useful to disambiguate parse trees
+/// based on the parent operator's precedence.
+///
+/// Implements [`Parser`]. When parsing an input, it applies
+/// the Pratt parser.
 pub struct Expression<I, O, ParseOperand, Pre, Post, Pix, E>
 where
     I: Stream + StreamIsPartial,
@@ -63,6 +125,12 @@ where
     I: Stream + StreamIsPartial,
     E: ParserError<I>,
 {
+    /// Sets the prefix operator parser.
+    ///
+    /// The parser should parse the input to a [`Prefix`],
+    /// which contains the operator's binding power and
+    /// a fold function which applies the operator to its
+    /// operands.
     #[inline(always)]
     pub fn prefix<NewParsePrefix>(
         self,
@@ -83,6 +151,12 @@ where
         }
     }
 
+    /// Sets the prefix operator parser.
+    ///
+    /// The parser should parse the input to a [`Postfix`],
+    /// which contains the operator's binding power and
+    /// a fold function which applies the operator to its
+    /// operands.
     #[inline(always)]
     pub fn postfix<NewParsePostfix>(
         self,
@@ -103,6 +177,12 @@ where
         }
     }
 
+    /// Sets the prefix operator parser.
+    ///
+    /// The parser should parse the input to a [`Infix`],
+    /// which contains the operator's binding power and
+    /// a fold function which applies the operator to its
+    /// operands.
     #[inline(always)]
     pub fn infix<NewParseInfix>(
         self,
@@ -123,6 +203,10 @@ where
         }
     }
 
+    /// Sets the precedence level of the parser.
+    ///
+    /// This is useful to disambiguate grammars based on the parent operator's
+    /// precedence.
     #[inline(always)]
     pub fn precedence_level(
         mut self,
@@ -158,6 +242,7 @@ where
     }
 }
 
+// Opaque implementation of the Pratt parser.
 fn expression_impl<I, O, Pop, Pre, Post, Pix, E>(
     i: &mut I,
     parse_operand: &mut Pop,
@@ -247,7 +332,13 @@ where
     Ok(operand)
 }
 
-pub struct Prefix<I, O, E>(i64, fn(&mut I, O) -> Result<O, E>);
+/// A helper struct for [`expression()`].
+///
+/// Represents a prefix operator.
+///
+/// It requires an operator binding power, as well as a
+/// fold function which applies the operator.
+pub struct Prefix<I, O, E>(pub i64, pub fn(&mut I, O) -> Result<O, E>);
 
 impl<I, O, E> Clone for Prefix<I, O, E> {
     #[inline(always)]
@@ -263,7 +354,13 @@ impl<I: Stream, O, E: ParserError<I>> Parser<I, Prefix<I, O, E>, E> for Prefix<I
     }
 }
 
-pub struct Postfix<I, O, E>(i64, fn(&mut I, O) -> Result<O, E>);
+/// A helper struct for [`expression()`].
+///
+/// Represents a postfix operator.
+///
+/// It requires an operator binding power, as well as a
+/// fold function which applies the operator.
+pub struct Postfix<I, O, E>(pub i64, pub fn(&mut I, O) -> Result<O, E>);
 
 impl<I, O, E> Clone for Postfix<I, O, E> {
     #[inline(always)]
@@ -279,9 +376,22 @@ impl<I: Stream, O, E: ParserError<I>> Parser<I, Postfix<I, O, E>, E> for Postfix
     }
 }
 
+/// A helper struct for [`expression()`].
+///
+/// Represents a prefix operator.
+///
+/// It requires an operator binding power, as well as a
+/// fold function which applies the operator.
+///
+/// Infix operators also have an associativity. Left-associative
+/// operators will bind more tightly to their rightmost operands,
+/// and it is the opposite for right-associative operators.
 pub enum Infix<I, O, E> {
+    /// Left-associative operator.
     Left(i64, fn(&mut I, O, O) -> Result<O, E>),
+    /// Right-associative operator.
     Right(i64, fn(&mut I, O, O) -> Result<O, E>),
+    /// Neither left or right associative.
     Neither(i64, fn(&mut I, O, O) -> Result<O, E>),
 }