Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Parsing Expression Grammars in Rust

Documentation | Release Notes

rust-peg is a simple yet flexible parser generator that makes it easy to write robust parsers. Based on the Parsing Expression Grammar formalism, it provides a Rust macro that builds a recursive descent parser from a concise definition of the grammar.


  • Parse input from &str, &[u8], &[T] or custom types implementing traits
  • Customizable reporting of parse errors
  • Rules can accept arguments to create reusable rule templates
  • Precedence climbing for prefix/postfix/infix expressions
  • Helpful rustc error messages for errors in the grammar definition or the Rust code embedded within it
  • Rule-level tracing to debug grammars


Parse a comma-separated list of numbers surrounded by brackets into a Vec<u32>:

  grammar list_parser() for str {
    rule number() -> u32
      = n:$(['0'..='9']+) {? n.parse().or(Err("u32")) }

    pub rule list() -> Vec<u32>
      = "[" l:(number() ** ",") "]" { l }

pub fn main() {
    assert_eq!(list_parser::list("[1,1,2,3,5,8]"), Ok(vec![1, 1, 2, 3, 5, 8]));

See the tests for more examples
Grammar rule syntax reference in rustdoc

Comparison with similar parser generators

crate parser type action code integration input type precedence climbing parameterized rules streaming input
peg PEG in grammar proc macro (block) &str, &[T], custom Yes Yes No
pest PEG external proc macro (file) &str Yes No No
nom combinators in source library &[u8], custom No Yes Yes
lalrpop LR(1) in grammar build script &str No Yes No

See also


The rust-peg grammar is written in rust-peg: peg-macros/grammar.rustpeg. To avoid the circular dependency, a precompiled grammar is checked in as peg-macros/ To regenerate this, run the ./ script.

There is a large test suite which uses trybuild to support testing for compilation failure errors. Use cargo test to run the entire suite, or cargo test -- trybuild to test just the indicated file. Add --features trace to trace these tests.