#moon-typst

#中文说明

#🌟 项目背景与生态价值

• MoonBit 源码实现：解析、排版与渲染模块以 MoonBit 编写，可构建到 wasm-gc、js 以及 native 目标。
• 文档处理管线：涵盖源码位置跟踪（Span）、词法分析、递归下降解析、脚本求值、盒模型排版，以及 SVG 1.1、PDF 1.4 和 HTML5 输出。
• 可复现实验入口：benchmarks/pipeline_test.mbt 提供分阶段和端到端编译基准，以下列出运行命令、测量口径与实测环境。

#🏗️ 系统架构设计

flowchart LR
    A["Typst 源码 (.typ)"] --> B["词法分析器 (parser/lexer)"]
    B --> C["Token 流 + 源码位置 Span"]
    C --> D["递归下降解析器 (parser/parser)"]
    D --> E["文档 AST (core.Doc)"]
    E --> F["脚本求值与级联样式 (eval)"]
    F --> G["流式几何盒模型引擎 (layout)"]
    G --> H["几何盒模型树 (LayoutBox)"]
    H --> I["PDF 1.4 二进制生成器 (render/pdf)"]
    H --> J["SVG 矢量渲染器 (render/svg)"]
    E --> K["HTML5 语义渲染器 (render/html)"]
    I --> L["标准 PDF 文件 (.pdf)"]
    J --> M["自包含矢量图 (.svg)"]
    K --> N["响应式网页 (.html)"]

#核心包模块职责：

1. core (核心领域模型与 AST)：
   • 定义不可变文档抽象语法树（Doc、Block、Inline、MathExpr）。
   • 度量单位系统 Length（支持 pt、mm、cm、in、em、fr 弹性比例与百分比 %）。
   • 颜色系统 Color（支持 #RRGGBB 十六进制、RGB、HSL 与标准颜色名称）。
   • 图形节点（Rect、Circle、Line）、网格布局（Grid）、脚注（Footnote）与图表（Figure）。
2. diag (源码诊断与高亮报错)：
   • 源码位置跨度（Pos、Span）。
   • 多级别诊断系统（Error、Warning、Hint、Info）。
   • 类似 Rustc/Clang 的 ANSI 彩色终端诊断报告器，带有代码切片、行号、下划波浪线及智能修复提示。
3. eval (Typst 脚本演算与运行时环境)：
   • 动态值系统 Val（数值、字符串、布尔、颜色、长度、几何形状、数组、字典）。
   • 词法作用域管理（Scope、Evaluator）与变量遮蔽机制。
   • 级联样式规则 #set（如 #set text(size: ..., fill: ...) 与 #set page(columns: ...)）。
   • 常用内置排版函数分发（#rect、#circle、#grid、#align 等）。
4. parser (词法与语法分析)：
   • 零回溯词法分析器（Lexer），原生兼容 Windows CRLF 与 UTF-8 BOM。
   • 递归下降语法解析器（Parser），解析复杂行内、块级标记、哈希表达式调用与数学语法。
   • 复杂数学公式语法解析：多行矩阵 mat(...)、列向量 vec(...)、音标重音符 hat、tilde、dot、bar、大型求和与积分记号 sum、int。
5. layout (空间排版与盒模型计算)：
   • 多列页面流（Multi-column Layout）、字宽与行高自适应折行计算。
   • 二维数学基准线平衡算法（根式延长线、分式上下对齐、矩阵格子行列对齐）。
   • 几何盒抽象（LayoutBox、PageLayout、DocumentLayout）。
6. render (多格式矢量后端)：
   • pdf.mbt：MoonBit 实现的 PDF 1.4 生成器，支持间接对象序列化、xref 交叉引用表、Catalog/Pages 树结构、标准 Type1 字体及 PDF 绘制操作流。WinAnsi 可编码的拉丁字符（包括常见重音字母）使用对应 Type1 字体；BMP 非 ASCII 文本其余部分按 Adobe-GB1 的 UniGB-UCS2-H CMap 编码，简体中文仅在该字符集覆盖范围内保证字形，其他未覆盖字符可能显示为空白。混排文本按字体分段，中文使用常规字重。字体不内嵌，显示依赖阅读器的字体资源或替代字体。补充平面字符在 PDF 输出中以 ? 代替。
   • svg.mbt：生成符合 W3C 标准、支持自包含字体样式与平滑线条的 SVG 1.1 矢量图。
   • html.mbt：生成语义化现代科技风响应式 HTML5 网页，内置自适应排版 CSS。
7. cmd/main (跨平台命令行编译工具)：
   • 提供命令行工具，支持参数解析、格式推导与彩色错误诊断输出。

#🚀 语法与排版特性全景图

#管道表格语法

| Target | Status | Notes |
| :--- | :---: | ---: |
| native | supported | SVG/PDF/HTML |
| js | supported | HTML |

#📦 快速上手与使用指南

#1. 作为库引入项目

moon add Lxxbv/moon_typst

{
  "import": [
    "Lxxbv/moon_typst/core",
    "Lxxbv/moon_typst/diag",
    "Lxxbv/moon_typst/eval",
    "Lxxbv/moon_typst/parser",
    "Lxxbv/moon_typst/layout",
    "Lxxbv/moon_typst/render"
  ]
}

import "Lxxbv/moon_typst/parser" as @parser
import "Lxxbv/moon_typst/layout" as @layout
import "Lxxbv/moon_typst/render" as @render
import "Lxxbv/moon_typst/core" as @core

