moonman

    Bounded man(7) semantic parser, diagnostics and safe HTML/plain/Markdown rendering

    manpage
    roff
    documentation
    parser
    Download zip
    Version
    0.1.0
    License
    MIT
    Last updated
    7 hours ago
    Downloads
    3

    No dependencies

    #MoonMan

    用纯 MoonBit 解析 man(7) 源文件,生成可检查的语义树、HTML、纯文本和 Markdown。模块:curry20061125/moonman@0.1.0,MIT 许可。

    它面向已有手写 man 手册的 CLI 维护者、文档发布系统和包文档检查工具。你可以把同一份源文件接到网页预览、静态站点导出和不可信文档分析流程,复用字体、段落、定义项、链接和诊断逻辑。需求来自成熟 man 文档工作流及 GNU groff 参考行为;没有声称做过用户访谈。

    #已实现与边界

    • 有界扫描、带引号参数、逐行诊断,TH 元数据及 SH/SS 章节。
    • 段落、显式换行、交替字体、TP/IP/HP 定义项、RS/RE 嵌套缩进。
    • EX/EE、nf/fi 原样文本,SY/YS/OP 命令 synopsis。
    • 常用 roff 字体、字形与 Unicode 标量转义;不展开字符串和寄存器。
    • UR/UE、MT/ME 链接;HTML 文本/属性转义,输出前再次校验链接协议。
    • 可重复的章节锚点、章节切片、手册引用/链接清单、编辑 lint 和文档统计。
    • 输入、行、块、行内节点、缩进和输出资源上限;调用者构造的 AST 也校验。

    这是 man 的语义子集。 不执行通用 troff、mdoc、宏定义、条件、包含文件、shell、表格、方程、寄存器或排版指令。未知请求产生诊断;危险请求产生 Error 且不执行。它不替代 groff 排版引擎,不提供像素或终端列宽一致性。

    #环境与安装

    本版本固定验证 MoonBit v0.10.18+6c83a7f62(2026-10-28)。支持 wasm-gc、wasm、js 和 Linux native。Windows native 需要 MSVC C++ 工具及 Windows SDK;仅有 Moon 工具链不足以编译 Windows native。项目没有第三方模块依赖,只使用 moonbitlang/core。

    在新的消费者目录执行:

    moon new manual-preview cd manual-preview moon add curry20061125/moonman@0.1.0

    在 cmd/main/moon.pkg 的 import 中加入:

    import {
    "curry20061125/moonman",
    }
    options("is-main": true)

    将 cmd/main/main.mbt 替换为:

    fn main raise {
    let source = ".TH TOOL 1\n.SH NAME\ntool \\- inspect records\n.TP\n.B \\-a\nInclude all records.\n"
    let doc = @moonman.parse(source).unwrap()
    assert_false(doc.has_errors())
    println(@moonman.render_html(doc).unwrap())
    println(@moonman.render_markdown(doc).unwrap())
    println(@moonman.render_plain(doc).unwrap())
    for entry in @moonman.outline(doc) {
    println(entry.anchor + ": " + entry.title)
    }
    let stats = @moonman.statistics(doc).unwrap()
    println(stats.blocks)
    }

    moon run cmd/main --target wasm-gc

    生产接入应显式处理 Err(Diagnostic),而非直接 unwrap()。示例为最小可运行流程。

    #错误、限制和接入 API

    parse(source, options~) 返回 Result[Document, Diagnostic]。超过硬限制返回 Err;可恢复的未知/危险请求记录在 Document.diagnostics,解析可能返回 Ok。Ok 不代表内容安全或无错误,发布策略应检查 doc.has_errors()。unknown_is_error: true 可把未知请求提升为 Error。lint(doc) 是额外编辑检查,不修改解析诊断。

    let limits = { ..@moonman.Options::default(), max_chars: 50000, max_blocks: 2000, unknown_is_error: true }
    let result = @moonman.parse(source, options=limits)

    默认上限为 1,000,000 个输入 Unicode 标量、30,000 行、每行 16,000 标量、20,000 块、100,000 行内节点及 64 层/单位缩进。渲染默认输出上限为 2,000,000 标量,宽度为 78(允许 20..240)。渲染和统计对 AST 采用默认 Options 校验;扩大解析限制不自动扩大输出接受范围。

    Span 行列均从 1 开始,计 Unicode 标量;块 span 是粗粒度的行范围,诊断通常定位到控制行,并非逐字符语法树。validate_document 可检查外部构造的 AST。完整公开签名见 pkg.generated.mbti。

    let output = @moonman.render_html(doc, options={ ..@moonman.RenderOptions::default(), standalone: true, max_output_chars: 200000 })
    let toc = @moonman.outline(doc)
    let section = @moonman.section_blocks(doc, "name")
    let manual_refs = @moonman.references(doc)
    let link_inventory = @moonman.links(doc)
    let editorial_issues = @moonman.lint(doc)

    section_blocks 返回标题之后的内容,包含下级章节,遇到同级或更高标题结束;锚点由 outline 获取。引用识别跨字体片段的 name(section),结果按块去重,是词法索引而非外部手册存在性验证。统计中的 words 按空白分词,不是自然语言分词器。

    #三个完整示例

    # CLI 维护者:man 源 -> 完整 HTML 预览,含定义项和代码块 moon run examples/preview # 文档发布者:同一手册 -> Markdown、60 字宽纯文本、目录与选项切片 moon run examples/publish # 包文档检查:不可信请求 -> 诊断、引用、链接清单,验证危险链接不生成锚点 moon run examples/audit

    这些入口内置原创 PACKLIST 手册并带行为断言。库本身不读文件、不访问网络;实际应用负责取得源文本并决定诊断是否阻断发布。

    #验证

    moon info moon fmt --check moon check --deny-warn --target wasm-gc moon build --deny-warn --target wasm-gc moon test --deny-warn --target wasm-gc # 同样对 wasm、js、native 执行 check/build/test 和上面的三个示例 python tools/groff_oracle.py

    独立对照需要 Python 3.8+、GNU groff、col,Windows 通过已有 WSL 调用。Ubuntu 可安装 groff bsdextrautils。7 份原创夹具与 GNU groff 1.23.0 比较正文有序词序列,忽略字体控制、分页、空白和标点,不是全部 man 语义或排版的兼容率。另有 43 项命名测试,其中一个遍历 300 组异常宏组合。CI 固定下载相同官方编译器和 core,在四个后端检查、构建、测试和执行示例。

    工程计量、提交审计及查重范围见 工程审计 和 查重记录。

    #已知限制

    • 支持宏表及恢复策略见 语义范围。未知请求不会展开其请求行;之后的普通行仍作为文本解析。
    • .so、.sy、.de 等从不执行;有 Error 的文档仍可供诊断预览。渲染安全性不等于来源可信。
    • 纯文本按 Unicode 标量换行,不按终端显示单元;长单词不强制切断,不做连字/断词。原样块不自动换行。
    • Markdown 不保留数值缩进和悬挂排版;定义项使用普通段落加 : ,不依赖扩展定义列表;正文 Code 字体退化为普通文字,原样块用防冲突围栏。Markdown 标题的站点锚点策略可能与 outline 不同。
    • HTML 对标签、属性和文本转义,无原始 HTML 通道;宿主网页仍负责 CSP、样式及点击链接的策略。
    • 字形仅常用集合;RE 显式层级、分数宽度及完整 groff 字体/字号语义不支持,会报告诊断或按已说明的语义降级。
    • 没有做性能基准或覆盖率百分比声明。

    #许可、参考和 AI 使用

    代码及原创夹具采用 MIT。本项目独立实现,参考 GNU groff man 宏文档的行为,使用本机 groff 作为外部测试工具,没有复制 GNU GPL 实现或手册正文。相邻 MoonBit 项目仅用于边界比较。依赖、参考及许可边界见 UPSTREAM.md。

    AI 参与了选题研究、代码、测试和文档生成,生成结果经过编译、测试、独立参考对照和人工式逐项审查;未将 AI 输出视为测试证据。维护和评审应以源代码、复现命令及公开 CI 为准。

    Arguments

    pub(all) struct Arguments {
    values : Array[String]
    diagnostics : Array[Diagnostic]
    } derive(Eq,
    Debug
    )

    Arguments::equal

    fn Arguments::equal(Arguments, Arguments) -> Bool
    automatically derived

    Arguments::not_equal

    fn Arguments::not_equal(x : Arguments, y : Arguments) -> Bool
    automatically derived

    Arguments::to_repr

    automatically derived

    Block

    pub(all) struct Block {
    kind : BlockKind
    inlines : Array[Inline]
    indent : Int
    span : Span
    } derive(Eq,
    Debug
    )

    Block::equal

    fn Block::equal(Block, Block) -> Bool
    automatically derived

    Block::not_equal

    fn Block::not_equal(x : Block, y : Block) -> Bool
    automatically derived

    Block::to_repr

    automatically derived

    BlockKind

    pub(all) enum BlockKind {
    Paragraph
    Heading(Int)
    Tagged(Array[Inline])
    Hanging(Int)
    Literal
    Synopsis
    Rule
    } derive(Eq,
    Debug
    )

    BlockKind::equal

    fn BlockKind::equal(BlockKind, BlockKind) -> Bool
    automatically derived

    BlockKind::not_equal

    fn BlockKind::not_equal(x : BlockKind, y : BlockKind) -> Bool
    automatically derived

    BlockKind::to_repr

    automatically derived

    Diagnostic

    pub(all) struct Diagnostic {
    code : String
    message : String
    severity : Severity
    span : Span
    } derive(Eq,
    Debug
    )

    Diagnostic::equal

    fn Diagnostic::equal(Diagnostic, Diagnostic) -> Bool
    automatically derived

    Diagnostic::not_equal

    fn Diagnostic::not_equal(x : Diagnostic, y : Diagnostic) -> Bool
    automatically derived

    Diagnostic::to_repr

    automatically derived

    Document

    pub(all) struct Document {
    metadata : Metadata
    blocks : Array[Block]
    diagnostics : Array[Diagnostic]
    } derive(Eq,
    Debug
    )

    Document::equal

    fn Document::equal(Document, Document) -> Bool
    automatically derived

    Document::has_errors

    fn Document::has_errors(self : Document) -> Bool

    Document::not_equal

    fn Document::not_equal(x : Document, y : Document) -> Bool
    automatically derived

    Document::to_repr

    automatically derived

    DocumentStats

    pub(all) struct DocumentStats {
    blocks : Int
    sections : Int
    definitions : Int
    literal_blocks : Int
    inline_runs : Int
    visible_chars : Int
    words : Int
    link_spans : Int
    unsafe_link_spans : Int
    manual_references : Int
    warnings : Int
    errors : Int
    } derive(Eq,
    Debug
    )

    DocumentStats::equal

    automatically derived

    DocumentStats::not_equal

    fn DocumentStats::not_equal(x : DocumentStats, y : DocumentStats) -> Bool
    automatically derived

    DocumentStats::to_repr

    automatically derived

    Font

    pub(all) enum Font {
    Roman
    Bold
    Italic
    Code
    } derive(Eq,
    Debug
    )

    Public style values are semantic; no terminal escape sequences are emitted.

    Font::equal

    fn Font::equal(Font, Font) -> Bool
    automatically derived

    Font::not_equal

    fn Font::not_equal(x : Font, y : Font) -> Bool
    automatically derived

    Font::to_repr

    automatically derived

    Inline

    pub(all) struct Inline {
    text : String
    font : Font
    target : String?
    } derive(Eq,
    Debug
    )

    Inline::equal

    fn Inline::equal(Inline, Inline) -> Bool
    automatically derived

    Inline::not_equal

    fn Inline::not_equal(x : Inline, y : Inline) -> Bool
    automatically derived

    Inline::text

    fn Inline::text(text : String, font? : Font) -> Inline

    Inline::to_repr

    automatically derived

    InlineResult

    pub(all) struct InlineResult {
    inlines : Array[Inline]
    diagnostics : Array[Diagnostic]
    end_font : Font
    previous_font : Font
    continues : Bool
    } derive(Eq,
    Debug
    )

    InlineResult::equal

    automatically derived

    InlineResult::not_equal

    fn InlineResult::not_equal(x : InlineResult, y : InlineResult) -> Bool
    automatically derived

    InlineResult::to_repr

    automatically derived

    LineKind

    pub(all) enum LineKind {
    Blank
    Text(String)
    Request(String, String)
    Comment
    } derive(Eq,
    Debug
    )

    Control lines retain raw arguments so a caller can inspect unsupported requests.

    LineKind::equal

    fn LineKind::equal(LineKind, LineKind) -> Bool
    automatically derived

    LineKind::not_equal

    fn LineKind::not_equal(x : LineKind, y : LineKind) -> Bool
    automatically derived

    LineKind::to_repr

    automatically derived

    LinkEntry

    pub(all) struct LinkEntry {
    target : String
    label : String
    block_index : Int
    safe : Bool
    } derive(Eq,
    Debug
    )

    LinkEntry::equal

    fn LinkEntry::equal(LinkEntry, LinkEntry) -> Bool
    automatically derived

    LinkEntry::not_equal

    fn LinkEntry::not_equal(x : LinkEntry, y : LinkEntry) -> Bool
    automatically derived

    LinkEntry::to_repr

    automatically derived

    ManualReference

    pub(all) struct ManualReference {
    name : String
    section : String
    block_indices : Array[Int]
    } derive(Eq,
    Debug
    )

    ManualReference::equal

    automatically derived

    ManualReference::not_equal

    fn ManualReference::not_equal(x : ManualReference, y : ManualReference) -> Bool
    automatically derived

    ManualReference::to_repr

    automatically derived

    Metadata

    pub(all) struct Metadata {
    title : String
    section : String
    date : String
    source : String
    manual : String
    } derive(Eq,
    Debug
    )

    Metadata::empty

    fn Metadata::empty() -> Metadata

    Metadata::equal

    fn Metadata::equal(Metadata, Metadata) -> Bool
    automatically derived

    Metadata::not_equal

    fn Metadata::not_equal(x : Metadata, y : Metadata) -> Bool
    automatically derived

    Metadata::to_repr

    automatically derived

    Options

    pub(all) struct Options {
    max_chars : Int
    max_lines : Int
    max_line_chars : Int
    max_blocks : Int
    max_inlines : Int
    max_indent : Int
    unknown_is_error : Bool
    } derive(Eq,
    Debug
    )

    Limits apply to source scalar values and retained AST elements.

    Options::default

    fn Options::default() -> Options

    Options::equal

    fn Options::equal(Options, Options) -> Bool
    automatically derived

    Options::not_equal

    fn Options::not_equal(x : Options, y : Options) -> Bool
    automatically derived

    Options::to_repr

    automatically derived

    OutlineEntry

    pub(all) struct OutlineEntry {
    level : Int
    title : String
    anchor : String
    block_index : Int
    span : Span
    } derive(Eq,
    Debug
    )

    OutlineEntry::equal

    automatically derived

    OutlineEntry::not_equal

    fn OutlineEntry::not_equal(x : OutlineEntry, y : OutlineEntry) -> Bool
    automatically derived

    OutlineEntry::to_repr

    automatically derived

    RenderOptions

    pub(all) struct RenderOptions {
    width : Int
    max_output_chars : Int
    standalone : Bool
    include_title : Bool
    } derive(Eq,
    Debug
    )

    RenderOptions::default

    fn RenderOptions::default() -> RenderOptions

    RenderOptions::equal

    automatically derived

    RenderOptions::not_equal

    fn RenderOptions::not_equal(x : RenderOptions, y : RenderOptions) -> Bool
    automatically derived

    RenderOptions::to_repr

    automatically derived

    Severity

    pub(all) enum Severity {
    Warning
    Error
    } derive(Eq,
    Debug
    )

    Severity::equal

    fn Severity::equal(Severity, Severity) -> Bool
    automatically derived

    Severity::not_equal

    fn Severity::not_equal(x : Severity, y : Severity) -> Bool
    automatically derived

    Severity::to_repr

    automatically derived

    SourceLine

    pub(all) struct SourceLine {
    kind : LineKind
    span : Span
    } derive(Eq,
    Debug
    )

    SourceLine::equal

    fn SourceLine::equal(SourceLine, SourceLine) -> Bool
    automatically derived

    SourceLine::not_equal

    fn SourceLine::not_equal(x : SourceLine, y : SourceLine) -> Bool
    automatically derived

    SourceLine::to_repr

    automatically derived

    Span

    pub(all) struct Span {
    line : Int
    column : Int
    end_line : Int
    end_column : Int
    } derive(Eq,
    Debug
    )

    Positions count Unicode scalar values, with one-based lines and columns.

    Span::equal

    fn Span::equal(Span, Span) -> Bool
    automatically derived

    Span::line_span

    fn Span::line_span(line : Int, length : Int) -> Span

    Span::not_equal

    fn Span::not_equal(x : Span, y : Span) -> Bool
    automatically derived

    Span::to_repr

    automatically derived

    decode_inline

    fn decode_inline(text : String, line? : Int, initial_font? : Font, previous_font? : Font, max_chars? : Int) -> Result[InlineResult, Diagnostic]

    Decode a bounded line of roff text. No string/register interpolation occurs.

    inline_text

    fn inline_text(inlines : Array[Inline]) -> String

    fn links(doc : Document) -> Array[LinkEntry]

    lint

    fn lint(doc : Document) -> Array[Diagnostic]

    Editorial checks are separate from parsing so incomplete documents stay useful.

    outline

    fn outline(doc : Document) -> Array[OutlineEntry]

    Anchors are deterministic and unique even when explicit suffixes collide.

    parse

    fn parse(source : String, options? : Options) -> Result[Document, Diagnostic]

    unsupported requests are located in Document.diagnostics.

    references

    fn references(doc : Document) -> Array[ManualReference]

    Extract conventional name(section) references, including split font runs.

    render_html

    fn render_html(doc : Document, options? : RenderOptions) -> Result[String, Diagnostic]

    Emit escaped, deterministic HTML with no scripts, includes, or raw HTML path.

    render_markdown

    fn render_markdown(doc : Document, options? : RenderOptions) -> Result[String, Diagnostic]

    Conservative CommonMark: escaped prose, fenced literal blocks, safe links. Code font within prose falls back to plain text to avoid delimiter ambiguity.

    render_plain

    fn render_plain(doc : Document, options? : RenderOptions) -> Result[String, Diagnostic]

    Wrap by Unicode scalar count, preserving explicit breaks and literal lines.

    safe_target

    fn safe_target(target : String) -> Bool

    This is an emission policy, not a network reachability or URL ownership check.

    scan

    fn scan(source : String, options? : Options) -> Result[Array[SourceLine], Diagnostic]

    Scan without interpreting or executing any request. CRLF is normalized.

    section_blocks

    fn section_blocks(doc : Document, anchor : String) -> Array[Block]?

    Return the blocks under a heading, stopping before the next peer/ancestor.

    statistics

    fn statistics(doc : Document) -> Result[DocumentStats, Diagnostic]

    Count bounded visible AST content, including definition terms, excluding metadata. Words are whitespace-separated runs, not a language-specific tokenizer.

    tokenize_arguments

    fn tokenize_arguments(raw : String, line? : Int) -> Arguments

    Quotes group whitespace; roff escapes remain intact for inline decoding.

    validate_document

    fn validate_document(doc : Document, limits? : Options) -> Result[Unit, Diagnostic]

    Validation neither edits the document nor treats parser warnings as fatal.