pest 1.0.0-beta.3

The Elegant Parser

pest. The Elegant Parser

pest is a PEG parser built with simplicity and speed in mind.

Input & Parser

pest works mainly through two traits: Input & Parser. Input defines the capabilities of an input source, while Parser provides an interface to the parsing functionality. Since Parser is a trait, parsing needs to be defined either though the #[derive(Parser)] attribute, or manually through the Position API. The use of the derive is highly encouraged since this is the only way you can make use of pest's PEG grammar, while manual parser definition can be used where highly specific or efficient parsing is required.

#[derive(Parser)]

pest comes with a procedural macro crate--pest_derive--which needs to be included in Cargo.toml in order to enable the derive.

pest_derive = "*"

.pest files

Grammar definitions reside in custom .pest files located in the src directory. Their path is relative to src and is specified between the derive attribute and an empty struct that Parser will be derived on.

Because of a limitation in procedural macros, there is no way for Cargo to know that a module needs to be recompiled based on the file that the procedural macro is opening. This leads to the case where modifying a .pest file without touching the file where the derive is does not recompile it if it already has a working binary in the cache. To avoid this issue, the grammar file can be included in a dummy const definition while debugging.

const _GRAMMAR: &'static str = include_str!("path/to/my_grammar.pest"); // relative to this file

#[derive(Parser)]
#[grammar = "path/to/my_grammar.pest"] // relative to src
struct MyParser;

The grammar of .pest files is documented in the pest_derive crate.