7 Lua语言

本章将总结Quarto的常规操作技术，重点是语法体系。

7.1 markdown相关

7.1.1 callout blocks

参看Callout Blocks语法体系

注记

Note that there are five types of callouts, including: note, tip, warning, caution, and important.

7.2 knitr相关

借助knitr包，quarto文档也可以执行多种命令语言（commandslanguage），例如yaml、bash、stata等。具体可以参看yihui的说明。

例如：执行shell quarto命令：

```{sh}
quarto --version
```

1.6.3

例如：执行shell bash命令：

```{sh}
git --version
```

git version 2.45.1.windows.1

注记

注意我们一定要考虑到工作文档绑定的渲染引擎（engine），例如knitr还是jupyter。具体可以参看quarto说明。

在执行上述bash命令时，两种引擎的代码块是不同的（注意方括号内的指称名称不同）：

```{sh}
# knitr: true
git --version
```

```{bash}
# jupyter: python3
# need python been installed
git --version
```

7.3 CJK字体

pdf格式下CJK字体的设置一直都是一个谜团（见quarto官方说明）。

简单地，可以通过调用LaTex的include-in-header进行字体设定（可能使用别的字体），也可以通过yaml域CJKmainfont: 宋体进行设置（默认为LaTex的xecjk包字体）

pdf:
  documentclass: scrreprt
  CJKmainfont: 宋体
  # CJKmainfont: SimSun #the same
  include-in-header: 
    text: |
      \usepackage{ctex}
      \usepackage{amsthm,mathrsfs}

参考资源：

中文LaTex的xecjk包（见ctan），可以参看文档说明（pdf）
Nan Xiao 的在线图书整理了好用稳定的开源字体集”Open Source Typography” （html在线）

7.4 绘图

7.4.1 Mermaid图形

提示

官方语法说明参看https://mermaid.js.org/
官方样式库可参看https://mermaid.js.org/config/Tutorials.html
在线编译可参看Mermaid Live Editorhttps://mermaid.live/

Quarto原生支mermaid图形代码块，代码块引擎为{mermaid}，注释符号（comment syntax）为%%，代码选项符号（cell options）为%%|

flowchart LR
%% the different edge
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

图 7.1: demo mermaid flowchart

（1）使用Rstudio编写并预览mermaid图形：

Rstudio下编写并保存demo.mmd文件
Rstudio对demo.mmd进行预览，点击Preview

（2）使用Mermaid Live Editor在线编写mermaid图形

编译好.mmd文件后，我们可以直接调用该文件：

sequenceDiagram
  participant Alice
  participant Bob
  Alice->>John: Hello John, how are you?
  loop Healthcheck
    John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts <br/>prevail!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!

图 7.2: demo mermaid of flowchart

7.4.2 Graphviz图形

提示

官方语法说明参看https://graphviz.org/
官方样式库可参看https://graphviz.org/gallery/
在线编译可参看Graphviz Onlinehttps://dreampuf.github.io/GraphvizOnline/

Quarto原生支持Graphviz图形代码块，代码块引擎为{dot}，注释符号（comment syntax）为//，代码选项符号（cell options）为//|。

library("DiagrammeR")

```{dot}
//| label: fig-demo-graphiviz
//| fig-cap: "demo Graphviz of Finite Automaton"
digraph finite_state_machine {
    fontname="Helvetica,Arial,sans-serif"
    node [fontname="Helvetica,Arial,sans-serif"]
    edge [fontname="Helvetica,Arial,sans-serif"]
    rankdir=LR;
    node [shape = doublecircle]; 0 3 4 8;  // comments here
    node [shape = circle];
    0 -> 2 [label = "SS(B)"];
    0 -> 1 [label = "SS(S)"];
    1 -> 3 [label = "S($end)"];
    2 -> 6 [label = "SS(b)"];
    2 -> 5 [label = "SS(a)"];
    2 -> 4 [label = "S(A)"];
    5 -> 7 [label = "S(b)"];
    5 -> 5 [label = "S(a)"];
    6 -> 6 [label = "S(b)"];
    6 -> 5 [label = "S(a)"];
    7 -> 8 [label = "S(b)"];
    7 -> 5 [label = "S(a)"];
    8 -> 6 [label = "S(b)"];
    8 -> 5 [label = "S(a)"];
}
```

图 7.3: demo Graphviz of Finite Automaton

（1）使用Rstudio编写并预览Graphviz图形：

安装DiagrammeR包
Rstudio下编写并保存demo.dot文件
Rstudio对demo.dot进行预览，点击Preview

