docs(comb): Add Pratt parsing example

This commit adds a new example `c_expression` for the Pratt parser added
to the `expression` module. It also adds this example to the language
special topic.

This example was primarily authored by @39555 in PR #622. @ssmendon
rebased it to the newest release of winnow and added extra
documentation.

Co-authored-by: Sohum Mendon <[email protected]>

Author: 39555

Cargo.toml

@@ -205,6 +205,17 @@ required-features = ["alloc"]
 name = "string"
 required-features = ["alloc"]
 
+[[example]]
+name = "c_expression"
+required-features = ["std"]
+
+
+[[bench]]
+name = "c_expression"
+path = "examples/c_expression/bench.rs"
+harness = false
+required-features = ["std"]
+
 [[bench]]
 name = "arithmetic"
 path = "examples/arithmetic/bench.rs"

examples/c_expression/bench.rs

@@ -0,0 +1,16 @@
+mod parser;
+
+use criterion::black_box;
+use winnow::prelude::*;
+
+fn pratt(c: &mut criterion::Criterion) {
+    let i =
+        "a = 2*-2 / ( &**foo.a->p! -+1) + 3^1 / 4 == 1 * (2 - 7 + 567 *12 /2) + 3*(1+2*( 45 /2))";
+    parser::pratt_parser.parse(i).expect("should parse");
+    c.bench_function("pratt_parser", |b| {
+        b.iter(|| black_box(parser::pratt_parser.parse(i).unwrap()));
+    });
+}
+
+criterion::criterion_group!(benches, pratt);
+criterion::criterion_main!(benches);

examples/c_expression/main.rs

@@ -0,0 +1,44 @@
+use winnow::prelude::*;
+
+mod parser;
+
+fn main() -> Result<(), lexopt::Error> {
+    let args = Args::parse()?;
+
+    let input = args.input.as_deref().unwrap_or("1 + 1");
+    match parser::pratt_parser.parse(input) {
+        Ok(result) => {
+            println!("{result}");
+        }
+        Err(err) => {
+            println!("FAILED");
+            println!("{err}");
+        }
+    }
+
+    Ok(())
+}
+
+#[derive(Default)]
+struct Args {
+    input: Option<String>,
+}
+
+impl Args {
+    fn parse() -> Result<Self, lexopt::Error> {
+        use lexopt::prelude::*;
+
+        let mut res = Args::default();
+
+        let mut args = lexopt::Parser::from_env();
+        while let Some(arg) = args.next()? {
+            match arg {
+                Value(input) => {
+                    res.input = Some(input.string()?);
+                }
+                _ => return Err(arg.unexpected()),
+            }
+        }
+        Ok(res)
+    }
+}