pest. 优雅的解析器

pest 是一个通用的解析器，用 Rust 编写，注重可访问性、正确性和性能。它使用解析表达式语法（或 PEG）作为输入，这些语法在精神上类似于正则表达式，但提供了解析复杂语言所需的增强表达能力。

入门指南

开始使用 pest 解析的推荐方法是阅读官方的 书籍。

其他有用的资源

• 在 docs.rs 上的 API 参考文档
• 在我们的 fiddle 上尝试语法并分享它们
• 在 GitHub Discussions 上找到或提出常见问题
• 在 Gitter 或 Discord 上留言、提问或打招呼

示例

以下是一个用于处理不以数字开头的字母数字标识符列表的语法的示例

alpha = { 'a'..'z' | 'A'..'Z' }
digit = { '0'..'9' }

ident = { !digit ~ (alpha | digit)+ }

ident_list = _{ ident ~ (" " ~ ident)* }
          // ^
          // ident_list rule is silent which means it produces no tokens

语法保存在单独的 .pest 文件中，这些文件永远不会与过程代码混合。这导致语言的规范始终保持最新，易于阅读和维护。

有意义的错误报告

根据语法定义，解析器还包括自动错误报告。对于上述示例，输入 "123" 将导致

thread 'main' panicked at ' --> 1:1
  |
1 | 123
  | ^---
  |
  = unexpected digit', src/main.rs:12

而 "ab *" 将导致

thread 'main' panicked at ' --> 1:1
  |
1 | ab *
  |    ^---
  |
  = expected ident', src/main.rs:12

这些错误信息可以从它们的默认 Display 实现中获取，例如：panic!("{}", parser_result.unwrap_err()) 或 println!("{}", e)。

对偶 API

语法可以被用来自动推导出一个 Parser 实现。解析返回一个嵌套标记对的迭代器

use pest_derive::Parser;
use pest::Parser;

#[derive(Parser)]
#[grammar = "ident.pest"]
struct IdentParser;

fn main() {
    let pairs = IdentParser::parse(Rule::ident_list, "a1 b2").unwrap_or_else(|e| panic!("{}", e));

    // Because ident_list is silent, the iterator will contain idents
    for pair in pairs {
        // A pair is a combination of the rule which matched and a span of input
        println!("Rule:    {:?}", pair.as_rule());
        println!("Span:    {:?}", pair.as_span());
        println!("Text:    {}", pair.as_str());

        // A pair can be converted to an iterator of the tokens which make it up:
        for inner_pair in pair.into_inner() {
            match inner_pair.as_rule() {
                Rule::alpha => println!("Letter:  {}", inner_pair.as_str()),
                Rule::digit => println!("Digit:   {}", inner_pair.as_str()),
                _ => unreachable!()
            };
        }
    }
}

这会产生以下输出

Rule:    ident
Span:    Span { start: 0, end: 2 }
Text:    a1
Letter:  a
Digit:   1
Rule:    ident
Span:    Span { start: 3, end: 5 }
Text:    b2
Letter:  b
Digit:   2

在单个文件中定义多个解析器

当前的自动 Parser 推导会产生一个 Rule 枚举，如果尝试定义多个自动推导 Parser 的结构体，可能会产生名称冲突。一个可能的解决方案是将每个解析器结构体放入一个单独的命名空间中

mod a {
    #[derive(Parser)]
    #[grammar = "a.pest"]
    pub struct ParserA;
}
mod b {
    #[derive(Parser)]
    #[grammar = "b.pest"]
    pub struct ParserB;
}

其他功能

• 优先级爬升
• 输入处理
• 自定义错误
• 在稳定版 Rust 上运行

使用 pest 的项目

你可以在 awesome-pest 仓库中找到更多项目和生态系统工具。

• pest_meta (自举)
• AshPaper
• brain
• cicada
• comrak
• elastic-rs
• graphql-parser
• handlebars-rust
• hexdino
• Huia
• insta
• jql
• json5-rs
• mt940
• Myoxine
• py_literal
• rouler
• RuSh
• rs_pbrt
• stache
• tera
• ui_gen
• ukhasnet-parser
• ZoKrates
• Vector
• AutoCorrect
• yaml-peg
• qubit
• caith (一个骰子投掷 crate)
• Melody
• json5-nodes
• prisma

最低支持的 Rust 版本 (MSRV)

此库应始终使用默认功能在 Rust 1.61.0 上编译。

no_std 支持

可以不使用 Rust 标准库构建 pest 和 pest_derive crate，并针对嵌入式环境进行目标。为此，您需要禁用它们的默认功能。在您的 Cargo.toml 中，您可以指定如下：

[dependencies]
# ...
pest = { version = "2", default-features = false }
pest_derive = { version = "2", default-features = false }

如果您想在 pest 仓库的工作区中构建这些 crate，您可以在 cargo 中传递 --no-default-features 标志，并使用 --package (-p) 标志指定这些 crate。例如：

$ cargo build --target thumbv7em-none-eabihf --no-default-features -p pest
$ cargo bootstrap
$ cargo build --target thumbv7em-none-eabihf --no-default-features -p pest_derive

特别感谢

向 Marius Minea 教授致以特别的敬意，感谢他的指导和 pest 的所有贡献者，其中一些是我的朋友。