update

Sunrisepeak · Sunrisepeak · commit cf5e43dc985e · 2026-02-23T14:09:42.000+08:00
diff --git a/README.md b/README.md
@@ -1,11 +1,117 @@
 # cmdline
 
-C++23 命令行解析库，API 见名知意，单 import。
+> 基于 C++23 的命令行解析库，API 见名知意，单 import
 
-```bash
-cd cmdline && xmake -P .
-xmake run basic
-xmake -y run cmdline_test   # 测试（-y 自动安装 gtest）
+[English](README.md) - 简体中文
+
+[文档](docs/api.md) - [API 参考](docs/api.md#类型一览) - [示例](examples/)
+
+使用 C++23 模块的类型安全命令行解析库。流式链式接口，零样板代码。支持位置参数、短/长选项、子命令、全局标志，以及基于 `std::expected` 的错误处理。
+
+## ✨ 特性
+
+- **C++23 模块** — `import cmdline`
+
+- **流式接口** — 链式构建方法，所见即所得的 API
+
+- **子命令** — 支持 `action` 回调或手动分发的嵌套命令
+
+- **全局选项** — 标志透明地传播到所有子命令
+
+- **类型安全结果** — `std::expected<ParsedArgs, std::string>`
+
+- **多种解析模式** — 支持 `argc/argv`、`cmdline::Args`（即 `vector<string>`）或原始 `string_view`
+
+## 快速开始
+
+```cpp
+import std;
+import cmdline;
+
+using namespace mcpplibs;
+
+int main(int argc, char* argv[]) {
+    auto app = cmdline::App("myapp")
+        .version("1.0.0")
+        .description("A demo CLI")
+        .arg("input").required().help("输入文件")
+        .option("verbose").short_name('v').help("详细输出")
+        .option("config").short_name('c').takes_value().value_name("FILE").help("配置文件")
+        .action([](const cmdline::ParsedArgs& p) {
+            if (p.is_flag_set("verbose")) std::println("详细模式已开启");
+            if (auto c = p.value("config"))  std::println("配置文件: {}", *c);
+            std::println("输入文件: {}", p.positional(0));
+        });
+
+    auto result = app.parse(argc, argv);
+    if (!result) {
+        if (result.error() == "help requested" || result.error() == "version requested")
+            return 0;
+        std::println("Error: {}", result.error());
+        return 1;
+    }
+    app.run(*result);
+    return 0;
+}
+```
+
+### 子命令 + action / run
+
+```cpp
+auto app = cmdline::App("demo")
+    .version("0.1.0")
+    .description("Demo: subcommands with action dispatch")
+    .option("yes").short_name('y').global().help("自动确认")
+    .subcommand("add")
+        .description("添加目标")
+        .arg("target").required()
+        .arg("version").required()
+        .action([](const cmdline::ParsedArgs& a) {
+            std::println("add: {}@{}", a.value("target").value_or(""),
+                                       a.value("version").value_or(""));
+        })
+    .subcommand("remove")
+        .description("移除目标")
+        .arg("target").required()
+        .action([](const cmdline::ParsedArgs& a) { std::println("remove: {}", a.positional(0)); });
+
+auto result = app.parse(argc, argv);
+if (result) app.run(*result);
 ```
 
-详见 [docs/api.md](docs/api.md)。
+### 多种解析模式
+
+```cpp
+auto r1 = app.parse(argc, argv);
+auto r2 = app.parse_from(cmdline::Args{"myapp", "add", "x", "1.0"});
+auto r3 = app.parse_from("myapp remove x --yes");
+```
+
+## 构建
+
+```shell
+xmake                       # 构建库
+xmake run basic             # 运行基础示例
+xmake -y run cmdline_test   # 运行测试（自动安装 gtest）
+```
+
+## 集成到构建工具
+
+### xmake
+
+```lua
+add_requires("cmdline")
+
+target("mytool")
+    add_packages("cmdline")
+```
+
+### cmake
+
+```
+todo...
+```
+
+## 📄 许可证
+
+Apache-2.0
diff --git a/examples/basic.cpp b/examples/basic.cpp
@@ -1,30 +1,28 @@
 import std;
 import cmdline;
 
-int main(int argc, char* argv[]) {
-    using namespace cmdline;
+using namespace mcpplibs;
 
-    // 1) 定义：程序名、版本、位置参数、选项
-    App app("myapp");
-    app.version("1.0.0")
+int main(int argc, char* argv[]) {
+    auto app = cmdline::App("myapp")
+        .version("1.0.0")
         .description("A demo CLI")
         .arg("input").required().help("Input file")
         .option("verbose").short_name('v').help("Verbose output")
-        .option("config").short_name('c').takes_value().value_name("FILE").help("Config file");
+        .option("config").short_name('c').takes_value().value_name("FILE").help("Config file")
+        .action([](const cmdline::ParsedArgs& p) {
+            if (p.is_flag_set("verbose")) std::println("Verbose on");
+            if (auto c = p.value("config")) std::println("Config: {}", *c);
+            std::println("Input: {}", p.positional(0));
+        });
 
-    // 2) 解析
     auto result = app.parse(argc, argv);
     if (!result) {
         if (result.error() == "help requested" || result.error() == "version requested")
             return 0;
         std::println("Error: {}", result.error());
         return 1;
     }
-
-    // 3) 使用结果
-    const ParsedArgs& p = *result;
-    if (p.is_flag_set("verbose")) std::println("Verbose on");
-    if (auto c = p.value("config")) std::println("Config: {}", *c);
-    std::println("Input: {}", p.positional(0));
+    app.run(*result);
     return 0;
 }
diff --git a/examples/parse_from_string.cpp b/examples/parse_from_string.cpp
@@ -1,22 +1,24 @@
 import std;
 import cmdline;
 
+using namespace mcpplibs;
+
 // 从字符串解析，适合测试或脚本内构造参数
 int main() {
-    using namespace cmdline;
-
-    App app("tool");
-    app.version("1.0")
+    auto app = cmdline::App("tool")
+        .version("1.0")
         .arg("cmd").required()
-        .option("verbose").help("Verbose");
+        .option("verbose").help("Verbose")
+        .action([](const cmdline::ParsedArgs& p) {
+            std::println("cmd = {}", p.positional(0));
+            std::println("verbose = {}", p.is_flag_set("verbose"));
+        });
 
     auto result = app.parse_from("tool add --verbose");
     if (!result) {
         std::println("Parse error: {}", result.error());
         return 1;
     }
-
-    std::println("cmd = {}", result->positional(0));
-    std::println("verbose = {}", result->is_flag_set("verbose"));
+    app.run(*result);
     return 0;
 }
diff --git a/examples/with_dispatch.cpp b/examples/with_dispatch.cpp
@@ -1,27 +1,25 @@
 import std;
 import cmdline;
 
-int main(int argc, char* argv[]) {
-    using namespace cmdline;
+using namespace mcpplibs;
 
-    // 1) 定义：根选项 + 子命令（链式 .subcommand("name").arg/.action）
-    App app("demo");
-    app.version("0.1.0")
+int main(int argc, char* argv[]) {
+    auto app = cmdline::App("demo")
+        .version("0.1.0")
         .description("Demo: parse + run with action")
         .option("yes").short_name('y').global(true).help("Auto confirm")
         .subcommand("add")
             .description("Add a target")
             .arg("target").required()
             .arg("version").required()
-            .action([](const ParsedArgs& args) {
+            .action([](const cmdline::ParsedArgs& args) {
                 std::println("add: {}@{}", args.value("target").value_or(""), args.value("version").value_or(""));
             })
         .subcommand("remove")
             .description("Remove a target")
             .arg("target").required()
-            .action([](const ParsedArgs& args) { std::println("remove: {}", args.positional(0)); });
+            .action([](const cmdline::ParsedArgs& args) { std::println("remove: {}", args.positional(0)); });
 
-    // 2) 解析
     auto result = app.parse(argc, argv);
     if (!result) {
         if (result.error() == "help requested" || result.error() == "version requested")
@@ -30,7 +28,6 @@ int main(int argc, char* argv[]) {
         return 1;
     }
 
-    // 3) 根据解析结果执行对应动作
     app.run(*result);
     return 0;
 }
diff --git a/src/cmdline.cppm b/src/cmdline.cppm
@@ -5,12 +5,14 @@ import std;
 export import :options;
 export import :parse;
 
-namespace cmdline {
+namespace mcpplibs::cmdline {
 
 class SubcommandBuilder;
+class SubcommandArgBuilder;
 class OptBuilder;
 class ArgBuilder;
 
+export using Args = std::vector<std::string>;
 export using detail::Arg;
 export using detail::Option;
 export using detail::OptionValue;
@@ -414,6 +416,7 @@ private:
 
 // 链式子命令构建器：.subcommand("add").description("...").action(...) 或 .subcommand("remove")...
 class SubcommandBuilder {
+    friend class SubcommandArgBuilder;
 public:
     SubcommandBuilder(App* parent, App sub_app) : parent_(parent), sub_(std::move(sub_app)) {}
     SubcommandBuilder(SubcommandBuilder&& other) noexcept
@@ -438,11 +441,18 @@ public:
     SubcommandBuilder& author(std::string_view author_str) { (void)sub_.author(author_str); return *this; }
     SubcommandBuilder& description(std::string_view desc) { (void)sub_.description(desc); return *this; }
     SubcommandBuilder& arg(Arg argument) { (void)sub_.arg(std::move(argument)); return *this; }
-    ArgBuilder arg(std::string_view name);
+    SubcommandArgBuilder arg(std::string_view name);
     SubcommandBuilder& option(Option opt) { (void)sub_.option(std::move(opt)); return *this; }
     OptBuilder option(std::string_view name);
+
+    // Commits this subcommand to the parent App and returns App& to enable further chaining.
     template <typename Fn>
-    SubcommandBuilder& action(Fn&& fn) { (void)sub_.action(std::forward<Fn>(fn)); return *this; }
+    App& action(Fn&& fn) {
+        (void)sub_.action(std::forward<Fn>(fn));
+        App* p = parent_;
+        commit();
+        return *p;
+    }
 
     SubcommandBuilder& subcommand(std::string_view name) {
         commit();
@@ -469,6 +479,42 @@ private:
     bool committed_ = false;
 };
 
+// 子命令内参数链式构建器：保持在 SubcommandBuilder 上下文中，使整条链能正确返回根 App&。
+class SubcommandArgBuilder {
+public:
+    SubcommandArgBuilder(SubcommandArgBuilder&& other) noexcept
+        : sb_(other.sb_), arg_(std::move(other.arg_)), committed_(other.committed_) {
+        other.sb_ = nullptr;
+    }
+    SubcommandArgBuilder& operator=(SubcommandArgBuilder&&) = delete;
+    SubcommandArgBuilder(const SubcommandArgBuilder&) = delete;
+    SubcommandArgBuilder& operator=(const SubcommandArgBuilder&) = delete;
+    ~SubcommandArgBuilder() { commit(); }
+
+    SubcommandArgBuilder& required(bool r = true) { (void)arg_.required(r); return *this; }
+    SubcommandArgBuilder& help(std::string_view h) { (void)arg_.help(h); return *this; }
+    SubcommandArgBuilder& default_value(std::string_view v) { (void)arg_.default_value(v); return *this; }
+
+    SubcommandArgBuilder arg(std::string_view name) { commit(); return sb_->arg(name); }
+
+    template <typename Fn>
+    App& action(Fn&& fn) { commit(); return sb_->action(std::forward<Fn>(fn)); }
+
+private:
+    SubcommandArgBuilder(SubcommandBuilder* sb, Arg a) : sb_(sb), arg_(std::move(a)) {}
+    void commit() {
+        if (sb_ && !committed_) {
+            (void)sb_->sub_.arg(std::move(arg_));
+            committed_ = true;
+        }
+    }
+    SubcommandBuilder* sb_ = nullptr;
+    Arg arg_;
+    bool committed_ = false;
+
+    friend class SubcommandBuilder;
+};
+
 inline SubcommandBuilder App::subcommand(std::string_view name) {
     return SubcommandBuilder(this, App(name));
 }
@@ -493,8 +539,8 @@ inline SubcommandBuilder ArgBuilder::subcommand(std::string_view name) {
 inline OptBuilder SubcommandBuilder::option(std::string_view name) {
     return OptBuilder(&sub_, Option(name));
 }
-inline ArgBuilder SubcommandBuilder::arg(std::string_view name) {
-    return ArgBuilder(&sub_, Arg(name));
+inline SubcommandArgBuilder SubcommandBuilder::arg(std::string_view name) {
+    return SubcommandArgBuilder(this, Arg(name));
 }
 
-} // namespace cmdline
+} // namespace mcpplibs::cmdline
diff --git a/src/options.cppm b/src/options.cppm
@@ -4,7 +4,7 @@ export module cmdline:options;
 
 import std;
 
-namespace cmdline::detail {
+namespace mcpplibs::cmdline::detail {
 
 export struct Arg {
     std::string name;
@@ -80,4 +80,4 @@ export struct Option {
     }
 };
 
-} // namespace cmdline::detail
+} // namespace mcpplibs::cmdline::detail
diff --git a/src/parse.cppm b/src/parse.cppm
@@ -4,7 +4,7 @@ export module cmdline:parse;
 
 import std;
 
-namespace cmdline::detail {
+namespace mcpplibs::cmdline::detail {
 
 /// 选项解析结果：同时表示 flag（用 count）和带值/多值选项（用 values）。
 /// 不用 std::optional<std::string> 的原因：flag 无值且需出现次数；multiple 需多个值。
@@ -62,4 +62,4 @@ export struct ParsedArgs {
     }
 };
 
-} // namespace cmdline::detail
+} // namespace mcpplibs::cmdline::detail
diff --git a/tests/cmdline_test.cpp b/tests/cmdline_test.cpp
