thag_rs

简介

thag_rs (命令 thag) 是适用于 Rust 表达式、片段和程序的通用脚本运行器和 REPL。它是一个开发者工具，允许您从命令行运行和测试 Rust 代码，以实现快速原型设计和探索。它旨在处理超出 Rust 演示场或普通脚本运行器范围的情况，同时希望使用简单方便。它还支持通过 shebangs 进行脚本编写、从您的片段构建可执行文件、循环过滤模式和纯文本或编辑标准输入。

thag_rs 包含一个超过 170 个示例脚本的演示库。如果您有一些好的内容想要分享，请随时提供，前提是遵守 MIT / Apache 2 许可证条款。

快速入门：运行 thag 命令的方法

* 带表达式参数

thag --expr '"Hello world!"'                                    # Short form: -e

调用静默模式 (--quiet (-q)) 会抑制大部分反馈，除了用于突出显示输出的花盒。调用两次 (-qq 简写) 会抑制所有非错误反馈，包括花盒，使输出可用于过滤。

默认情况下，thag 和 Cargo 将向您反馈

thag -e ' {
use jiff::{Zoned, Unit};
Zoned::now().round(Unit::Second)?
}'                                                              # Long form: --expr

* 使用脚本

thag demo/py_thag.rs

thag demo/iced_tour.rs

这将调用 cargo build 并运行跨平台 GUI 库 iced 的导游。脚本取自 iced 仓库中发布的示例。

要直接运行脚本，您可以在第一行添加类似 #! /usr/bin/env thag 的 shebang。您需要给予脚本执行权限才能运行它。例如 (*nix)

chmod ug+x demo/fib_basic.rs
demo/fib_basic.rs -- 10

但是，为什么要在 shebang 中构建脚本，而不是按照 Rust 的意图将其作为命令呢？请参阅下面的 As an executable。

作为REPL（读取-评估-打印循环）

thag --repl                                                     # Short form: -l

REPL具有文件支持的搜索历史记录，并且可以通过VISUAL或EDITOR环境变量访问VS Code、Zed、Helix、Vim、Nano等图形和基于文本的编辑器，以防其reedline编辑器在某些任务上表现不佳。后者的快捷键将取决于您的终端设置，您可能不需要太多导航快捷键。

带有标准输入

echo '(1..=10).product::<u32>()' | thag --stdin                 # Short form: -s

将脚本的所有参数放在--之后，以将其与thag参数分开

echo 'println!("Hello {}", std::env::args().nth(1).unwrap());' | thag -s -- Ferris

这相当于

thag -e 'println!("Hello {}", std::env::args().nth(1).unwrap());' -- Ferris

使用TUI（终端用户界面）编辑器

thag --edit                                                     # Short form: -d

将标准输入输入到TUI编辑器

cat my_file.rs | thag --edit                                    # Short form: -d

这允许您在提交给thag_rs之前编辑或追加到stdin输入。它具有文件支持的历史记录，这样您就不会丢失您的编辑。

关于TUI编辑器的说明

