Rust动态字符串格式化库dynfmt使用指南

dynfmt是一个Rust库，提供了运行时字符串模板渲染功能，相比标准库的格式化功能更加灵活高效。

主要特性

• 运行时解析和渲染字符串模板
• 支持多种格式化语法
• 高性能的模板渲染
• 支持自定义格式化函数

基本用法

首先在Cargo.toml中添加依赖：

[dependencies]
dynfmt = "0.3"

简单示例

use dynfmt::{Format, SimpleCurlyFormat};

fn main() {
    let formatted = SimpleCurlyFormat.format("Hello, {}!", &["Rust"]);
    assert_eq!(formatted.expect("formatting failed"), "Hello, Rust!");
}

使用命名参数

use dynfmt::{Format, SimpleCurlyFormat};

fn main() {
    let formatted = SimpleCurlyFormat.format(
        "Hello, {name}! You have {count} new messages.",
        &[("name", "Alice"), ("count", "5")]
    );
    assert_eq!(formatted.unwrap(), "Hello, Alice! You have 5 new messages.");
}

支持的格式化语法

dynfmt支持多种格式化语法风格：

1. 花括号语法 (默认)

   SimpleCurlyFormat.format("{} {}", &["Hello", "world"]);
   

2. Python风格语法

   use dynfmt::PythonFormat;
   
   PythonFormat.format("{0} {1}", &["Hello", "world"]);
   

3. Shell风格语法

   use dynfmt::ShellFormat;
   
   ShellFormat.format("$0 $1", &["Hello", "world"]);
   

高级用法

自定义格式化器

use dynfmt::{Format, Formatter, SimpleCurlyFormat};

struct UppercaseFormatter;

impl Formatter for UppercaseFormatter {
    fn format(&self, value: &dyn std::fmt::Display) -> Result<String, dynfmt::Error> {
        Ok(value.to_string().to_uppercase())
    }
}

fn main() {
    let formatted = SimpleCurlyFormat.format_with(
        "Hello, {name}!",
        &[("name", &"rust")],
        &UppercaseFormatter
    );
    assert_eq!(formatted.unwrap(), "Hello, RUST!");
}

性能优化

对于需要重复使用的模板，可以先编译模板：

use dynfmt::{CompiledFormat, SimpleCurlyFormat};

fn main() {
    let template = SimpleCurlyFormat.compile("Hello, {name}!").unwrap();
    let formatted = template.format(&[("name", "World")]).unwrap();
    assert_eq!(formatted, "Hello, World!");
}

错误处理

dynfmt提供了详细的错误信息：

use dynfmt::{Format, SimpleCurlyFormat};

match SimpleCurlyFormat.format("Hello, {name}", &[]) {
    Ok(result) => println!("{}", result),
    Err(e) => eprintln!("Formatting error: {}", e),
}

完整示例

下面是一个结合多种功能的完整示例：

use dynfmt::{Format, SimpleCurlyFormat, PythonFormat, ShellFormat, Formatter, CompiledFormat};

// 自定义格式化器 - 将值转换为大写
struct UppercaseFormatter;

impl Formatter for UppercaseFormatter {
    fn format(&self, value: &dyn std::fmt::Display) -> Result<String, dynfmt::Error> {
        Ok(value.to_string().to_uppercase())
    }
}

fn main() {
    // 1. 简单格式化示例
    let simple_result = SimpleCurlyFormat.format("Hello, {}!", &["Rust"])
        .expect("简单格式化失败");
    println!("简单格式化结果: {}", simple_result);

    // 2. 命名参数示例
    let named_result = SimpleCurlyFormat.format(
        "Hello, {name}! Age: {age}", 
        &[("name", "Bob"), ("age", "30")]
    ).unwrap();
    println!("命名参数结果: {}", named_result);

    // 3. Python风格格式化
    let python_result = PythonFormat.format("{0} {1} {0}", &["Repeat", "me"])
        .unwrap();
    println!("Python风格结果: {}", python_result);

    // 4. Shell风格格式化
    let shell_result = ShellFormat.format("$1 $0", &["World", "Hello"])
        .unwrap();
    println!("Shell风格结果: {}", shell_result);

    // 5. 使用自定义格式化器
    let custom_result = SimpleCurlyFormat.format_with(
        "Shout: {msg}", 
        &[("msg", &"hello world")],
        &UppercaseFormatter
    ).unwrap();
    println!("自定义格式化器结果: {}", custom_result);

    // 6. 编译模板重用
    let template = SimpleCurlyFormat.compile("重用的模板: {data}")
        .unwrap();
    for i in 1..=3 {
        let result = template.format(&[("data", &i.to_string())]).unwrap();
        println!("编译模板结果 {}: {}", i, result);
    }

    // 7. 错误处理示例
    match SimpleCurlyFormat.format("Missing {parameter}", &[]) {
        Ok(r) => println!("成功: {}", r),
        Err(e) => println!("错误处理示例 - 预期错误: {}", e),
    }
}

这个完整示例展示了：

1. 基本格式化功能
2. 命名参数使用
3. 不同语法风格
4. 自定义格式化器
5. 模板编译和重用
6. 错误处理

dynfmt是处理运行时字符串格式化的强大工具，特别适合模板内容在运行时确定或需要从外部加载的场景。