Rust文档处理库typst-eval的使用：高效解析与执行Typst模板的Rust插件库

介绍

typst-eval是一个用于解析和执行Typst模板的Rust库。Typst是一种现代化的文档排版系统，类似于LaTeX但更简单易用。typst-eval库允许开发者在Rust程序中嵌入和执行Typst模板，实现动态文档生成。

该库提供了以下核心功能：

• 解析Typst模板语法
• 执行模板中的表达式和逻辑
• 处理Typst的数据模型
• 与Rust数据结构交互

安装方法

在Cargo.toml中添加依赖：

[dependencies]
typst-eval = "0.7"  # 请使用最新版本

基本使用方法

1. 执行简单表达式

use typst_eval::eval_string;

fn main() {
    let result = eval_string("1 + 2 * 3").unwrap();
    println!("Result: {}", result); // 输出: Result: 7
}

2. 处理Typst模板

use typst_eval::{eval_template, Scope};

fn main() {
    let template = r#"
        #let name = "Alice"
        Hello, #name!
    "#;
    
    let mut scope = Scope::new();
    let output = eval_template(template, &mut scope).unwrap();
    println!("{}", output); // 输出: Hello, Alice!
}

3. 使用自定义变量

use typst_eval::{eval_template, Scope, Value};

fn main() {
    let template = r#"
        The calculated value is #value * 2
    "#;
    
    let mut scope = Scope::new();
    scope.set("value", Value::from(42));
    
    let output = eval_template(template, &mut scope).unwrap();
    println!("{}", output); // 输出: The calculated value is 84
}

高级功能

1. 使用自定义函数

use typst_eval::{eval_template, Scope, Value, Func};

fn double(args: &[Value]) -> Result<Value, String> {
    if let Some(num) = args.get(0).and_then(|v| v.as_f64()) {
        Ok(Value::from(num * 2.0))
    } else {
        Err("Expected a number".to_string())
    }
}

fn main() {
    let template = r#"
        #let double(x) = user::double(x)
        Double of 21 is #double(21)
    "#;
    
    let mut scope = Scope::new();
    scope.set("user::double", Func::new(double));
    
    let output = eval_template(template, &mut scope).unwrap();
    println!("{}", output); // 输出: Double of 21 is 42
}

2. 处理复杂数据结构

use typst_eval::{eval_template, Scope, Value, Dict};

fn main() {
    let template = r#"
        #let user = data.user
        Name: #user.name \
        Age: #user.age
    "#;
    
    let mut scope = Scope::new();
    let mut user = Dict::new();
    user.insert("name".into(), Value::from("Bob"));
    user.insert("age".into(), Value::from(30));
    
    let mut data = Dict::new();
    data.insert("user".into(), Value::Dict(user));
    scope.set("data", Value::Dict(data));
    
    let output = eval_template(template, &mut scope).unwrap();
    println!("{}", output); 
    // 输出: Name: Bob Age: 30
}

错误处理

typst-eval提供了详细的错误信息：

use typst_eval::eval_string;

fn main() {
    match eval_string("1 + 'text'") {
        Ok(result) => println!("Result: {}", result),
        Err(e) => println!("Error: {}", e),
        // 输出: Error: cannot add integer and string
    }
}

性能提示

1. 对于重复执行的模板，可以预编译Scope对象
2. 避免在循环中重复创建Scope
3. 复杂计算考虑使用Rust实现后暴露给Typst

typst-eval是处理Typst模板的强大工具，特别适合需要将文档生成集成到Rust应用程序中的场景。

完整示例

以下是一个结合了基本使用和高级功能的完整示例：

use typst_eval::{eval_template, Scope, Value, Func, Dict};

// 自定义函数：将字符串转换为大写
fn to_uppercase(args: &[Value]) -> Result<Value, String> {
    if let Some(s) = args.get(0).and_then(|v| v.as_str()) {
        Ok(Value::from(s.to_uppercase()))
    } else {
        Err("Expected a string".to_string())
    }
}

fn main() {
    // 创建模板，包含变量、函数和复杂数据结构
    let template = r#"
        #let user = data.user
        #let upper(s) = user::to_upper(s)
        
        用户信息:
        - 姓名: #upper(user.name)
        - 年龄: #user.age
        - 状态: #if user.active { "活跃" } else { "不活跃" }
        - 分数: #calculate_score(user.scores)
    "#;
    
    // 创建作用域并设置自定义函数
    let mut scope = Scope::new();
    scope.set("user::to_upper", Func::new(to_uppercase));
    
    // 另一个自定义函数：计算平均分
    scope.set("calculate_score", Func::new(|args| {
        if let Some(scores) = args.get(0).and_then(|v| v.as_array()) {
            let sum: f64 = scores.iter()
                .filter_map(|v| v.as_f64())
                .sum();
            let avg = sum / scores.len() as f64;
            Ok(Value::from(avg.round() as i64))
        } else {
            Err("Expected an array of numbers".to_string())
        }
    }));
    
    // 准备复杂数据
    let mut user = Dict::new();
    user.insert("name".into(), Value::from("Bob"));
    user.insert("age".into(), Value::from(30));
    user.insert("active".into(), Value::from(true));
    user.insert("scores".into(), Value::from(vec![85, 90, 78]));
    
    let mut data = Dict::new();
    data.insert("user".into(), Value::Dict(user));
    scope.set("data", Value::Dict(data));
    
    // 执行模板
    match eval_template(template, &mut scope) {
        Ok(output) => println!("生成的文档:\n{}", output),
        Err(e) => println!("模板执行错误: {}", e),
    }
}

这个完整示例展示了：

1. 使用自定义函数处理字符串
2. 处理包含条件逻辑的模板
3. 传递复杂数据结构（包含嵌套字典和数组）
4. 在模板中使用Rust实现的复杂计算逻辑
5. 综合错误处理

输出结果将是：

生成的文档:
用户信息:
- 姓名: BOB
- 年龄: 30
- 状态: 活跃
- 分数: 84