Crate pest [] [src]

pest. The Elegant Parser

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

Parser

pest works mainly through a trait, Parser, which 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.

Be careful when using this code, it's not being tested!
#[cfg(debug_assertions)]
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.

Modules

iterators

A mod containing iterators and constructs to aid in parser output manipulation.

prec_climber

A mod containing constructs useful in infix operator parsing with the precedence climbing method.

Macros

fails_with

A macro which facilitates grammar testing and debugging by comparing produced errors.

parses_to

A macro which facilitates grammar testing and debugging by comparing produced tokens.

Structs

ParserState

A struct which contains the complete state of a Parser.

Position

A struct containing a position that is tied to a &str which provides useful methods to manually parse it. This leads to an API largely based on the standard Result.

Span

A struct of a span over a &str. It is created from either two Positions or from a Pair.

Enums

Atomicity

An enum specifying the current atomicity of a ParserState.

Error

An enum which defines possible errors.

Lookahead

An enum specifying the current lookahead status of a ParserState.

Token

An enum representing tokens generated by a Parser.

Traits

Parser

A trait that defines a Parser.

RuleType

A trait which parser rules must implement.

Functions

state

Creates a ParserState from a &str, supplying it to a closure f.