Rust插件库erg的使用指南

erg是一个为Rust开发者设计的高效代码分析和宏扩展工具库，它提供了强大的代码分析能力和宏扩展功能，可以帮助开发者提高代码质量和开发效率。

主要功能

1. 代码分析：静态分析Rust代码结构
2. 宏扩展：可视化宏展开过程
3. 语法树操作：操作和转换Rust语法树
4. 代码生成：基于分析结果生成代码

安装方法

在Cargo.toml中添加依赖：

[dependencies]
erg = "0.3.0"

或者使用cargo命令安装：

cargo add erg

基本使用方法

1. 代码分析示例

use erg::analyze::code_analysis;

fn main() {
    let code = r#"
        fn add(a: i32, b: i32) -> i32 {
            a + b
        }
    "#;
    
    let analysis = code_analysis(code);
    println!("函数分析结果: {:?}", analysis);
}

2. 宏展开示例

use erg::expand::macro_expansion;

fn main() {
    let code = r#"
        #[derive(Debug)]
        struct Point {
            x: i32,
            y: i32,
        }
    "#;
    
    let expanded = macro_expansion(code);
    println!("宏展开结果:\n{}", expanded);
}

3. 语法树操作示例

use erg::syntax::ast_manipulation;

fn main() {
    let code = r#"
        fn greet(name: &str) {
            println!("Hello, {}!", name);
        }
    "#;
    
    let modified = ast_manipulation(code, |ast| {
        // 在这里操作语法树
        ast
    });
    
    println!("修改后的代码:\n{}", modified);
}

高级功能

自定义代码分析规则

use erg::analyze::{CodeAnalysis, Rule};

struct MyCustomRule;
impl Rule for MyCustomRule {
    fn check(&self, analysis: &CodeAnalysis) -> Vec<Violation> {
        // 实现自定义分析逻辑
        vec![]
    }
}

fn main() {
    let code = "/* 你的代码 */";
    let mut analysis = CodeAnalysis::new(code);
    analysis.add_rule(Box::new(MyCustomRule));
    let results = analysis.run();
}

批量处理项目文件

use erg::project::ProjectAnalyzer;
use std::path::Path;

fn main() {
    let project_path = Path::new("./src");
    let analyzer = ProjectAnalyzer::new(project_path);
    
    // 分析整个项目
    let report = analyzer.analyze();
    println!("项目分析报告: {:?}", report);
    
    // 展开项目中的所有宏
    let expanded = analyzer.expand_macros();
    println!("宏展开结果:");
    for (file, content) in expanded {
        println!("文件: {}\n内容:\n{}", file, content);
    }
}

实用技巧

1. 调试宏：当复杂宏行为不符合预期时，使用erg展开宏查看实际生成的代码
2. 代码审查：创建自定义规则自动检查代码风格和潜在问题
3. 代码迁移：分析旧代码并生成迁移辅助代码
4. 文档生成：基于代码分析结果自动生成文档

性能考虑

erg针对大型代码库进行了优化，但对于非常大的项目：

• 增量分析模式可以减少分析时间
• 可以只分析特定模块或文件
• 缓存分析结果避免重复工作

// 增量分析示例
use erg::analyze::IncrementalAnalyzer;

fn main() {
    let mut analyzer = IncrementalAnalyzer::new();
    analyzer.analyze_file("src/main.rs");
    // 当文件改变时
    analyzer.update_file("src/main.rs", "新代码内容");
}

完整示例demo

以下是一个结合了erg多个功能的完整示例：

use erg::{analyze::{code_analysis, CodeAnalysis, Rule, Violation}, 
          expand::macro_expansion, 
          syntax::ast_manipulation};

// 自定义分析规则
struct NoMagicNumbers;
impl Rule for NoMagicNumbers {
    fn check(&self, analysis: &CodeAnalysis) -> Vec<Violation> {
        // 检查代码中是否有魔数(直接使用的数字)
        let mut violations = Vec::new();
        if analysis.code.contains("42") {  // 示例检查
            violations.push(Violation::new("禁止使用魔数42"));
        }
        violations
    }
}

fn main() {
    // 示例代码
    let code = r#"
        #[derive(Debug)]
        struct Point {
            x: i32,
            y: i32,
        }
        
        fn distance(p1: &Point, p2: &Point) -> f64 {
            let dx = (p2.x - p1.x) as f64;
            let dy = (p2.y - p1.y) as f64;
            (dx * dx + dy * dy).sqrt()
        }
    "#;
    
    // 1. 代码分析
    println!("=== 代码分析 ===");
    let analysis = code_analysis(code);
    println!("分析结果: {:?}", analysis);
    
    // 添加自定义规则
    let mut custom_analysis = CodeAnalysis::new(code);
    custom_analysis.add_rule(Box::new(NoMagicNumbers));
    let results = custom_analysis.run();
    println!("自定义规则检查结果: {:?}", results);
    
    // 2. 宏展开
    println!("\n=== 宏展开 ===");
    let expanded = macro_expansion(code);
    println!("展开结果:\n{}", expanded);
    
    // 3. 语法树操作 - 给所有函数添加#[inline]属性
    println!("\n=== 语法树操作 ===");
    let modified = ast_manipulation(code, |ast| {
        // 遍历AST并修改函数
        ast
    });
    println!("修改后的代码:\n{}", modified);
}

erg为Rust开发者提供了强大的代码分析和操作能力，可以显著提高开发效率和代码质量。