（2）使用Graphviz Online在线编写Graphviz图形

编译好.dot文件后，我们可以直接调用该文件：

图 7.4: demo Graphviz of Finite Automaton

7.5 Lua相关

7.5.1 学习资源

Lua官方在线教程 Lua 5.4 Reference Manual https://www.lua.org/manual/5.4/
Quarto文档Learning Lua https://quarto.org/docs/extensions/lua.html#learning-lua
(Ierusalimschy 2016) Ierusalimschy, Roberto. Programming in Lua. Fourth edition. Rio de Janeiro: Lua.org, 2016.
(Figueiredo, Celes, 和 Ierusalimschy 2008) Figueiredo, Luiz Henrique de, Waldemar Celes, and Roberto Ierusalimschy. Lua Programming Gems. Rio de Janeiro: Lua.org, 2008.
YiHui在线图书章节Manipulate Markdown via Pandoc Lua filters （见在线图书rmarkdown cookbook）

7.5.2 为什么用Lua？

Lua是一种轻量、高级脚本语言（scripting language）。Pandoc内嵌Lua编译器，从而可以实现对Pandoc运行的良好支持。因此，进一步保障了Quarto插件（extension）无需依赖其他环境（参看quarto文档介绍）。

Lua脚本语言的特点：

是一个独立的C语言库，有独立发行版本
是一种内嵌程序（embedding program），可以独立运行于其他程序之下
是免费的

作为一种基础性脚本语言，Lua同时被其他软件平台使用。例如Pandoc、Quarto都开发了扩展的Lua API（参看Lua API Reference）：

Lua Base API：Lua官方开发的API调用函数
Pandoc Lua API：Pandoc开发的API调用函数
Quarto Lua API：Quarto开发的API调用函数

7.5.3 Lua基础

注记

在Rstudio下使用Quarto自带的Lua编译器可以直接读取.lua脚本（参看Project Scripts）。例如:

quarto run lua/hello.lua

但是会报错：

Error running filter C:\Users\huhua\AppData\Local\Programs\Quarto\share\filters\init\init.lua:
cannot open C:\Users\huhua\AppData\Local\Programs\Quarto\share\filters\init\init.lua: No such file or directory

可能原因：（1）quarto安装模式问题；（2）Lua编译器路径问题（参看队长问答提到的os.getenv("QUARTO_PROJECT_DIR")，以及Pre and Post Render的示例lua脚本代码）

Lua有8种基本类型：nil, boolean, number, string, function, userdata, thread, and table.

7.5.4 Pandoc Lua Filters

Pandoc a universal document converter https://pandoc.org/lua-filters.html

7.5.4.1 pandoc filter过程

Pandoc支持filters来控制摘要语法树（abstract syntax tree， AST）。

Pandoc 2.0以后可以使用Lua编写filters，而不需要其他外部依赖。

7.5.4.2 遍历顺序

默认是topdown，也可以是typewise：

local filter = {
  traverse = 'topdown',
  -- ... filter functions ...
}
return {filter}

类别遍历顺序（Typewise）：

functions for Inline elements,
the Inlines filter function,
functions for Block elements ,
the Blocks filter function,
the Meta filter function, and last
the Pandoc filter function.

当然，也可以明确指定顺序：

-- ... filter definitions ...

return {
  { Meta = Meta },  -- (1)
  { Str = Str }     -- (2)
}

7.5.4.3 全局变量

Pandoc可以将全局变量传送给filters以供后者使用。

7.5.4.4 Padoc 模块

Pandoc Lua模块提供了一系列工具函数，更加方便控制各个要素。

Pandoc Lua模块提供有两类主要工具函数：

要素创造（create）函数，包括Str、Para
pandoc展现（expose）函数，包括walk_block 和 walk_inline函数；read函数；pipe函数；pandoc.mediabag 模块；pandoc.utils模块

7.5.5 Lua应用

7.5.5.1 缩略词

在计量经济学材料整理中，往往会碰到大量的缩略词。例如，最优线性无偏估计量BLUE、两阶段最小二乘法TSLS等。使用quarto渲染qmd文件到多个输出格式（pdf、latex、html），通过Lua编写filter脚本可以使用统一的语法获得多输出一致的缩写效果。

参看1：R in Pharma频道推出的youtube视频 Quarto All the Things! https://www.youtube.com/watch?v=k-dQ36sx4Rk。其中，第二位演讲者Mutaz Jaber介绍了如何实现“缩写符号”的lua实现。