Rust: Rust 宏（Macros）入门：声明宏与元编程

// 用宏来定义"运费计算器"的模板
macro_rules! create_shipping_calculator {
    // 匹配模式：运输方式名称 + 每公里费率 + 速度
    ($name:ident, $rate_per_km:expr, $speed:expr) => {
        fn $name(distance: f64) -> (f64, f64) {
            let base_cost = distance * $rate_per_km;
            let fuel_surcharge = base_cost * 0.1;
            let total = base_cost + fuel_surcharge;
            let time_hours = distance / $speed;
            (total, time_hours)
        }
    };
}

// 一行宏调用 = 生成一个完整函数
create_shipping_calculator!(truck,  1.5,  60.0);
create_shipping_calculator!(ship,   0.8,  30.0);
create_shipping_calculator!(plane,  5.0, 800.0);
create_shipping_calculator!(train,  1.2,  80.0);
create_shipping_calculator!(drone,  2.0,  50.0);

fn main() {
    let distance = 500.0;
    // 每个函数都自动存在，就像手写的一样
    println!("Truck :  cost=${:.2}, time={:.1}h", truck(distance).0,  truck(distance).1);
    println!("Ship  :  cost=${:.2}, time={:.1}h", ship(distance).0,   ship(distance).1);
    println!("Plane :  cost=${:.2}, time={:.1}h", plane(distance).0,  plane(distance).1);
    println!("Train :  cost=${:.2}, time={:.1}h", train(distance).0,  train(distance).1);
    println!("Drone :  cost=${:.2}, time={:.1}h", drone(distance).0,  drone(distance).1);
}

Truck :  cost=$825.00, time=8.3h
Ship  :  cost=$440.00, time=16.7h
Plane :  cost=$2750.00, time=0.6h
Train :  cost=$660.00, time=6.2h
Drone :  cost=$1100.00, time=10.0h

// ============================================
// 使用 macro_rules! 定义宏
// 场景：为结构体字段自动生成 getter 方法
// ============================================

// 宏定义：根据字段名和类型生成 getter 函数
// 宏名后跟 ! 表示这是一个宏
macro_rules! create_getter {
    // 匹配模式：$name 是标识符(ident)，$ty 是类型(ty)
    // => 后面的代码块是展开模板
    ($name:ident, $ty:ty) => {
        pub fn $name(&self) -> $ty {
            self.$name.clone()
        }
    };
}

// 使用宏的结构体
#[derive(Debug)]
struct Student {
    name: String,
    age: u32,
    grade: String,
}

impl Student {
    // 手动写的 getter —— 一个字段就要写一个
    // pub fn name(&self) -> String { self.name.clone() }
    // pub fn age(&self) -> u32 { self.age }
    // pub fn grade(&self) -> String { self.grade.clone() }

    // 用宏自动生成 —— 一行一个 getter
    create_getter!(name, String);
    create_getter!(age, u32);
    create_getter!(grade, String);
}

fn main() {
    let s = Student {
        name: "Alice".to_string(),
        age: 20,
        grade: "A".to_string(),
    };

    // 调用宏生成的 getter 方法
    println!("Name  : {}", s.name());
    println!("Age   : {}", s.age());
    println!("Grade : {}", s.grade());
}

Name  : Alice
Age   : 20
Grade : A

// ============================================
// 演示宏的重复模式：$()* 零次或多次、$()+ 一次或多次
// 场景：一个迷你测试框架，支持多个断言
// ============================================

// 宏：运行多个测试用例，每个用例包含名称 + 表达式 + 期望值
// $()* 表示括号内的模式可以重复零次或多次
macro_rules! run_tests {
    // 每个测试由 (名称, 表达式, 期望值) 三元组组成
    // $test_name 是标识符，$expr 是表达式，$expected 是表达式
    ($( $test_name:ident, $expr:expr, $expected:expr );* $(;)?) => {
        $(
            println!("[Test] {} ...", stringify!($test_name));
            let result = $expr;
            let expected: i32 = $expected;
            if result == expected {
                println!("  ✅ PASS: {} == {}", result, expected);
            } else {
                println!("  ❌ FAIL: {} != {} (expected {})", stringify!($expr), result, expected);
            }
        )*
    };
}

// 宏：计算任意数量数字的和
// $()+ 表示括号内的模式至少重复一次
macro_rules! sum_of {
    // 使用 $()+ 要求至少一个参数
    ($($x:expr),+ $(,)?) => {
        // 0 + $x 的累加: 0 + a + b + c ...
        {
            let mut sum = 0i64;
            $(
                sum += $x as i64;
            )+
            sum
        }
    };
}