为了在Apple终端上使Shift-Up和Shift-Down键组合正常工作，您可能需要在Apple终端设置 | 配置文件 | 键盘设置中添加以下内容：Shift-Up: \033;[2A 和 Shift-Down: \033;[2B。使用Esc键生成\033。这在Iterm2或WezTerm中不是必需的。

一般来说，如果您没有遇到您想要的关键绑定，那可能是因为您的终端已经拦截了它们，您可能可以通过调整终端设置来解决这个问题。同样也适用于REPL。

作为标准输入上的过滤器（循环模式）

至少，它将循环遍历stdin，并对每一行运行--loop表达式。行号和内容分别作为i和line提供给表达式。

cat demo/iter.rs | thag --loop 'format!("{i}.\t{line}")' -q    # Short form: -l

注意使用上面的--quiet (-q)选项来抑制Cargo构建的消息。

或者

thag -l 'format!("{i}.\t{line}")' < demo/hello.rs               # Long form: --loop

对于可以将其管道传输到另一个进程的真正过滤器，您可以使用-qq（或--quiet --quiet）来抑制所有非错误输出。

循环模式也接受以下可选参数，提供类似于AWK的代码

--cargo (-C)    for specifying dependencies etc. in Cargo.toml format.
--begin (-B)    for specifying any imports, functions/closures, declarations etc. to be run before the loop.
--end   (-E)    for specifying any summary or final logic to run after the loop.

注意：一般来说，如果您计划将Rust输出管道传输，那么使用writeln!(io::stdout())而不是println!可能是一个好主意，因为截至编写时，如果println!遇到错误（包括来自head命令的broken pipe错误），它将恐慌。有关容忍broken pipe的示例，请参阅demo/thag_from_rust_script.rs。

作为可执行文件

使用--executable (-x)选项以发布模式构建您的脚本并将其移动到~/.cargo/bin/，这是建议将其添加到您的路径中的。

thag -x my_script.rs                                            # Long form: --executable

当然，如果您希望，可以使用操作系统命令重命名可执行文件。

但是，最好首先重命名您的源文件，这样如果您想更新它，就不会丢失跟踪命令来源。

我建议构建可执行文件而不是使用shebang，因为它在几个方面都更快

• 它消除了中间商（thag）
• 您只需在最初承担一次构建开销
• 它将以发布模式构建，使其运行速度更快
• 您可以使用像llvm-strip这样的工具从可执行文件中删除部分

并且在一个方面更加方便：它消除了需要--参数分隔符的需要，因为thag不再首先被调用，因此我们不需要分开两组参数。

投入使用

** 命令行选项

希望帮助屏幕是自我解释的

您可以按任何顺序输入 thag 参数和选项，只要您用 -- 分隔符将它们与任何脚本参数分开。

** 入门指南

您可以选择安装 thag_rs（推荐），或者您可能更喜欢克隆它并自行编译，然后通过 cargo run -- 运行。

• 安装将为您提供开箱即用的速度和更简单的命令行界面，无需自行调用 Cargo。您有选择

cargo install thag_rs

或者从 Github 发布页面选择适合您环境的合适安装程序 https://github.com/durbanlegend/thag_rs/releases，从 v0.1.1 开始。

您还可以从同一页面下载演示脚本的起始套件，作为 demo.zip 下载。

• 克隆为您提供立即访问演示脚本库以及本地更改或分叉的机会。您还可以使用带有环境变量 RUST_LOG=thag_rs=debug 的标志 --features=debug-logs 来获取调试日志。

概述

thag_rs 使用 Cargo、syn、quote 和 cargo_toml 分析并包装良好的片段和表达式，将其转换为可工作的程序。良好的输入程序通过具有有效的 fn main（或一个以上 - 见下文）并保持不变传递给 cargo build。

thag_rs 使用 syn 包将有效代码解析为抽象语法树（AST）。其他好处包括防止它被注释或字符串字面量中的代码所欺骗，这是正则表达式和字符串解析的诅咒。然后，thag_rs 使用 syn 访问者机制遍历 AST 以识别代码中的依赖项，从而生成 Cargo.toml。它过滤这些依赖项以删除重复项和错误信息，如内置 Rust 包、重命名的包和本地模块。

良好性是通过在 AST 中计算 main 函数的任何出现次数来确定的。没有 fn main 的缺失表示一个片段或表达式，而一个以上的 fn main 有时是有效的，但必须通过用户使用 --multimain (-m) 选项来积极标记。

如果您的代码由于编码错误而无法成功解析为 AST，thag_rs 将回退到使用源代码分析为 Rust 编译器准备您的代码，然后 Rust 编译器可以显示错误消息以帮助您找到问题。

您可以根据以下描述在 TOML 块中提供可选的元数据。thag_rs 使用 cargo_toml 包将任何元数据解析到 manifest 结构体中，合并从 AST 推理出的任何依赖项，然后使用 toml 包编写 Cargo 需要构建脚本的专用 Cargo.toml 文件。最后，在代码片段和表达式的案例中，它使用 quote 包将逻辑嵌入到格式良好的程序模板中，然后调用 Cargo 进行构建。

所有这些操作都非常快：真正的瓶颈将是熟悉的 Cargo 构建过程在首次构建时下载和编译您的依赖项。Cargo 构建输出将实时显示，以确保没有神秘的延迟。如果您重新运行编译后的脚本，它应该非常快。

以这种方式，thag_rs 尝试处理任何有效的（或无效的）Rust 脚本，无论是程序、代码片段还是表达式。它将从您的代码中的 use 语句尝试生成针对您的脚本的专用 Cargo.toml，尽管为了速度和精度，我建议您将自定义的嵌入到脚本开头的 toml 块中，就像大多数演示中所做的那样。为此，在每次成功的 Cargo 搜索之后，thag_rs 将生成并打印一个基本的 toml 块，其中包含包名和版本，在 [dependencies] 标题下，供您复制并粘贴到脚本中（如上面的第二个 --expr 示例所示）。它不会打印合并块，因此合并所有依赖项到单个 toml 块的工作由您自己完成。所有依赖项通常可以放在 toml 块下的单个 [dependencies] 标题下，但由于 cargo_toml 的存在，在 toml 块中放置有效 Cargo 代码没有特定的限制。

[toml]
[dependencies]
...
*/

thag_rs 力求在速度和透明度之间取得平衡，尽可能全面。它使用时间戳来重新运行编译后的脚本而无需不必要的重建，尽管您可以覆盖此行为。例如，一个预编译的脚本在我的 M1 MacBook Air 上将在不到半秒内计算出 10,000 的 35,661 位阶乘。

安装

支持的最低 Rust 版本

thag_rs 支持的最低 Rust 版本（MSRV）是 1.74.1。

您可以使用 cargo install 安装 thag_rs。

从 v0.1.1 开始可以下载 demo.zip，地址为 https://github.com/durbanlegend/thag_rs/releases。

cargo install thag_rs

thag -e '(1..=34).product::<u128>()'

thag -e "$(cat demo/fizz_buzz_gpt.rs)"

thag -tq demo/fizz_buzz_gpt.rs
Completed generation in 0.276s
Completed build in 1.171s
----------------------------------------------------------------------
1
2
Fizz
4
Buzz
Fizz
7
8
Fizz
Buzz
11
Fizz
13
14
FizzBuzz
16
...
89
FizzBuzz
91
92
Fizz
94
Buzz
Fizz
97
98
Fizz
Buzz
----------------------------------------------------------------------
Completed run in 0.558s
thag_rs completed processing script fizz_buzz_gpt.rs in 2.43s

thag -r

thag -r repl_<nnnnnn>.rs

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)