chumsky

When parsing keywords (like let or fn), use text::ascii::keyword to ensure the parser matches the exact identifier and doesn't accidentally match a longer identifier that happens to start with that keyword.

To avoid ambiguity between keywords and identifiers (e.g., a variable named let), place the keyword parser earlier in the .or() chain than the identifier parser. Chumsky resolves ambiguity by choosing the first successful parse it encounters.

let r#let = text::ascii::keyword("let")
    .ignore_then(ident)
    .then_ignore(just('='))
    .then(expr.clone())
    .then_ignore(just(';'))
    .then(decl)
    .map(|((name, rhs), then)| Expr::Let {
        name,
        rhs: Box::new(rhs),
        then: Box::new(then),
    });

r#let.or(expr).padded()

To start a new project with Chumsky, create a new Rust binary project and add chumsky as a dependency. You can use the following boilerplate to read a file from a command-line argument and print its contents.

use chumsky::prelude::*;

fn main() {
    let src = std::fs::read_to_string(std::env::args().nth(1).unwrap()).unwrap();

    println!("{}", src);
}

You can add chumsky to your Cargo project using either the CLI or by manually editing your Cargo.toml file.

Minimum Supported Rust Version (MSRV): 1.65 (due to the use of Generic Associated Types).

Note: The nightly feature is exempt from this MSRV and may require the latest nightly Rust compiler.

$ cargo add chumsky

Chumsky employs performance optimizations that may skip generating output values that go unused (e.g., the output of a in a.ignore_then(b)). This includes potentially optimizing away calls to combinators like Parser::map.

Requirement: Any closures or functions used inline within a parser should be semantically pure. You should not assume a closure is called any specific number of times. While side effects are permitted, they must be irrelevant to the correct functioning of the parser.

Example of acceptable impurity: String interning within Parser::map_with is acceptable because interning a string that is ultimately unused does not affect the parser's correctness.

To avoid manually importing every type, trait, and function, use the prelude to bring all commonly used items into scope:

use chumsky::prelude::*;

Heavy use of the type system can lead to long compilation times. Use these strategies to improve performance:

1. Avoid long .or() chains: Long chains of Parser::or can cause exponential behavior in the Rust trait solver. Replace them with choice(), which provides identical behavior but is much easier for the compiler to process.
2. Use .boxed() for type erasure: For long parser chains, call .boxed() at the end. This performs an allocation during parser creation (not during parsing) to reduce the complexity of the type the compiler must understand. This can significantly improve compilation times and may even improve runtime performance.

Note: .boxed() does not impact the performance of the actual parsing process, only the creation of the parser instance.

The comprehensive Chumsky guide is hosted on docs.rs. For the most up-to-date and interactive documentation, visit the official guide page.

https://docs.rs/chumsky/latest/chumsky/guide/index.html