fn main() {
    println!("=== Mini Test Framework ===");

    // 调用 run_tests! 宏 —— 传入多个测试用例
    run_tests! {
        add_one,    1 + 1, 2;
        multiply,   3 * 4, 12;
        subtract,   10 - 3, 7;
        power,      2 * 2 * 2, 8
    }

    println!("\n=== Sum Calculator ===");

    // 调用 sum_of! 宏 —— 传入任意数量参数
    let s1 = sum_of!(1, 2, 3, 4, 5);
    println!("sum_of!(1..5) = {}", s1);

    let s2 = sum_of!(10, 20, 30);
    println!("sum_of!(10,20,30) = {}", s2);

    // 单个参数也可以
    let s3 = sum_of!(42);
    println!("sum_of!(42) = {}", s3);

    println!("\n=== Done ===");
}

=== Mini Test Framework ===
[Test] add_one ...
  ✅ PASS: 2 == 2
[Test] multiply ...
  ✅ PASS: 12 == 12
[Test] subtract ...
  ✅ PASS: 7 == 7
[Test] power ...
  ✅ PASS: 8 == 8

=== Sum Calculator ===
sum_of!(1..5) = 15
sum_of!(10,20,30) = 60
sum_of!(42) = 42

=== Done ===

// ============================================
// 模拟实现一个简化版 vec! 宏
// 理解 vec! 宏的底层展开原理
// ============================================

// 简化版 vec! 宏 —— 不支持 vec![x; n] 语法
macro_rules! my_vec {
    // 空向量
    () => {
        Vec::new()
    };
    // 单个元素
    ($elem:expr) => {
        {
            let mut v = Vec::new();
            v.push($elem);
            v
        }
    };
    // 多个元素，用逗号分隔
    ($($x:expr),+ $(,)?) => {
        {
            let mut v = Vec::new();
            $(
                v.push($x);
            )+
            v
        }
    };
}

fn main() {
    // 使用内置 vec! 宏
    let builtin_empty: Vec<i32> = vec![];
    let builtin_one = vec![42];
    let builtin_multi = vec![1, 2, 3, 4, 5];

    println!("=== Built-in vec! ===");
    println!("empty  : {:?}", builtin_empty);
    println!("one    : {:?}", builtin_one);
    println!("multi  : {:?}", builtin_multi);

    // 使用自定义 my_vec! 宏
    let my_empty: Vec<i32> = my_vec![];
    let my_one = my_vec![42];
    let my_multi = my_vec![10, 20, 30, 40, 50];

    println!("\n=== Custom my_vec! ===");
    println!("my_empty : {:?}", my_empty);
    println!("my_one   : {:?}", my_one);
    println!("my_multi : {:?}", my_multi);

    // 验证功能一致
    assert_eq!(builtin_multi.len(), 5);
    assert_eq!(my_multi.len(), 5);
    assert_eq!(builtin_multi, vec![1, 2, 3, 4, 5]);
    assert_eq!(my_multi, vec![10, 20, 30, 40, 50]);

    println!("\n=== All assertions passed! ===");
}

=== Built-in vec! ===
empty  : []
one    : [42]
multi  : [1, 2, 3, 4, 5]

=== Custom my_vec! ===
my_empty : []
my_one   : [42]
my_multi : [10, 20, 30, 40, 50]

=== All assertions passed! ===

// ============================================
// 演示内置宏：todo! / unimplemented! / format! / eprintln!
// 场景：一个正在开发中的库存管理系统
// ============================================

// 模拟库存项
#[derive(Debug)]
struct InventoryItem {
    id: u32,
    name: String,
    quantity: u32,
}

// 库存管理器
struct InventoryManager {
    items: Vec<InventoryItem>,
}

impl InventoryManager {
    fn new() -> InventoryManager {
        InventoryManager {
            items: Vec::new(),
        }
    }

    // 已实现：添加商品
    fn add_item(&mut self, id: u32, name: &str, quantity: u32) {
        self.items.push(InventoryItem {
            id,
            name: name.to_string(),
            quantity,
        });
        // 使用 format! 宏格式化日志消息
        let log_msg = format!("[INFO] Added item: {} (id={}, qty={})", name, id, quantity);
        println!("{}", log_msg);
    }

