用 Rapp 把 R 脚本构建为带参数解析、帮助和子命令的…

在需要用 R 编写命令行工具、给 R 脚本增加参数解析、或将 R 包内脚本发布为 CLI 时，用 Rapp 自动把顶层 R 赋值模式映射为 CLI 参数、帮助与子命令。

适用场景

解决思路

1. 确认 R ≥ 4.1.0；从 CRAN 安装：`install.packages("Rapp")`，或从 GitHub 安装：`r-lib/Rapp`。
2. 安装后把 `Rapp` 启动器加入 PATH：在 R 中执行 `Rapp::install_pkg_cli_apps("Rapp")`；macOS/Linux 会放到 `~/.local/bin`，Windows 会放到 `%LOCALAPPDATA%\Programs\R\Rapp\bin`。
3. 编写普通 R 脚本；Rapp 会扫描脚本的顶层表达式，把特定模式转换为 CLI 构造。同一脚本应能通过 `source()` 和 CLI 一致运行。
4. 在脚本中写正常 R 代码，Rapp 从代码推断 CLI；代码中的默认值成为 CLI 默认值。
5. 只在顶层进行赋值；函数、循环、条件分支内的赋值不会被解析为 CLI 参数。
6. `foo <- "text"` → `--foo <value>`，字符串选项。
7. `foo <- 1L` → `--foo <int>`，整数选项。
8. `foo <- 3.14` → `--foo <float>`，浮点选项。
9. `foo <- TRUE` / `foo <- FALSE` → `--foo` / `--no-foo`，布尔开关。
10. `foo <- NA_integer_` → `--foo <int>`，可选整数（NA 表示未设置）。
11. `foo <- NA_character_` → `--foo <str>`，可选字符串（NA 表示未设置）。
12. `foo <- NULL` → 位置参数，默认必填。
13. `foo... <- NULL` → 可变位置参数，零个或多个值。
14. `foo <- c()` → 可重复 `--foo`，多个值作为字符串。
15. `foo <- list()` → 可重复 `--foo`，多个值按 YAML/JSON 解析。
16. `switch("", cmd1={}, cmd2={})` → 子命令：`app cmd1`、`app cmd2`。
17. `switch(cmd <- "", ...)` → 子命令，并把命令名捕获到 `cmd`。
18. 非字符串标量在 CLI 端按 YAML/JSON 解析，并强制转换为默认值的 R 类型；例如 `n <- 5L` 时，`--n 10` 得到整数 `10L`。
19. 用 NA 默认值表示可选参数；用 `!is.na(myvar)` 判断用户是否提供。
20. 变量名 snake_case 映射为 kebab-case：`n_flips` → `--n-flips`。
21. 位置参数总是以字符串到达；需要手动转换类型。
22. 在脚本第一行加 shebang：`#!/usr/bin/env Rapp`。
23. 在 macOS/Linux 上 `chmod +x` 后脚本可直接执行；在 Windows 上用 `Rapp myscript.R` 显式调用。
24. 在任何代码前用 `#|` 哈希管道注释设置脚本级元数据，如 `#| name: my-app`、`#| title: My App`、`#| description: |` 后接多行 YAML 块。
25. `name:` 字段设置帮助输出中的应用名，默认使用文件名。
26. 把 `#|` 注释紧挨着放在要注解的赋值之前，以添加参数注解。
27. 可用注解字段：`description:`（`--help` 中的帮助文本）、`title:`（子命令和 front matter 的显示标题）、`short:`（单字母别名，如 `'n'` → `-n`）、`required:`（仅位置参数，`true`/`false`）、`val_type:`（覆盖类型：`string`、`integer`、`float`、`bool`、`any`）、`arg_type:`（覆盖 CLI 类型：`option`、`switch`、`positional`）、`action:`（可重复选项：`replace` 或 `append`）。
28. 为常用选项添加 `#| short:`；用户通常期望常见标志有单字母快捷方式，如 verbose `-v`、output `-o`、count `-n`。
29. 标量字面量赋值成为命名选项：`name <- "world"` → `--name <value>`（字符串，默认 `"world"`）；`count <- 1L` → `--count <int>`（整数，默认 `1`）；`threshold <- 0.5` → `--threshold <flt>`（浮点，默认 `0.5`）；`seed <- NA_integer_` → `--seed <int>`（可选，省略时为 NA）；`output <- NA_character_` → `--output <str>`（可选，省略时为 NA）。
30. 对可选参数，判断用户是否提供，例如 `seed <- NA_integer_; if (!is.na(seed)) set.seed(seed)`。
31. `TRUE`/`FALSE` 赋值成为开关：`verbose <- FALSE` → `--verbose` 或 `--no-verbose`；`wrap <- TRUE` → `--wrap`（默认）或 `--no-wrap`。
32. 值 `yes`/`true`/`1` 设为 TRUE；`no`/`false`/`0` 设为 FALSE。
33. 可重复选项：`pattern <- c()` → `--pattern '*.csv' --pattern 'sales-*'` 得到字符向量；`threshold <- list()` → `--threshold 5 --threshold '[10,20]'` 得到解析后的值列表。
34. 位置参数：赋值为 `NULL`，例如 `#| description: The input file to process.` 后 `input_file <- NULL`；默认必填。
35. 用 `#| required: false` 使位置参数可选；用 `is.null(myvar)` 判断是否提供。
36. 可变位置参数：用 `...` 后缀，如 `pkgs... <- c()`；`install-pkgs dplyr ggplot2 tidyr` 得到 `pkgs... = c("dplyr", "ggplot2", "tidyr")`。
37. 用第一个参数为字符串的 `switch()` 声明子命令；`switch()` 之前的选项是全局选项，分支内的选项对子命令局部有效。
38. 子命令示例：`switch(command <- "", list = { limit <- 30L; ... }, add = { task <- NULL; ... }, done = { index <- 1L; ... })`；用 `#| title:` 给分支加标题，用 `#| description:` 给参数加描述。
39. 帮助按范围显示：`myapp --help` 列出命令；`myapp list --help` 显示 list 专属选项加全局选项。
40. 在 `switch()` 分支内再放 `switch()` 可实现嵌套子命令。
41. 每个 Rapp 自动获得 `--help`（人类可读）和 `--help-yaml`（机器可读）；它们也适用于子命令。
42. 在 R 会话中用 `Rapp::run()` 测试脚本：`Rapp::run("path/to/myapp.R", c("--help"))`、`Rapp::run("path/to/myapp.R", c("--name", "Alice", "--count", "5"))`。
43. `Rapp::run()` 会 invisibly 返回求值环境供检查，并支持 `browser()` 进行交互调试。
44. 在包中测试 CLI 应用：用 `Rapp::run()` 配合 `testthat` 快照测试；通过返回的求值环境测试计算值，用 `expect_snapshot()` 测试输出。
45. 详细测试模式见 `references/advanced.md#testing-cli-apps`：通过求值环境访问计算值、对帮助输出和格式化文本做快照测试、测试文件副作用和状态变化。
46. 完整 coin flipper 示例：脚本包含 `#!/usr/bin/env Rapp`、front matter `#| name: flip-coin`、`flips <- 1L` 带 `#| short: 'n'`、`sep <- " "`、`wrap <- TRUE`、`seed <- NA_integer_` 和 `if (!is.na(seed)) set.seed(seed)`，然后 `cat(sample(...), sep = sep, fill = wrap)`；可运行 `flip-coin`、`flip-coin -n 3`、`flip-coin --seed 42 -n 5`、`flip-coin --help`。
47. 完整 todo manager 示例：用 `store <- ".todo.yml"`、`switch(command <- "", list = {...}, add = {...}, done = {...})` 实现子命令；可运行 `todo add "Write quarterly report"`、`todo list`、`todo list --limit 5`、`todo done 1`、`todo --store /tmp/work.yml list`。
48. 在 R 包中发布 CLI：把 CLI 脚本放在 `exec/`，在 DESCRIPTION 的 `Imports` 加入 `Rapp`；目录结构如 `mypkg/` 下有 `DESCRIPTION`、`R/`、`exec/`（含带 shebang 的 `myapp`、`myapp2`）、`man/`。
49. 用户安装包后执行 `Rapp::install_pkg_cli_apps("mypkg")` 来安装 CLI 启动器。
50. 暴露便捷安装函数，让用户不必知道 Rapp：`install_mypkg_cli <- function(destdir = NULL) { Rapp::install_pkg_cli_apps(package = "mypkg", destdir = destdir) }`。
51. 默认启动器设置 `--default-packages=base,<pkg>`，因此只自动加载 `base` 和该包；其他依赖用 `library()` 加载。
52. NA 与 NULL 的区别：NA（`NA_integer_`、`NA_character_`）→ 可选命名选项，判断 `!is.na(x)`；NULL + `#| required: false` → 可选位置参数，判断 `!is.null(x)`。
53. stdin/stdout：`input_file <- NA_character_`；`con <- if (is.na(input_file)) file("stdin") else file(input_file, "r")`；`lines <- readLines(con)`；`writeLines(lines, stdout())`。
54. 退出码和 stderr：`message("Error: something went wrong")` 写到 stderr；`cat("Error:", msg, "\n", file = stderr())` 也写到 stderr；`quit(status = 1)` 返回非零退出码。
55. 错误处理：`tryCatch({ result <- do_work() }, error = function(e) { cat("Error:", conditionMessage(e), "\n", file = stderr()); quit(status = 1) })`。
56. 对不常见主题——启动器定制（`#| launcher:` front matter）、`Rapp::install_pkg_cli_apps()` API 的详细选项、更多完整示例（去重过滤器、可变 install-pkg、交互式回退）——阅读 `references/advanced.md`。

适用边界 · 注意事项

• R 版本低于 4.1.0 或无法安装 Rapp 时。
• 不需要命令行界面，只编写普通 R 脚本或 R 函数时。
• 需要不依赖 Rapp 的通用 CLI 框架或完全自定义参数解析时。