友好错误

注意，这还是一个正在进行中的作品，并且非常实验性。

出色的错误消息应该是使用任何语言的体验的核心部分。我们程序员讨厌调试，所以让我们尽可能容易地调试错误。

指导原则

错误消息应该是有用的。为此，它们应该做五件事

1. 清晰简洁。
2. 帮助用户理解出了什么问题
3. 为用户提供解决问题的建议
4. 帮助用户防止未来出现类似问题
5. 如果适用，链接到文档或其他相关信息

这使得用户可以快速了解问题，并希望只需几秒钟就能解决问题。

格式化

以下是错误消息的一般格式

--- Error(E1234): name of the error -------------------------------------------

text explaining the error

    filepath:line:column
    |
 72 | function hello_world() {
    |          ^^^^^^^^^^^

  --> try changing "hello_world" to "helloWorld"

Explanation. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

To learn more, read the docs at https://docs.example.com/

让我们分解一下。

1. 包含一般错误类型和错误代码的大标题。这不仅使用户能够快速识别错误，还有助于对它们进行分类，并让其他人帮助调试错误。水平线有助于分隔连续的错误。
2. 以普通英语解释错误的文本。这应该是清晰和简洁的，但可以尽可能长。通常，它应该尽可能短，但不能更短。
3. 链接到文件路径、行号和列号。这使用户知道错误的确切位置。此外，使用此格式，编辑器（如 VS Code）可以在用户点击该“链接”时跳转到错误位置。
4. 带有行号的代码片段。如果需要，可以添加更多上下文。虽然最重要的是，应该使用胡萝卜 ^ 来突出显示确切的错误位置。
5. 如果可能，建议如何修复错误。这是可选的，但包含它是一个好主意。如果错误是一个快速且容易的修复，这特别有用。
6. 更详细的解释。如果这是一个常见的错误，因为有人使用了来自另一语言（例如，来自 JavaScript）的语法，请在此处解释与其他语言的区别。如果适用，也提供示例。例如，如果错误是关于导入代码的，请提供一些关于如何导入代码的示例。
7. 如果可用，链接到文档或其他相关信息。

用法

要开始，只需将以下内容添加到您的 Cargo.toml 文件中

[dependencies]
friendly-errors = "0.1"

然后，您可以根据需要构建错误消息。这个crate中的每个项目都使用构建器模式

let error_message = FriendlyError::new()
    .title("variable is undefined")
    .code("E1234")
    .add_code_snippet(
        FriendlyCodeSnippet::new()
            .filepath("src/main.rs")
            .contents("let x = foo;")
            .line_start(1)
            .index_start(8)
            .line_end(1)
            .index_end(10)
            .text("let x = foo;")
            .caption("foo is not defined")
    )
    .add_suggestion("Try defining foo before using it. All variables must be defined before they're used.")
    .doc_url("https://github.com/Nick-Mazuk/friendly-errors")
    .build() // returns a Result as to provide errors if not all required fields are set
    .unwrap();

这将生成以下错误消息

--- Error(E1234): variable is undefined ---------------------------------------

    src/main.rs:1:8
    |
 1  | let x = foo;
    |         ^^^

  --> foo is not defined.

Try defining foo before using it. All variables must be defined before they're
used.

To learn more, read the docs at https://github.com/Nick-Mazuk/friendly-errors