diff --git a/docs/api.md b/docs/api.md index b2c68d8..b1d32cb 100644 --- a/docs/api.md +++ b/docs/api.md @@ -208,7 +208,8 @@ app.subcommand(cmdline::App("add").description("Add").arg(cmdline::Arg("x").requ ### 生成流程 -1. 从 `App` 构建 `completions::Command` 树(`snapshot(app)` 或自动由 `generate_completions` 调用) +1. 从 `App` 构建 `completions::Command` 树(`snapshot(app)` 或自动由 `generate_completions` 调用)。`snapshot` 是导出的函数(自 0.0.5): + 补全脚本、手册页与工具对自身命令和选项的列举都由同一棵树生成 2. `Command` 包含名称、描述、版本、`Arg`/`Option` 列表、子命令列表 3. 选择目标 `Shell` 后调用 `generate_completions`,输出补全脚本文本 diff --git a/mcpp.toml b/mcpp.toml index f11673c..f57c7e3 100644 --- a/mcpp.toml +++ b/mcpp.toml @@ -1,7 +1,7 @@ [package] namespace = "mcpplibs" name = "cmdline" -version = "0.0.4" +version = "0.0.5" description = "A simple command-line parsing library/framework for modern C++" license = "Apache-2.0" authors = ["mcpplibs"] diff --git a/src/cmdline.cppm b/src/cmdline.cppm index 37a5d16..85c0c86 100644 --- a/src/cmdline.cppm +++ b/src/cmdline.cppm @@ -17,6 +17,12 @@ class SubcommandArgBuilder; class OptBuilder; class ArgBuilder; +export class App; +/// The command tree as declared, with the options the parse adds itself (`-h/--help`, and +/// `--version` when a version is set): what a completion script, a manual page or a tool's +/// listing of its own commands and options is generated from. +export [[nodiscard]] completions::Command snapshot(const App& app); + export using Argv = std::vector; export using detail::Arg; export using detail::Option; @@ -545,7 +551,6 @@ SubcommandBuilder AppItemBuilder::subcommand(std::string_view name) { this->c inline OptBuilder SubcommandBuilder::option(std::string_view name) { return OptBuilder(&sub_, Option(name)); } inline SubcommandArgBuilder SubcommandBuilder::arg(std::string_view name) { return SubcommandArgBuilder(this, Arg(name)); } -/// Rebuild the command tree for shell completions. completions::Command snapshot(const App& app) { completions::Command cmd; cmd.name = app.name_; diff --git a/tests/completions_test.cpp b/tests/completions_test.cpp index f83c325..2a1fb40 100644 --- a/tests/completions_test.cpp +++ b/tests/completions_test.cpp @@ -158,3 +158,25 @@ TEST(Completions, NoSubcommands) { EXPECT_EQ(r.find("_commands"), std::string::npos); } } + +// ----------------------------------------------------------------------------- +// snapshot: the command tree an importer walks +// ----------------------------------------------------------------------------- +TEST(Snapshot, NamesEveryCommandAndOption) { + App app("myapp"); + (void)app.version("1.0"); + (void)app.option(Option("quiet").short_name('q').global()); + (void)app.subcommand(App("cache").subcommand(App("gc").option(Option("dry-run")))); + + const auto tree = snapshot(app); + EXPECT_EQ(tree.name, "myapp"); + std::vector top; + for (const auto& o : tree.options) top.push_back(o.long_name); + EXPECT_EQ(top, (std::vector{"quiet", "help", "version"})); + ASSERT_EQ(tree.subcommands.size(), 1u); + ASSERT_EQ(tree.subcommands[0].subcommands.size(), 1u); + const auto& gc = tree.subcommands[0].subcommands[0]; + EXPECT_EQ(gc.name, "gc"); + ASSERT_FALSE(gc.options.empty()); + EXPECT_EQ(gc.options[0].long_name, "dry-run"); +}