    // 已实现：查找商品
    fn find_item(&self, id: u32) -> Option<&InventoryItem> {
        self.items.iter().find(|item| item.id == id)
    }

    // 未实现：更新库存
    fn update_quantity(&mut self, _id: u32, _new_qty: u32) {
        // TODO: 实现库存更新逻辑
        // todo!() 会 panic 并提示"未实现"
        todo!("update_quantity: id={} quantity={}", _id, _new_qty);
    }

    // 未实现：生成库存报告
    fn generate_report(&self) -> String {
        // unimplemented!() 表示这个功能还没做
        unimplemented!("generate_report() is not yet implemented");
    }

    // 已实现：打印所有商品
    fn list_items(&self) {
        if self.items.is_empty() {
            println!("  (no items in inventory)");
            return;
        }
        for item in &self.items {
            println!("  #{} {} (qty: {})", item.id, item.name, item.quantity);
        }
    }
}

fn main() {
    let mut manager = InventoryManager::new();

    println!("=== Inventory Manager ===");

    // 添加商品
    manager.add_item(101, "Laptop", 10);
    manager.add_item(102, "Mouse", 50);
    manager.add_item(103, "Keyboard", 30);

    // 列出商品
    println!("\nCurrent inventory:");
    manager.list_items();

    // 查找商品
    if let Some(item) = manager.find_item(102) {
        println!("\nFound: {:?}", item);
    }

    // 以下代码取消注释会 panic（但不会编译错误）：
    // manager.update_quantity(101, 8);   // panics: "not yet implemented"
    // let report = manager.generate_report(); // panics: "not yet implemented"

    println!("\n=== Demo completed ===");
    println!("Note: Try uncommenting update_quantity() or generate_report() to see todo!/unimplemented! in action.");
}

=== Inventory Manager ===
[INFO] Added item: Laptop (id=101, qty=10)
[INFO] Added item: Mouse (id=102, qty=50)
[INFO] Added item: Keyboard (id=103, qty=30)

Current inventory:
  #101 Laptop (qty: 10)
  #102 Mouse (qty: 50)
  #103 Keyboard (qty: 30)

Found: InventoryItem { id: 102, name: "Mouse", quantity: 50 }

=== Demo completed ===
Note: Try uncommenting update_quantity() or generate_report() to see todo!/unimplemented! in action.

// ============================================
// 演示宏的卫生性（hygiene）
// 宏内部创建的变量不会与外部作用域冲突
// ============================================

// 注意：Rust 声明宏的卫生性是"部分卫生"的
// 宏内部用 $ 捕获的变量名不会与外部冲突
// 但宏内部直接写的标识符在 Rust 2018+ 中有特殊规则

// 宏：创建一个局部变量 tmp 并做交换
// 注意：宏内部直接写 tmp 是卫生的——不会影响外部的 tmp
macro_rules! swap_with_tmp {
    ($a:expr, $b:expr) => {
        {
            let tmp = $a;
            $a = $b;
            $b = tmp;
        }
    };
}

// 宏：演示卫生性 —— 即使外部也有 tmp 变量
macro_rules! demonstrate_hygiene {
    ($x:expr) => {
        {
            // 宏内部定义的 tmp 是卫生的
            let tmp = $x * 2;
            println!("  Inside macro: tmp = {}", tmp);
            tmp
        }
    };
}

// 非卫生的反例（用另一种方式展示）
// 注意：Rust 声明宏不允许直接创建跨作用域冲突的变量
// 所以这里用 concat 模拟"非卫生"可能导致的问题

fn main() {
    println!("=== Macro Hygiene Demonstration ===\n");

    // 场景 1：宏内部变量不影响外部
    println!("1. Macro internal variable vs external variable:");
    let mut x = 10;
    let mut y = 20;

    println!("  Before swap: x={}, y={}", x, y);

    // 宏内部使用了 tmp，但外部的变量名 tmp 不受影响
    swap_with_tmp!(x, y);

    println!("  After swap:  x={}, y={}", x, y);

    // 外部的 tmp 变量并不存在 —— 宏内部的 tmp 是卫生的
    // 下面这行取消注释会编译错误：
    // println!("tmp from macro = {}", tmp);  // ❌ 编译错误: tmp not found

    // 场景 2：宏内部变量与外部同名变量不冲突
    println!("\n2. Hygiene with same name:");
    let tmp = 100;  // 外部 tmp
    println!("  Outside macro: tmp = {}", tmp);

    let result = demonstrate_hygiene!(5);
    println!("  Return value: {}", result);
    println!("  Outside macro again: tmp = {}", tmp);  // 仍然是 100，不受宏影响

    // 场景 3：为什么卫生性重要
    println!("\n3. Why hygiene matters:");
    println!("  Without hygiene, macros could accidentally:");
    println!("  - Overwrite variables in the caller's scope");
    println!("  - Create hard-to-find bugs");
    println!("  - Break encapsulation of the calling code");
    println!("  Rust's hygiene prevents these issues at compile time.");

    println!("\n=== Demo completed ===");
}

