代码巡游

简介

本项目试图改进Rust基于示例的学习方法。

想象以下示例文件

#[derive(Debug)]
struct S {
    x: i32,
    y: i32,
}

fn main() {
    // Declare something.
    // Because it's an example.
    let a = S { x: 7, y: 42 };

    let b = a.x + a.y;

    // Here is the result!
    let c = b + 1;
}

当使用 cargo run --example foo 运行示例时，没有任何输出！这意味着示例的作者必须每次都添加 println! 或 dbg! 指令。此外，用户可能会错过注释，这真是太不幸了。

进入 code_tour.

让我们将示例重写如下

use code_tour::code_tour;

#[derive(Debug)]
struct S {
    x: i32,
    y: i32,
}

#[code_tour]
fn main() {
    /// Declare something.
    /// Because it's an example.
    let a = S { x: 7, y: 42 };

    let b = a.x + a.y;

    /// Here is the result!
    let c = b + 1;
}

让我们像以前一样重新执行示例，我们将看到

$ cargo run --example foo

示例注释在执行过程中被复制到输出中。

注释必须是类型为 /// 或 /** … */ 的注释，该注释引入了一个 let 绑定。这就是目前的所有内容！

交互式模式

使用 --features interactive 运行示例后，每次代码执行步骤完成后都会显示“按Enter键继续，否则按Ctrl-C退出。”的消息。

$ cargo run --example foo --features interactive

静默模式

设置环境变量 CODE_TOUR_QUIET 以运行示例，将使 code-tour 变得静默。请注意，它不会禁用交互式模式（这是故意的）。

$ CODE_TOUR_QUIET=1 cargo run --example foo

更好的源代码显示

使用 cargo +nightly 运行示例将使用 Span::source_text 生成更好的代码输出。

$ cargo +nightly run --example foo

安装

这是一个经典的Rust项目，因此将 code_tour 添加到您的 Cargo.toml 文件中，然后就可以了。

许可证

BSD-3-Clause，见 LICENSE.md。