pub fn compile_typst(source : String) -> Unit {
  // 1. 解析源码为 AST
  let doc = @parser.parse_typst(source)

  // 2. 配置样式上下文并计算流式盒模型
  let style = @core.StyleContext::default()
  let engine = @layout.LayoutEngine::new(style)
  let page = engine.layout_doc(doc)

  // 3. 生成 Adobe PDF 1.4 二进制数据
  let pdf_data = @render.render_pdf(page)

  // 4. 生成矢量 SVG 图形
  let svg_data = @render.render_svg(page)

  // 5. 生成语义化 HTML5 页面
  let html_data = @render.render_html(doc)
}

#2. 使用命令行工具 (CLI)

moon build

# 1. 编译为标准 PDF 1.4 二进制文件
moon run cmd/main -- examples/paper.typ -p -o examples/paper.pdf

# 生成包含中文文本的 PDF 示例
moon run cmd/main -- examples/chinese.typ -p -o examples/chinese.pdf

# 2. 编译为矢量 SVG 图形
moon run cmd/main -- examples/paper.typ --svg -o examples/paper.svg

# 3. 编译为响应式 HTML5 网页
moon run cmd/main -- examples/paper.typ --html -o examples/paper.html

# 4. 查看所有选项与帮助信息
moon run cmd/main -- --help

#🔬 官方真实用例套件

1. 学术论文 (examples/paper.typ)：
   • 包含多级标题、数学公式推导（、分式、根式）、系统架构列表。
   • 产物输出：paper.pdf, paper.svg, paper.html。
2. 高等数学论文 (examples/multi_column_paper.typ)：
   • 包含多维矩阵 mat(a, b; c, d)、三维向量 vec(x, y, z)、求和算子 sum、重音符号 hat(theta)、代码块与多格式对比。
   • 产物输出：multi_column_paper.pdf, multi_column_paper.svg, multi_column_paper.html。
3. 幻灯片演示文稿 (examples/presentation.typ)：
   • 包含分页演讲卡片、彩色横幅、三列式架构分解与命令行快速指引。
   • 产物输出：presentation.pdf, presentation.svg, presentation.html。
4. 技术评估报告 (examples/report.typ) 与 专业简历 (examples/resume.typ)。
5. 中文 PDF 示例 (examples/chinese.typ)：展示简体中文 CID 字体路径及其字体替代边界。

#⚡ 性能基准测试 (Micro-benchmarks)

moon version --all
moon bench benchmarks --target native --release --deny-warn
moon bench benchmarks --target wasm-gc --release --deny-warn
moon bench benchmarks --target js --release --deny-warn

#English

#🌟 Project Overview & Ecosystem Value

#📐 Features

• MoonBit Implementation: Parser, layout, and renderer source is written in MoonBit.
• Triple Vector Targets:
  • Adobe PDF 1.4: Direct binary serializer with xref tables, Type1 fonts, and vector drawing operators. WinAnsi-encodable Latin characters, including common accented letters, use the matching Type1 font. Other BMP non-ASCII text uses Adobe-GB1's UniGB-UCS2-H CMap; Simplified Chinese is guaranteed only within that collection's glyph coverage, and other uncovered characters may render blank. Mixed text is split by font; CJK uses a regular STSong-Light face. The font is not embedded, so rendering depends on reader font resources or substitution; supplementary Unicode characters become ?.
  • Scalable Vector Graphics (SVG 1.1): Clean vector elements and font metrics.
  • Semantic HTML5: Responsive CSS styling for web publishing.
• Advanced Mathematical Typesetting:
  • Fractions, square roots, sub/superscript.
  • Multi-dimensional matrices (mat(1, 2; 3, 4)), column vectors (vec(x, y)).
  • Accented characters (hat(x), tilde(y), dot, bar) and limit operators (sum, int).
• Pipe Tables: Pipe-delimited rows with optional outer pipes; a separator after the first row marks the header, and colons select left/center/right alignment. Short rows are padded. Unbordered tables need at least two consecutive rows with matching column counts, or a header separator; use outer pipes for a single-row table. Escaped pipes, merged cells, nested tables, and pagination are not supported.
• Scripting & Evaluation Engine (eval):
  • Variable scopes, constant evaluation, and cascading #set rules (text, page).
• Rich Terminal Diagnostics (diag):
  • Source span tracking, Rustc-style colorized diagnostic reporting with line numbers, code snippets, and hints.
• Reproducible Benchmarks: The benchmark entry point measures individual stages and an in-memory parse/layout/render path for HTML, SVG, and PDF. On the documented Windows and MoonBit toolchain, HTML and SVG averaged below 1 ms on all three targets; PDF averaged 544 µs on wasm-gc, 1.03 ms on native, and 1.06 ms on JS in the recorded run. These are fixture- and machine-specific measurements, not a general latency guarantee; CLI startup and file I/O are excluded. See the Chinese benchmark section for the exact means and ranges; the saved benchmark run contains complete outputs and environment details.

#🧪 Test & CI Coverage

• Unit tests across core, diag, eval, parser, layout, and render.
• GitHub Actions CI matrix testing on Ubuntu, macOS, and Windows.
• Strict formatting and all-target warning checks (moon fmt --check, moon check --target all --deny-warn, moon test --target all --deny-warn).

#📄 License