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)]也将实现类型的标准Display特质，只需简单地将其实例转发到其ToTokens实现。

此外，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)]来支持这种用法。将此属性添加到结构体或枚举变体的字段中，将导致从生成的Parse和ToTokens impls的where子句中省略所有FieldType: Parse和FieldType: ToTokens约束，打破约束循环，从而允许代码编译。

在单个类型上打破每个约束循环（实际上是在需要添加最少#[parsel(recursive)]注解的类型上）就足够了。然而，如果语法包含多个自引用循环，则必须打破其中的每一个。此外，如果打破循环需要省略出现在结构体或变体多个字段中的类型的约束，那么必须将这些字段的所有字段都添加#[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