Rust宏扩展库dprint-core-macros的使用指南

概述

dprint-core-macros是dprint代码格式化工具的核心宏库，提供了一系列用于代码格式化和自动化处理的宏。这些宏主要用于简化格式化器的开发，处理抽象语法树(AST)的转换和生成。

主要功能

1. 提供AST节点的定义和生成宏
2. 简化格式化规则的实现
3. 支持代码生成和转换
4. 为dprint生态系统提供核心宏支持

安装方法

在Cargo.toml中添加依赖：

[dependencies]
dprint-core-macros = "0.1"

核心宏介绍

ast_node!宏

用于定义AST节点类型：

use dprint_core_macros::ast_node;

// 定义一个函数声明AST节点
ast_node!(
    #[derive(Clone, Debug, PartialEq)]
    pub struct FunctionDeclaration {
        pub name: String,          // 函数名
        pub parameters: Vec<Parameter>,  // 参数列表
        pub body: BlockStatement,   // 函数体
    }
);

format_node!宏

用于定义节点的格式化规则：

use dprint_core_macros::format_node;

// 定义函数声明的格式化规则
format_node!(
    FunctionDeclaration {
        "function" name "(" parameters ")" " " body
    }
);

visit_node!宏

用于实现访问者模式遍历AST：

use dprint_core_macros::visit_node;

// 为函数声明实现访问者模式
visit_node!(
    impl Visitor for FunctionDeclaration {
        fn visit_children(&mut self, visitor: &mut impl Visitor) {
            visitor.visit(&mut self.name);
            for param in &mut self.parameters {
                visitor.visit(param);
            }
            visitor.visit(&mut self.body);
        }
    }
);

完整示例

下面是一个使用dprint-core-macros定义简单AST和格式化器的完整示例：

use dprint_core_macros::{ast_node, format_node, visit_node};

// 定义AST节点 - 二元表达式
ast_node!(
    #[derive(Clone, Debug, PartialEq)]
    pub struct BinaryExpression {
        pub left: Box<Expression>,  // 左表达式
        pub operator: String,       // 操作符
        pub right: Box<Expression>, // 右表达式
    }
);

// 定义AST节点 - 表达式枚举
ast_node!(
    #[derive(Clone, Debug, PartialEq)]
    pub enum Expression {
        NumberLiteral(f64),         // 数字字面量
        StringLiteral(String),      // 字符串字面量
        BinaryExpression(BinaryExpression), // 二元表达式
    }
);

// 定义二元表达式的格式化规则
format_node!(
    BinaryExpression {
        left operator " " right
    }
);

// 定义表达式的格式化规则
format_node!(
    Expression {
        match self {
            Expression::NumberLiteral(num) => num.to_string(),  // 数字直接转字符串
            Expression::StringLiteral(s) => format!("\"{}\"", s), // 字符串加引号
            Expression::BinaryExpression(expr) => expr.format(), // 二元表达式调用其format方法
        }
    }
);

// 实现二元表达式的访问者模式
visit_node!(
    impl Visitor for BinaryExpression {
        fn visit_children(&mut self, visitor: &mut impl Visitor) {
            visitor.visit(&mut self.left);
            visitor.visit(&mut self.right);
        }
    }
);

// 实现表达式的访问者模式
visit_node!(
    impl Visitor for Expression {
        fn visit_children(&mut self, visitor: &mut impl Visitor) {
            match self {
                Expression::BinaryExpression(expr) => visitor.visit(expr), // 只访问二元表达式
                _ => {}
            }
        }
    }
);

高级用法

自定义格式化配置

// 根据配置决定操作符周围的空格
format_node!(
    BinaryExpression {
        left
        if should_space_around_operator {  // 条件判断
            concat!(" ", operator, " ")    // 有空格
        } else {
            operator                       // 无空格
        }
        right
    }
);

条件格式化

// 根据参数和函数体是否为空决定格式化方式
format_node!(
    FunctionDeclaration {
        "function" name "("
        if !parameters.is_empty() {  // 参数不为空时
            parameters.join(", ")   // 用逗号分隔参数
        }
        ")" 
        if !body.statements.is_empty() {  // 函数体不为空时
            " " body                      // 添加空格和函数体
        }
    }
);

注意事项

1. 宏生成的代码会包含一些trait实现，如Format和Visit
2. 节点定义需要遵循一定的模式才能正确工作
3. 格式化规则中可以使用Rust表达式，但需要返回实现ToString的类型

dprint-core-macros库是构建自定义代码格式化工具的强大基础，通过它提供的宏可以大大简化AST处理和格式化逻辑的实现。