Repository files navigation

Documentation |Release Notes

rust-peg is a simple yet flexible parser generator that makes it easy to write robust parsers. Based on theParsing 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
• Helpfulrustc error messages for errors in the grammar definition or the Rustcode embedded within it
• Rule-level tracing to debug grammars

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

peg::parser!{  grammar list_parser()forstr{    rule number() ->u32      = n:$(['0'..='9']+){? n.parse().or(Err("u32"))}pub rule list() ->Vec<u32>      ="[" l:(number()**",")"]"{ l}}}pubfnmain(){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

• pegviz is a UI for visualizing rust-peg's trace output to debug parsers.
• There exist several crates to format diagnostic messages on source code snippets in the terminal, includingchic,annotate-snippets,codespan-reporting, andcodemap-diagnostic.

Therust-peg grammar is written inrust-peg:peg-macros/grammar.rustpeg. To avoid the circular dependency, a precompiled grammar is checked in aspeg-macros/grammar.rs. To regenerate this, run the./bootstrap.sh script.

There is a large test suite which usestrybuild to test both functionality (tests/run-pass) and error messages for incorrect grammars (tests/compile-fail). Becauserustc error messages change, thecompile-fail tests are only run on the minimum supported Rust version to avoid spurious failures.

Usecargo test to run the entire suite,orcargo test -- trybuild trybuild=lifetimes.rs to test just the indicated file.Add--features trace to trace these tests.