【typst-rs】Typst CLI Eval 命令实现解析

这是一个Rust语言中的Typst文档处理命令解析模块，用于在Typst文档上下文中执行表达式求值。

主要功能

这个eval函数用于执行Typst文档的查询命令，主要功能是：

1. 编译Typst文档（支持分页PDF或HTML格式）
2. 在文档上下文中执行一个表达式
3. 输出表达式的计算结果

完整代码

usecomemo::Track;useecow::eco_format;usetypst::diag::{HintedStrResult,SourceResult,Warned};usetypst::foundations::{Context,Output,Scope,StyleChain,Value};usetypst::syntax::{Span,SyntaxMode};usetypst::{World,engine::Sink,introspection::Introspector};usetypst_eval::eval_string;usetypst_html::HtmlDocument;usetypst_layout::PagedDocument;usecrate::args::{EvalCommand,Target};usecrate::compile::print_diagnostics;usecrate::set_failed;usecrate::world::SystemWorld;/// Execute a query command.pubfneval(command:&'staticEvalCommand)->HintedStrResult<()>{letmutworld=SystemWorld::new(command.r#in.as_ref(),&command.world,&command.process)?;// Reset everything and ensure that the main file is present.world.reset();world.source(world.main()).map_err(|err|err.to_string())?;// Compile the main file and get the introspector.letWarned{output,mutwarnings}=matchcommand.target{Target::Paged=>typst::compile::<PagedDocument>(&world).map(|result|result.map(|output|Box::new(output)asBox<dynOutput>)),Target::Html=>typst::compile::<HtmlDocument>(&world).map(|result|result.map(|output|Box::new(output)asBox<dynOutput>)),};matchoutput{// Retrieve and print evaluation results.Ok(document)=>{letmutsink=Sink::new();leteval_result=evaluate_expression(command.expression.clone(),&mutsink,&world,document.introspector(),);leterrors=match&eval_result{Err(errors)=>errors.as_slice(),Ok(value)=>{letserialized=crate::serialize(value,command.format,command.pretty)?;println!("{serialized}");&[]}};// Collect additional warnings from evaluating the expression.warnings.extend(sink.warnings());print_diagnostics(&world,errors,&warnings,command.process.diagnostic_format,).map_err(|err|eco_format!("failed to print diagnostics ({err})"))?;}// Print diagnostics.Err(errors)=>{set_failed();print_diagnostics(&world,&errors,&warnings,command.process.diagnostic_format,).map_err(|err|eco_format!("failed to print diagnostics ({err})"))?;}}Ok(())}/// Evaluates the expression with code syntax mode and no scope.fnevaluate_expression(expression:String,sink:&mutSink,world:&dynWorld,introspector:&dynIntrospector,)->SourceResult<Value>{eval_string(&typst::ROUTINES,world.track(),sink.track_mut(),introspector.track(),Context::new(None,Some(StyleChain::new(&world.library().styles))).track(),&expression,Span::detached(),SyntaxMode::Code,Scope::default(),)}

代码结构解析

1. 初始化世界环境

letmutworld=SystemWorld::new(command.r#in.as_ref(),&command.world,&command.process)?;world.reset();world.source(world.main()).map_err(|err|err.to_string())?;

• 创建SystemWorld实例，管理文件系统、字体等资源
• 重置状态并确保主文件存在

2. 编译文档

matchcommand.target{Target::Paged=>typst::compile::<PagedDocument>(&world),Target::Html=>typst::compile::<HtmlDocument>(&world),}

根据目标类型编译为分页文档（PDF）或HTML文档

3. 执行表达式求值

leteval_result=evaluate_expression(command.expression.clone(),&mutsink,&world,document.introspector(),// 提供文档内省能力);

4. 核心求值函数 -evaluate_expression

fnevaluate_expression(...)->SourceResult<Value>{eval_string(&typst::ROUTINES,// Typst内置函数world.track(),// 文件追踪（用于增量编译）sink.track_mut(),// 警告收集器introspector.track(),// 文档内省（查询元素位置等）Context::new(...),// 样式上下文&expression,// 要执行的表达式Span::detached(),// 位置信息（分离状态）SyntaxMode::Code,// 代码语法模式Scope::default(),// 空作用域)}

5. 结果处理

• 成功：序列化结果并打印（支持自定义格式和美化输出）
• 失败：打印诊断信息（错误和警告）

关键依赖项说明

典型使用场景

# 查询文档中的标题数量typstevaldocument.typ--expression'query(heading).len()'# 获取特定元素位置typstevaldocument.typ--expression'locate(here).position()'

设计特点

1. 增量编译支持：通过Track特性实现
2. 双目标输出：同时支持分页和HTML文档
3. 表达式求值：可以在编译后的文档上下文中执行Typst代码
4. 诊断友好：完整的错误和警告报告机制

总结

这个模块本质上是Typst CLI工具中eval子命令的实现，用于在Typst文档环境中执行脚本表达式。它允许用户在不修改原始文档的情况下，动态查询文档的各种属性和元素信息。