Lib.rs

Parsel，零代码解析器生成器

Parsel 是一个库，可以直接从语法树节点类型生成解析器。

主要入口是自定义 derive proc-macro #[derive(Parse)]，它为注解的 AST 节点类型生成 syn::parse::Parse 特性的实现。添加 #[derive(FromStr)] 还实现了类型的标准 FromStr 特性，通过简单地转发到其 Parse 实现。

此外，还提供了一个#[derive(ToTokens)]宏，通过quote crate轻松获取特定AST节点的源表示。这反过来又帮助获取其Span，因为实现了泛型impl<T: ToTokens> Spanned for T。添加#[derive(Display)]也可以通过简单地转发到其ToTokens实现来为该类型实现标准Display特质。

此外，ast模块提供了一些常见需求的辅助类型，例如可选产生式、重复、括号化和分组。这些大多是围绕syn已提供的解析集合和解析逻辑的轻量级包装。然而，一些非常有用的syn类型，如Option<T: Parse>和Punctuated，有多种等效的有效解析，因此它们没有实现Parse以避免歧义。Parsel通过在类型级别将有效解析集合拆分为多个无歧义的解析类型来处理这种歧义。

示例及其工作原理

Parsel背后的基本思想是观察结构体（struct）和枚举（enum）直接对应于语法的序列和选择，并且它们是可组合的：在生成当前规则的解析器时，不需要知道子表达式的确切实现。

具有结构体类型的AST节点对应于序列：每个字段（无论是命名还是编号）都将按源中指定的顺序逐个解析并填充。

具有枚举类型的AST节点对应于选择：它们的变体会按顺序尝试，并返回第一个成功的变体。元组和结构体变体的字段以与结构体字段相同的顺序处理方式处理。

相应地，您通过指定AST节点的字段和变体来定义您的语法，Parsel将从中生成解析器。让我们看看在简单JSON-like语言的解析器和打印器上下文中这看起来像什么。

use core::iter::FromIterator;
use core::convert::TryFrom;
use parsel::{Parse, ToTokens};
use parsel::ast::{Bracket, Brace, Punctuated, LitBool, LitInt, LitFloat, LitStr};
use parsel::ast::token::{Comma, Colon};

mod kw {
    parsel::custom_keyword!(null);
}

#[derive(PartialEq, Eq, Debug, Parse, ToTokens)]
enum Value {
    Null(kw::null),
    Bool(LitBool),
    Int(LitInt),
    Float(LitFloat),
    Str(LitStr),
    Array(
        #[parsel(recursive)]
        Bracket<Punctuated<Value, Comma>>
    ),
    Object(
        #[parsel(recursive)]
        Brace<Punctuated<KeyValue, Comma>>
    ),
}

#[derive(PartialEq, Eq, Debug, Parse, ToTokens)]
struct KeyValue {
    key: LitStr,
    colon: Colon,
    value: Value,
}

let actual: Value = parsel::parse_quote!({
    "key1": "string value",
    "other key": 318,
    "recursive": [
        1.6180,
        2.7182,
        3.1416,
        null
    ],
    "inner": {
        "nested key": true,
        "hard to write a parser": false
    }
});
let expected = Value::Object(Brace::from(Punctuated::from_iter([
    KeyValue {
        key: LitStr::from("key1"),
        colon: Colon::default(),
        value: Value::Str(LitStr::from("string value")),
    },
    KeyValue {
        key: LitStr::from("other key"),
        colon: Colon::default(),
        value: Value::Int(LitInt::from(318)),
    },
    KeyValue {
        key: LitStr::from("recursive"),
        colon: Colon::default(),
        value: Value::Array(Bracket::from(Punctuated::from_iter([
            Value::Float(LitFloat::try_from(1.6180).unwrap()),
            Value::Float(LitFloat::try_from(2.7182).unwrap()),
            Value::Float(LitFloat::try_from(3.1416).unwrap()),
            Value::Null(kw::null::default()),
        ]))),
    },
    KeyValue {
        key: LitStr::from("inner"),
        colon: Colon::default(),
        value: Value::Object(Brace::from(Punctuated::from_iter([
            KeyValue {
                key: LitStr::from("nested key"),
                colon: Colon::default(),
                value: Value::Bool(LitBool::from(true)),
            },
            KeyValue {
                key: LitStr::from("hard to write a parser"),
                colon: Colon::default(),
                value: Value::Bool(LitBool::from(false)),
            },
        ]))),
    },
])));

assert_eq!(actual, expected);

递归AST节点和循环约束

大多数有用的现实世界语法都是递归的，即它们包含直接（直接递归）或间接（相互递归）引用自身的产生式。这导致包含指向同一类型的指针的AST节点类型。更重要的是，它导致Parse和ToTokens实现的循环约束。这些循环约束可以轻易满足和解决，但由于问题 #48214，Rust编译器的约束求解器目前正在努力处理它们。

因此，在推导Parse和ToTokens的实现时，必须打破此类约束循环。Parsel通过提供属性#[parsel(recursive)]或等效的拼写#[parsel(recursive = true)]来支持此用例。将此属性添加到struct的字段或enum的变体中，将导致生成的Parse和ToTokens impls的where子句中省略所有FieldType: Parse和FieldType: ToTokens约束，打破约束循环，从而使代码能够编译。

只需在单个类型上（实际上是在需要添加最少#[parsel(recursive)]注释的类型）上打破每个约束循环即可。然而，如果语法包含多个自引用循环，则必须打破其中的每一个。此外，如果打破循环需要省略出现在struct或变体的多个字段中的类型的约束，那么就必须将#[parsel(recursive)]添加到所有这些字段。

use parsel::{Parse, ToTokens};
use parsel::ast::{Paren, LitBool};
use parsel::ast::token::{Or, And, Not};

#[derive(PartialEq, Eq, Debug, Parse, ToTokens)]
enum Expr {
    Or {
        lhs: Conjunction,
        op: Or,
        #[parsel(recursive)] // break direct recursion
        rhs: Box<Expr>,
    },
    Conjunction(Conjunction),
}

#[derive(PartialEq, Eq, Debug, Parse, ToTokens)]
enum Conjunction {
    And {
        lhs: Term,
        op: And,
        #[parsel(recursive)] // break direct recursion
        rhs: Box<Conjunction>,
    },
    Term(Term),
}

#[derive(PartialEq, Eq, Debug, Parse, ToTokens)]
enum Term {
    Literal(LitBool),
    Not(
        Not,
        #[parsel(recursive)] // break direct recursion
        Box<Term>,
    ),
    Group(
        #[parsel(recursive)] // break mutual recursion
        Paren<Box<Expr>>
    ),
}

let expr: Expr = parsel::parse_str("true & (false | true & true) & !false").unwrap();

assert_eq!(
    expr,
    Expr::Conjunction(Conjunction::And {
        lhs: Term::Literal(LitBool::from(true)),
        op: And::default(),
        rhs: Box::new(Conjunction::And {
            lhs: Term::Group(Paren::from(Box::new(Expr::Or {
                lhs: Conjunction::Term(Term::Literal(LitBool::from(false))),
                op: Or::default(),
                rhs: Box::new(Expr::Conjunction(Conjunction::And {
                    lhs: Term::Literal(LitBool::from(true)),
                    op: And::default(),
                    rhs: Box::new(Conjunction::Term(Term::Literal(LitBool::from(true)))),
                }))
            }))),
            op: And::default(),
            rhs: Box::new(Conjunction::Term(Term::Not(
                Not::default(),
                Box::new(Term::Literal(LitBool::from(false))),
            ))),
        })
    })
);

expr = expr '|' conjunction
     | conjunction