Ariadne

actions-徽章

一个精美的编译器诊断crate。

示例

fn main() {
    use ariadne::{Color, ColorGenerator, Fmt, Label, Report, ReportKind, Source};

    let mut colors = ColorGenerator::new();

    // 为每个元素生成并选择一些颜色
    let a = colors.next();
    let b = colors.next();
    let out = Color::Fixed(81);

    Report::build(ReportKind::Error, "sample.tao", 12)
        .with_code(3)
        .with_message(format!("类型不兼容"))
        .with_label(
            Label::new(("sample.tao", 32..33))
                .with_message(format!("这是 {} 类型", "Nat".fg(a)))
                .with_color(a),
        )
        .with_label(
            Label::new(("sample.tao", 42..45))
                .with_message(format!("这是 {} 类型", "Str".fg(b)))
                .with_color(b),
        )
        .with_label(
            Label::new(("sample.tao", 11..48))
                .with_message(format!(
                    "这些值是此 {} 表达式的输出",
                    "match".fg(out),
                ))
                .with_color(out),
        )
        .with_note(format!(
            "{} 表达式的输出必须强制转换为相同的类型",
            "match".fg(out)
        ))
        .finish()
        .print(("sample.tao", Source::from(include_str!("sample.tao"))))
        .unwrap();
}

更多示例请参见 examples/。

使用方法

对于每个你想要报告的错误：

调用 Report::build() 创建一个 ReportBuilder。
使用各种方法为错误分配适当的细节，然后调用 finish 方法得到一个 Report。
对于每个 Report，调用 print 或 eprint 直接将报告写入 stdout 或 stderr。或者，你可以使用 write 将报告发送到任何其他 Write 目标（如文件）。

关于

ariadne 是 chumsky 的姐妹项目。它们互不依赖，但我同时在开发这两个项目，并认为它们的功能相辅相成。如果你正考虑使用 ariadne 处理编译器的输出，为什么不尝试使用 chumsky 来处理输入呢？

特性

能够处理任意跨度配置的内联和多行标签
多文件错误处理
适用于自定义跨度和文件缓存的泛型
提供多种字符集选择以确保兼容性
带有8位和24位颜色支持的彩色标签和高亮（感谢 yansi）
标签优先级和排序
用于较小诊断的紧凑模式
正确处理变宽字符，如制表符
ColorGenerator 类型，用于为视觉元素生成不同的颜色
大量其他选项（制表符宽度、标签附着点、下划线等）
内置的排序/重叠启发式算法，找出避免重叠和标签交叉的最佳方式

Cargo 特性

"concolor" 启用与 concolor crate 的集成，用于全局控制应用程序的颜色输出
"auto-color" 启用 concolor 的 "auto" 特性，用于自动颜色控制

concolor 的特性应由顶层二进制 crate 定义，但如果不启用任何特性，concolor 不会执行任何操作。如果 ariadne 是你唯一使用 concolor 的依赖项，那么 "auto-color" 提供了一个方便的方式来启用 concolor 的自动颜色支持检测，即：

[dependencies]
ariadne = { version = "...", features = ["auto-color"] }

等同于：

[dependencies]
ariadne = { version = "...", features = ["concolor"] }
concolor = { version = "...", features = ["auto"] }

计划中的特性

改进布局规划和空间利用
非ANSI终端支持
更多无障碍选项（屏幕阅读器友好模式、作为颜色替代的纹理高亮等）
更多颜色选项
更好地支持布局限制（例如，最大终端宽度）

稳定性

API（应该）遵循 semver。然而，这不适用于最终错误消息的布局。对内部布局启发式算法的微小调整通常会导致错误消息的确切格式发生变化，标签可能会略有移动。如果你遇到了你认为是退化的布局变化（变化不正确，或使你的诊断更难阅读），请开一个 issue。

致谢

感谢：

@brendanzab 为他们美丽的 codespan crate，它激发了我尝试推动错误诊断的极限。
@estebank 通过他们在 Rust 上的工作，向无数人展示了编译器诊断可以有多好。