Commander-CPP

特性

安装

#include "commander_cpp.hpp"

快速开始

#include "commander_cpp.hpp"
using namespace COMMANDER_CPP;

int main(int argc, char **argv) {
    Command("example")
        .version("1.0.0")
        ->description("一个示例命令行应用")
        ->option("-n --name <name>", "你的名字")
        ->action([](Vector<Variant> args, Map<String, Variant> opts) {
            if (opts.find("name") != opts.end()) {
                std::cout << "Hello, " << std::get<String>(opts["name"]) << "!" << std::endl;
            } else {
                std::cout << "Hello, World!" << std::endl;
            }
        })
        .parse(argc, argv);
    return 0;
}

$ ./example -n Alice
Hello, Alice!

$ ./example --help
Usage: example [options]

一个示例命令行应用

Options:
  -V, --version       out put version number.
  -n, --name <name>   你的名字
  -h, --help

核心概念

选项语法

参数语法

详细用法

1. 定义选项

Command("app")
    .option("-s --single <value>", "单值选项")
    ->option("-m --multi <values...>", "多值选项")
    ->option("-b --boolean", "布尔选项")
    ->option("-n --number <num>", "数字选项", 42)  // 带默认值
    ->action([](Vector<Variant> args, Map<String, Variant> opts) {
        // 获取单值选项
        if (opts.find("single") != opts.end()) {
            auto value = std::get<String>(opts["single"]);
            std::cout << "Single: " << value << std::endl;
        }
        
        // 获取多值选项
        if (opts.find("multi") != opts.end()) {
            auto values = std::get<std::vector<VariantBase>>(opts["multi"]);
            for (const auto &val : values) {
                std::cout << std::get<String>(val) << " ";
            }
            std::cout << std::endl;
        }
        
        // 获取布尔选项
        if (opts.find("boolean") != opts.end()) {
            std::cout << "Boolean enabled" << std::endl;
        }
    });

$ ./app -s value1
$ ./app --single value1
$ ./app -m file1.txt file2.txt file3.txt
$ ./app -b
$ ./app -bs value1  # 组合选项

2. 定义参数

Command("copy")
    .argument("<from>", "源文件")
    ->argument("[to]", "目标文件", "default.txt")  // 带默认值
    ->action([](Vector<Variant> args, Map<String, Variant> opts) {
        auto from = std::get<String>(args[0]);
        std::cout << "From: " << from << std::endl;
        
        if (args.size() > 1) {
            auto to = std::get<String>(args[1]);
            std::cout << "To: " << to << std::endl;
        }
    });

$ ./copy source.txt
$ ./copy source.txt target.txt

3. 定义子命令

    Command cmd("git");

    cmd.version("1.0.0")
    ->description("Git 命令行工具")
    // 添加一个子命令，返回子命令指针，继续链式调用时，是向子命令添加选项或参数
    ->command("add <files...>", "添加文件到暂存区")
    ->option("-f --force", "强制添加")
    ->action([](Vector<Variant> args, Map<String, Variant> opts) {
        auto files = std::get<std::vector<VariantBase>>(args[0]);
        std::cout << "Adding files..." << std::endl;
        for (const auto &file : files) {
            std::cout << "  " << std::get<String>(file) << std::endl;
        }
    });

    // 添加另一个子命令
    cmd.command("commit", "提交更改")
    ->option("-m --message <msg>", "提交信息")
    ->action([](Vector<Variant> args, Map<String, Variant> opts) {
        if (opts.find("message") != opts.end()) {
            auto msg = std::get<String>(opts["message"]);
            std::cout << "Commit: " << msg << std::endl;
        }
    });

$ ./git add file1.txt file2.txt
$ ./git add -f file.txt
$ ./git commit -m "Initial commit"

4. 类型支持

Command("types")
    .option("-i --int <num>", "整数")
    ->option("-d --double <num>", "浮点数")
    ->option("-b --bool <val>", "布尔值")
    ->option("-s --string <text>", "字符串")
    ->action([](Vector<Variant> args, Map<String, Variant> opts) {
        // 自动类型转换
        auto intVal = std::get<int>(opts["int"]);        // 42
        auto doubleVal = std::get<double>(opts["double"]); // 3.14
        auto boolVal = std::get<bool>(opts["bool"]);     // true/false
        auto strVal = std::get<String>(opts["string"]);  // "text"
    });

