Pandoc 实战用--typst-input向 Typst 文档注入sys.inputs变量【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc--typst-input是 Pandoc Typst 读取器提供的一个命令行参数用于在把 Typst 源文件转换为其他格式时把外部键值对注入到 Typst 的sys.inputs字典中。本文以仓库中的命令测试用例 test/command/11588.md 为起点完整讲解该参数的语法、分隔符规则、空格处理方式、默认配置文件写法并结合 Typst 读取器源码 说明其底层实现原理。读完本文你将能熟练使用--typst-input实现一次编写 Typst 文档、多次按参数渲染不同内容的模板化转换流程。一、测试用例一行命令验证sys.inputs注入仓库测试目录 test/command/11588.md 中的命令测试是理解该功能的最佳入口其完整内容如下% pandoc --typst-input fooFOO --typst-input barbar bim -f typst -t plain #sys.inputs.at(foo); #sys.inputs.at(bar); ^D FOO bar bim这是一段标准的 Pandoc command 测试与 test/Command.hs 中运行的test-pandoc.hs测试框架对应第一行%之后是要执行的命令紧接着是喂给标准输入^D为输入结束标志的 Typst 源文档最后两段FOO与bar bim是期望的标准输出。它验证的核心行为是通过两个--typst-input参数分别注入fooFOO与barbar bim在 Typst 文档中用#sys.inputs.at(foo)与#sys.inputs.at(bar)读取转换到 plain 格式后注入的变量值被原样输出FOO和bar bim。也就是说--typst-input让 Typst 文档中所有对sys.inputs的读取在 Pandoc 转换阶段就完成了求值结果直接进入转换后的文档而不是停留在未被解析的 Typst 源码里。1.1 测试用例覆盖的关键语法点该用例虽短却覆盖了三个必须注意的细节参数可重复命令中出现了两个--typst-input说明该选项不是单值选项而是可以多次指定、累积成一组键值对。作为键值分隔符fooFOO用把键foo与值FOO分开。带空格的取值必须加引号barbar bim中值bar bim含有空格因此整体用双引号包裹shell 才不会把空格截断成多个参数。二、官方文档中的参数规范在仓库根目录的 MANUAL.txt 中--typst-input的完整说明如下--typst-inputKEY[VAL]Set a parameter value that will be made available to the typst parser insys.inputs, like--inputin thetypstCLI. Either:ormay be used to separateKEYfromVAL. Values containing spaces must be quoted.从中可以提炼出四条规范规范说明用途设置一个参数值注入到 Typst 解析器的sys.inputs中对标等价于 Typst 官方 CLI 的--input参数分隔符:与均可用于分隔键和值即--typst-input foobar与--typst-input foo:bar都合法空格规则值中含空格时必须加引号注意命令测试用例 11588 使用的是分隔符而 MANUAL 明确两者皆可实测时可以按需选用。三、默认文件defaults file中的等价写法--typst-input除了作为命令行参数使用还可以写进 Pandoc 的默认文件defaults file通常为 YAML中。MANUAL 的Options affecting specific writers/readers与默认文件对应关系表中给出了明确示例见 MANUAL.txt--typst-input foobar | typst-inputs: | foo: bar即命令行--typst-input foobar等价于在 YAML 默认文件中写typst-inputs: foo: bar这一键名typst-inputs与 Pandoc 默认文件解析代码中的字段完全对应——在 src/Text/Pandoc/App/Opt.hs 中通过o .:? typst-inputs .! optTypstInputs defaultOpts读取该字段若默认文件中没有typst-inputs键则回退到命令行选项optTypstInputs的默认值。也就是说命令行参数与默认文件字段可以互补默认文件提供基础参数集命令行可追加或覆盖。四、底层实现从命令行到sys.inputs的完整调用链理解--typst-input的实现需要沿着三条代码路径串联起来。4.1 命令行解析KEYVALUE拆分成键值对在 src/Text/Pandoc/App/CommandLineOptions.hs 中选项定义如下, option [typst-input] (ReqArg (\arg opt - do let (key, val) splitField arg return opt{ optTypstInputs (T.pack key, T.pack val) : optTypstInputs opt }) KEYVALUE) Files (T.pack Typst variable KEYVALUE)关键点有三ReqArg该选项必须携带一个参数KEYVALUE形式不能单独出现splitField对传入的字符串按分隔符拆成(key, val)二元组对应前面提到的:或两种分隔符支持累加语义新解析出的键值对被:前插到optTypstInputs列表头部因此多次指定--typst-input会累积成一组键值对列表。4.2 选项传递optTypstInputs进入ReaderOptions命令行解析得到的optTypstInputs需要传入读取器。在 src/Text/Pandoc/App.hs 中它被写入ReaderOptions的readerTypstInputs字段, readerTypstInputs optTypstInputs opts而ReaderOptions中该字段的定义位于 src/Text/Pandoc/Options.hs, readerTypstInputs :: [(Text, Text)] -- ^ parameters specified using --typst-input其默认值为空列表[]见 src/Text/Pandoc/Options.hs即不指定参数时不会注入任何sys.inputs变量。4.3 求值阶段evaluateTypst消费键值对最终消费这些键值对的是 Typst 读取器的核心入口 readTypst。整个流程为用parseTypst把输入源解析为 Typst 语法树构造Operations记录包含loadBytes、currentUTCTime、lookupEnvVar、checkExistence等 IO 操作调用evaluateTypst ops (readerTypstInputs opts) inputName parsed把readerTypstInputs键值对传入求值器求值结果即经过变量替换后的内容再交由pPandoc解析器转换为 Pandoc AST最终输出为目标格式。从源码结构可以推断evaluateTypst是执行 Typst 求值的通用求值器模块头注释也写明本读取器的工作方式是 Reads and evaluates a Typst document as a Pandoc AST见 src/Text/Pandoc/Readers/Typst.hssys.inputs变量的解析正是发生在这一求值阶段之后才轮到 Pandoc 自身的 AST 转换。五、实战模板化 Typst 文档的按参数渲染结合上述语法与实现--typst-input最常见的实战场景是编写一份引用sys.inputs的 Typst 模板转换时通过命令行传入不同取值从而用同一份源文件产出不同内容的文档。5.1 最小示例对应测试用例沿用测试用例的写法在终端执行pandoc --typst-input fooFOO --typst-input barbar bim -f typst -t plain EOF #sys.inputs.at(foo); #sys.inputs.at(bar); EOF输出为FOO bar bim要点#sys.inputs.at(key)是 Typst 中读取sys.inputs字典的标准方式其中at方法对字典按键取值。Pandoc 在转换时若发现该键已被--typst-input注入就会用注入值替换未被注入的键则保持 Typst 语义由求值器按 Typst 自身规则处理。5.2 带默认值的字段sys.inputs是字典因此 Typst 也支持带默认值的读取方式例如#sys.inputs.at(author, default: unknown)配合命令pandoc --typst-input authorAlice -f typst -t plain输出Alice而如果不注入author则回退到默认值unknown。这为可选参数类模板提供了优雅的实现手段at的第二个具名参数default是 Typst 字典方法的既有能力。5.3 与默认文件配合使用把参数固化到默认文件typst-params.yaml中from: typst to: plain typst-inputs: title: Pandoc 与 Typst 集成 author: Alice然后执行pandoc --defaultstypst-params.yaml input.typ再在命令行追加--typst-input authorBob即可在不修改默认文件的情况下临时覆盖作者信息命令行与默认文件共同累积到optTypstInputs列表中。5.4 注意事项与限制值含空格必须引号--typst-input barbar bim否则 shell 会将其拆为多个参数导致解析错误:与都可作分隔符若值本身包含建议改用:分隔避免歧义参数累积而非覆盖多次指定--typst-input会全部累积从实现看键值对以列表形式存储并传递给求值器同一键多次注入时以后注入者生效与否取决于求值器对字典的处理因此模板中应避免对同一键重复注入仅作用于 Typst 读取器该选项只在使用-f typstTypst 作为输入格式时生效输出格式无关——无论是 plain、markdown、html 还是其他格式注入都发生在读取阶段。六、总结--typst-input打通了外部参数与Typst 模板之间的通道语法上支持/:两种分隔符、支持重复指定、要求带空格的值加引号写法上既可用于命令行也可写入默认文件的typst-inputs字段实现上由 CommandLineOptions.hs 解析、经 App.hs 传入ReaderOptions最终在 Typst 读取器 的evaluateTypst求值阶段注入sys.inputs。参考仓库测试 test/command/11588.md 与 MANUAL.txt 的规范即可在项目实践中稳定复现同一模板、按参数渲染的工作流。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pandoc 实战：用 `--typst-input` 向 Typst 文档注入 `sys.inputs` 变量
Pandoc 实战用--typst-input向 Typst 文档注入sys.inputs变量【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc--typst-input是 Pandoc Typst 读取器提供的一个命令行参数用于在把 Typst 源文件转换为其他格式时把外部键值对注入到 Typst 的sys.inputs字典中。本文以仓库中的命令测试用例 test/command/11588.md 为起点完整讲解该参数的语法、分隔符规则、空格处理方式、默认配置文件写法并结合 Typst 读取器源码 说明其底层实现原理。读完本文你将能熟练使用--typst-input实现一次编写 Typst 文档、多次按参数渲染不同内容的模板化转换流程。一、测试用例一行命令验证sys.inputs注入仓库测试目录 test/command/11588.md 中的命令测试是理解该功能的最佳入口其完整内容如下% pandoc --typst-input fooFOO --typst-input barbar bim -f typst -t plain #sys.inputs.at(foo); #sys.inputs.at(bar); ^D FOO bar bim这是一段标准的 Pandoc command 测试与 test/Command.hs 中运行的test-pandoc.hs测试框架对应第一行%之后是要执行的命令紧接着是喂给标准输入^D为输入结束标志的 Typst 源文档最后两段FOO与bar bim是期望的标准输出。它验证的核心行为是通过两个--typst-input参数分别注入fooFOO与barbar bim在 Typst 文档中用#sys.inputs.at(foo)与#sys.inputs.at(bar)读取转换到 plain 格式后注入的变量值被原样输出FOO和bar bim。也就是说--typst-input让 Typst 文档中所有对sys.inputs的读取在 Pandoc 转换阶段就完成了求值结果直接进入转换后的文档而不是停留在未被解析的 Typst 源码里。1.1 测试用例覆盖的关键语法点该用例虽短却覆盖了三个必须注意的细节参数可重复命令中出现了两个--typst-input说明该选项不是单值选项而是可以多次指定、累积成一组键值对。作为键值分隔符fooFOO用把键foo与值FOO分开。带空格的取值必须加引号barbar bim中值bar bim含有空格因此整体用双引号包裹shell 才不会把空格截断成多个参数。二、官方文档中的参数规范在仓库根目录的 MANUAL.txt 中--typst-input的完整说明如下--typst-inputKEY[VAL]Set a parameter value that will be made available to the typst parser insys.inputs, like--inputin thetypstCLI. Either:ormay be used to separateKEYfromVAL. Values containing spaces must be quoted.从中可以提炼出四条规范规范说明用途设置一个参数值注入到 Typst 解析器的sys.inputs中对标等价于 Typst 官方 CLI 的--input参数分隔符:与均可用于分隔键和值即--typst-input foobar与--typst-input foo:bar都合法空格规则值中含空格时必须加引号注意命令测试用例 11588 使用的是分隔符而 MANUAL 明确两者皆可实测时可以按需选用。三、默认文件defaults file中的等价写法--typst-input除了作为命令行参数使用还可以写进 Pandoc 的默认文件defaults file通常为 YAML中。MANUAL 的Options affecting specific writers/readers与默认文件对应关系表中给出了明确示例见 MANUAL.txt--typst-input foobar | typst-inputs: | foo: bar即命令行--typst-input foobar等价于在 YAML 默认文件中写typst-inputs: foo: bar这一键名typst-inputs与 Pandoc 默认文件解析代码中的字段完全对应——在 src/Text/Pandoc/App/Opt.hs 中通过o .:? typst-inputs .! optTypstInputs defaultOpts读取该字段若默认文件中没有typst-inputs键则回退到命令行选项optTypstInputs的默认值。也就是说命令行参数与默认文件字段可以互补默认文件提供基础参数集命令行可追加或覆盖。四、底层实现从命令行到sys.inputs的完整调用链理解--typst-input的实现需要沿着三条代码路径串联起来。4.1 命令行解析KEYVALUE拆分成键值对在 src/Text/Pandoc/App/CommandLineOptions.hs 中选项定义如下, option [typst-input] (ReqArg (\arg opt - do let (key, val) splitField arg return opt{ optTypstInputs (T.pack key, T.pack val) : optTypstInputs opt }) KEYVALUE) Files (T.pack Typst variable KEYVALUE)关键点有三ReqArg该选项必须携带一个参数KEYVALUE形式不能单独出现splitField对传入的字符串按分隔符拆成(key, val)二元组对应前面提到的:或两种分隔符支持累加语义新解析出的键值对被:前插到optTypstInputs列表头部因此多次指定--typst-input会累积成一组键值对列表。4.2 选项传递optTypstInputs进入ReaderOptions命令行解析得到的optTypstInputs需要传入读取器。在 src/Text/Pandoc/App.hs 中它被写入ReaderOptions的readerTypstInputs字段, readerTypstInputs optTypstInputs opts而ReaderOptions中该字段的定义位于 src/Text/Pandoc/Options.hs, readerTypstInputs :: [(Text, Text)] -- ^ parameters specified using --typst-input其默认值为空列表[]见 src/Text/Pandoc/Options.hs即不指定参数时不会注入任何sys.inputs变量。4.3 求值阶段evaluateTypst消费键值对最终消费这些键值对的是 Typst 读取器的核心入口 readTypst。整个流程为用parseTypst把输入源解析为 Typst 语法树构造Operations记录包含loadBytes、currentUTCTime、lookupEnvVar、checkExistence等 IO 操作调用evaluateTypst ops (readerTypstInputs opts) inputName parsed把readerTypstInputs键值对传入求值器求值结果即经过变量替换后的内容再交由pPandoc解析器转换为 Pandoc AST最终输出为目标格式。从源码结构可以推断evaluateTypst是执行 Typst 求值的通用求值器模块头注释也写明本读取器的工作方式是 Reads and evaluates a Typst document as a Pandoc AST见 src/Text/Pandoc/Readers/Typst.hssys.inputs变量的解析正是发生在这一求值阶段之后才轮到 Pandoc 自身的 AST 转换。五、实战模板化 Typst 文档的按参数渲染结合上述语法与实现--typst-input最常见的实战场景是编写一份引用sys.inputs的 Typst 模板转换时通过命令行传入不同取值从而用同一份源文件产出不同内容的文档。5.1 最小示例对应测试用例沿用测试用例的写法在终端执行pandoc --typst-input fooFOO --typst-input barbar bim -f typst -t plain EOF #sys.inputs.at(foo); #sys.inputs.at(bar); EOF输出为FOO bar bim要点#sys.inputs.at(key)是 Typst 中读取sys.inputs字典的标准方式其中at方法对字典按键取值。Pandoc 在转换时若发现该键已被--typst-input注入就会用注入值替换未被注入的键则保持 Typst 语义由求值器按 Typst 自身规则处理。5.2 带默认值的字段sys.inputs是字典因此 Typst 也支持带默认值的读取方式例如#sys.inputs.at(author, default: unknown)配合命令pandoc --typst-input authorAlice -f typst -t plain输出Alice而如果不注入author则回退到默认值unknown。这为可选参数类模板提供了优雅的实现手段at的第二个具名参数default是 Typst 字典方法的既有能力。5.3 与默认文件配合使用把参数固化到默认文件typst-params.yaml中from: typst to: plain typst-inputs: title: Pandoc 与 Typst 集成 author: Alice然后执行pandoc --defaultstypst-params.yaml input.typ再在命令行追加--typst-input authorBob即可在不修改默认文件的情况下临时覆盖作者信息命令行与默认文件共同累积到optTypstInputs列表中。5.4 注意事项与限制值含空格必须引号--typst-input barbar bim否则 shell 会将其拆为多个参数导致解析错误:与都可作分隔符若值本身包含建议改用:分隔避免歧义参数累积而非覆盖多次指定--typst-input会全部累积从实现看键值对以列表形式存储并传递给求值器同一键多次注入时以后注入者生效与否取决于求值器对字典的处理因此模板中应避免对同一键重复注入仅作用于 Typst 读取器该选项只在使用-f typstTypst 作为输入格式时生效输出格式无关——无论是 plain、markdown、html 还是其他格式注入都发生在读取阶段。六、总结--typst-input打通了外部参数与Typst 模板之间的通道语法上支持/:两种分隔符、支持重复指定、要求带空格的值加引号写法上既可用于命令行也可写入默认文件的typst-inputs字段实现上由 CommandLineOptions.hs 解析、经 App.hs 传入ReaderOptions最终在 Typst 读取器 的evaluateTypst求值阶段注入sys.inputs。参考仓库测试 test/command/11588.md 与 MANUAL.txt 的规范即可在项目实践中稳定复现同一模板、按参数渲染的工作流。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考