Yarner

一个语言无关的 Markdown 文献编程工具。Yarner 从为人类编写的结构和文档化的 Markdown 文档中提取代码块，生成可编译的源代码。它提供了足够的功能和灵活性，可以用于包含大量文件和多种语言的较大项目。

Yarner 使用熟悉的语法，可以进一步定制以满足您的需求。请参阅 示例 目录，了解使用不同编程语言的全功能示例。有关文档，请参阅 用户指南。

• 功能
• 安装
• 入门指南
• 配置
• 贡献
• 致谢

功能

• 宏和命名代码块
• 多文件，多个入口点
• 文件包含
• 反转模式
• 自定义插件
• ...

请参阅 用户指南 了解所有功能的完整和详细解释。

安装

预编译的二进制文件

1. 下载适用于您平台的最新二进制文件 （点击此处）
2. 解压到某处
3. 可选： 将可执行文件的父目录添加到您的 PATH 环境变量中

使用 cargo

如果您已安装 Rust，可以使用 cargo 安装

> cargo install yarner

入门指南

要设置新项目，请使用 init 子命令。在您项目的基础目录中运行以下命令：

> yarner init

这将创建一个包含默认设置的 Yarner.toml 文件和一个作为文献编程起点的基础 README.md 文件。

生成的文件已包含一些内容以开始使用 Yarner 的基本功能。有关详细信息，请参阅 用户指南。

要构建项目（提取代码并创建文档），只需运行

> yarner

这将在两个子目录中创建一个，一个包含提取的代码（一个最小但可工作的 Rust 项目），另一个包含最终的文档。

请注意，这些目录的内容可以像平常一样处理，即使用常规编译器编译代码，或将Markdown渲染为HTML或PDF。

示例

宏

宏使可读性程序能够按照逻辑顺序编写以供人类读者阅读。使用Yarner，这是通过命名代码块并在稍后通过“调用”宏来引用它们来实现的。

默认情况下，宏调用以// ==>开头，以句号.结尾。这两个序列都可以根据您的需要进行自定义。唯一限制是宏调用必须是该行上的唯一内容。

在这里，我们有一个未命名的代码块作为入口点，并将两个其他代码块中的“draw”代码绘制到主函数中。这些代码块通过其第一行代码命名，以//-开头。

The program starts in the main function. It calculates something and prints the result:

```rust
fn main() {
    // ==> Calculate something.
    // ==> Print the result.
}
```

The calculation does the following:

```rust
//- Calculate something
let result = 100;
```

Printing the result looks like this:

```rust
//- Print the result
println!("{}", result);
```

渲染的文档看起来像这样

fn main() {
    // ==> Calculate something.
    // ==> Print the result.
}

//- Calculate something
let result = 100;

//- Print the result
println!("{}", result);

生成的代码看起来像这样

fn main() {
    let result = 100;
    println!("{}", result);
}

入口点

默认情况下，程序的入口点是未命名的代码块。但是，可以在Yarner.toml中指定代码块名称或将该名称传递给Yarner的命令行。然后，它将从这个具有该名称的代码块开始，而不是从未命名的代码块开始。

通过以file:前缀命名代码块，后跟一个相对路径，可以从一个源文件创建多个代码文件。具有file:前缀的每个代码块都被视为一个单独的入口点。

```rust
//- file:src/lib.rs
fn say_hello() {
    println!("Hello Literate Programmer!");
}
```

文件包含和链接是进一步的功能，允许有多个代码、文档和/或源文件的项目。

配置

配置通过一个toml配置文件提供（默认：Yarner.toml）。通过init子命令生成具有默认配置的文件。有关详细说明，请参阅用户指南章节配置。

贡献

请使用问题进行错误报告和功能建议。有关问题和一般讨论，请使用讨论。

欢迎提交拉取请求！

致谢

此工具是从foxfriends的工作outline派生出来的。