=== Macro Hygiene Demonstration ===

1. Macro internal variable vs external variable:
  Before swap: x=10, y=20
  After swap:  x=20, y=10

2. Hygiene with same name:
  Outside macro: tmp = 100
  Inside macro: tmp = 10
  Return value: 10
  Outside macro again: tmp = 100

3. Why hygiene matters:
  Without hygiene, macros could accidentally:
  - Overwrite variables in the caller's scope
  - Create hard-to-find bugs
  - Break encapsulation of the calling code
  Rust's hygiene prevents these issues at compile time.

// ============================================
// 综合示例：用宏构建一个迷你单元测试框架
// 结合使用：匹配模式、重复模式、内置宏
// ============================================

// 测试结果统计
struct TestStats {
    total: u32,
    passed: u32,
    failed: u32,
}

impl TestStats {
    fn new() -> TestStats {
        TestStats { total: 0, passed: 0, failed: 0 }
    }

    fn print_summary(&self) {
        println!("\n==============================");
        println!("Test Summary:");
        println!("  Total : {}", self.total);
        println!("  Passed: {}", self.passed);
        println!("  Failed: {}", self.failed);
        if self.failed == 0 {
            println!("  ✅ All tests passed!");
        } else {
            println!("  ❌ {} test(s) failed", self.failed);
        }
        println!("==============================");
    }
}

// 宏：定义一组测试用例
// 每个测试由名称、断言表达式、期望结果组成
macro_rules! test_suite {
    // 匹配零个或多个测试
    ($( $name:ident: $left:expr, $op:tt, $right:expr );* $(;)?) => {{
        let mut stats = TestStats::new();
        $(
            stats.total += 1;
            print!("[Test] {}: {} {} {} ... ", stringify!($name),
                stringify!($left), stringify!($op), stringify!($right));

            let passed = match $op {
                == => { $left == $right }
                != => { $left != $right }
                <  => { $left < $right }
                <= => { $left <= $right }
                >  => { $left > $right }
                >= => { $left >= $right }
                _ => { panic!("Unsupported operator: {}", stringify!($op)); }
            };

            if passed {
                stats.passed += 1;
                println!("✅ PASS");
            } else {
                stats.failed += 1;
                println!("❌ FAIL (got {:?}, expected {:?})", $left, $right);
            }
        )*
        stats
    }};
}

fn main() {
    println!("=== Mini Test Framework ===");
    println!("Using macro-generated test suite\n");

    // 用宏定义测试套件
    let stats = test_suite! {
        test_add:  2 + 2, ==, 4;
        test_sub:  10 - 3, ==, 7;
        test_mul:  3 * 4, ==, 12;
        test_div:  10 / 2, ==, 5;
        test_gt:   100, >, 50;
        test_lt:   3, <, 10;
        test_eq:   "hello", ==, "hello";
        test_neq:  42, !=, 0
    };

    // 打印统计
    stats.print_summary();

    // 验证所有测试通过
    assert_eq!(stats.total, 8);
    assert_eq!(stats.passed, 8);
    assert_eq!(stats.failed, 0);

    println!("\n=== Demo completed ===");
}

=== Mini Test Framework ===
Using macro-generated test suite

[Test] test_add: 2 + 2 == 4 ... ✅ PASS
[Test] test_sub: 10 - 3 == 7 ... ✅ PASS
[Test] test_mul: 3 * 4 == 12 ... ✅ PASS
[Test] test_div: 10 / 2 == 5 ... ✅ PASS
[Test] test_gt: 100 > 50 ... ✅ PASS
[Test] test_lt: 3 < 10 ... ✅ PASS
[Test] test_eq: "hello" == "hello" ... ✅ PASS
[Test] test_neq: 42 != 0 ... ✅ PASS

==============================
Test Summary:
  Total : 8
  Passed: 8
  Failed: 0
  ✅ All tests passed!
==============================

=== Demo completed ===