$ ./types -i 42 -d 3.14 -b true -s hello

5. 自定义日志

class CustomLogger : public Logger {
  public:
    virtual Logger *error(const String &msg) override {
        std::cerr << "[ERROR] " << msg << std::endl;
        return this;
    }
    virtual Logger *warn(const String &msg) override {
        std::cerr << "[WARN] " << msg << std::endl;
        return this;
    }
    virtual Logger *debug(const String &msg) override {
        std::cout << "[DEBUG] " << msg << std::endl;
        return this;
    }
    virtual Logger *print(const String &msg) override {
        std::cout << msg << std::endl;
        return this;
    }
};

int main(int argc, char **argv) {
    CustomLogger logger;
    Command("app", &logger)
        .option("-v --verbose", "详细输出")
        ->parse(argc, argv);
    return 0;
}

6. 选项组合

Command("app")
    .option("-a --option-a", "选项 A")
    ->option("-b --option-b", "选项 B")
    ->option("-c --option-c <value>", "选项 C")
    ->action([](Vector<Variant> args, Map<String, Variant> opts) {
        if (opts.find("option-a") != opts.end()) {
            std::cout << "A enabled" << std::endl;
        }
        if (opts.find("option-b") != opts.end()) {
            std::cout << "B enabled" << std::endl;
        }
    });

$ ./app -ab           # 同时启用 A 和 B
$ ./app -abc value    # 启用 A、B，并为 C 设置值

完整示例

#include "commander_cpp.hpp"
using namespace COMMANDER_CPP;

int main(int argc, char **argv) {
    Command cmd("todo");

    cmd.version("1.0.0")
    ->description("待办事项管理工具")
    
    // 添加子命令
    ->command("add <todos...>", "添加待办事项")
    ->option("-d --done", "标记为已完成")
    ->option("-p --priority", "设置为高优先级")
    ->action([](Vector<Variant> args, Map<String, Variant> opts) {
        auto todos = std::get<std::vector<VariantBase>>(args[0]);
        for (const auto &todo : todos) {
            std::cout << "Added: " << std::get<String>(todo);
            if (opts.find("done") != opts.end()) {
                std::cout << " [DONE]";
            }
            if (opts.find("priority") != opts.end()) {
                std::cout << " [HIGH]";
            }
            std::cout << std::endl;
        }
    });

    cmd.command("rm", "删除待办事项")
    ->argument("<index...>", "待办事项索引")
    ->option("-l --level <value>", "删除级别")
    ->action([](Vector<Variant> args, Map<String, Variant> opts) {
        auto indices = std::get<std::vector<VariantBase>>(args[0]);
        for (const auto &idx : indices) {
            std::cout << "Removed: " << std::get<String>(idx) << std::endl;
        }
    });

    cmd.parse(argc, argv);
    return 0;
}

$ ./todo add "学习 C++" "写代码" -p
Added: 学习 C++ [HIGH]
Added: 写代码 [HIGH]

$ ./todo rm 1 2
Removed: 1
Removed: 2

$ ./todo --help
Usage: todo [options]

待办事项管理工具

Options:
  -V, --version       out put version number.
  -h, --help

Commands:
  add [options] <todos...>  添加待办事项
  rm [options] <index...>   删除待办事项

测试

$ xmake
$ ./build/macosx/arm64/debug/commander-cpp
$ ./build/macosx/arm64/debug/commander-cpp -i  # 显示详细信息

构建

# 安装 xmake
$ brew install xmake

# 构建项目
$ xmake

# 运行测试
$ xmake run commander-cpp

目录结构

commander-cpp/
├── src/
│   ├── commander_cpp.hpp   # 核心库（单头文件）
│   └── main.cpp            # 测试用例
├── build/                  # 构建输出
├── xmake.lua              # 构建配置
└── README.md              # 本文档

注意

未来

贡献

许可证