cargs: 一个轻量级跨平台命令行参数解析库

cmake_minimum_required(VERSION 3.1)
project(cargs)

set(CMAKE_C_STANDARD 99)

include_directories(include)

add_library(cargs src/cargs.c)

add_executable(test test/test.c)
target_link_libraries(test cargs)

4.核心数据结构与函数

cargs 的使用围绕选项定义 和参数解析两个核心步骤，关键数据结构和函数如下：

1.选项结构体 cag_option

用于定义一个命令行选项，结构体成员如下：

cpp 复制代码

typedef struct cag_option {
  const char* identifier;  // 长选项名（如 "verbose" 对应 --verbose）
  char short_name;         // 短选项名（如 'v' 对应 -v，0 表示无短选项）
  const char* description; // 选项描述（用于 --help 提示）
  const char* value_name;  // 选项参数名（如 "file" 对应 --output file，NULL 表示无参数）
  int flags;               // 选项标志（目前仅支持 CAG_OPTION_FLAG_REQUIRED，标记为必填项）
} cag_option;

2.解析上下文 cag_context

解析参数后的数据存储结构，用于后续获取选项是否被使用、选项参数值等信息：

cpp 复制代码

typedef struct cag_context {
  // 内部实现细节（用户无需直接修改，通过 API 访问）
} cag_context;

3.核心函数

cag_init：初始化解析上下文

cpp 复制代码

void cag_init(cag_context* context, const cag_option* options, int option_count, int argc, char**argv);

参数：context（上下文指针）、options（选项数组）、option_count（选项数量）、argc/argv（命令行参数）。

-cag_next：迭代解析选项

cpp 复制代码

bool cag_next(cag_context* context);

功能：返回 true 表示解析到下一个选项，false 表示解析结束。

-cag_option_get：获取当前解析到的选项信息。

cpp 复制代码

const cag_option* cag_option_get(const cag_context* context);

-cag_positionals_get：获取位置参数（非选项参数）

cpp 复制代码

int cag_positionals_get(const cag_context* context, const char*** positionals);

返回值：位置参数的数量；positionals：输出位置参数数组。

-cag_print_help：打印自动生成的帮助信息5.

cpp 复制代码

void cag_print_help(const char* program_name, const cag_option* options, int option_count);

5.基本使用示例

以下是一个 C++ 项目中使用 cargs 的示例，实现解析 --verbose（-v）、--output <file>（-o <file>）选项和位置参数：

cpp 复制代码

#include <iostream>
extern "C" {
#include "cargs.h"
}

int main(int argc, char** argv) {
  // 1. 定义选项
  const cag_option options[] = {
    {.identifier = "verbose", .short_name = 'v', 
     .description = "Enable verbose output", .value_name = NULL, .flags = 0},
    {.identifier = "output", .short_name = 'o', 
     .description = "Set output file", .value_name = "file", .flags = 0},
    {.identifier = "help", .short_name = 'h', 
     .description = "Show help", .value_name = NULL, .flags = 0},
  };
  const int option_count = sizeof(options) / sizeof(options[0]);

  // 2. 初始化解析上下文
  cag_context context;
  cag_init(&context, options, option_count, argc, argv);

  // 3. 解析选项
  bool verbose = false;
  const char* output_file = NULL;

  while (cag_next(&context)) {
    const cag_option* option = cag_option_get(&context);
    if (strcmp(option->identifier, "verbose") == 0) {
      verbose = true;
    } else if (strcmp(option->identifier, "output") == 0) {
      output_file = cag_value_get(&context);
    } else if (strcmp(option->identifier, "help") == 0) {
      cag_print_help(argv[0], options, option_count);
      return 0;
    }
  }

  // 4. 解析位置参数
  const char** positionals;
  int positional_count = cag_positionals_get(&context, &positionals);

  // 5. 输出结果
  if (verbose) {
    std::cout << "Verbose mode enabled\n";
  }
  if (output_file) {
    std::cout << "Output file: " << output_file << "\n";
  }
  std::cout << "Positionals (" << positional_count << "):\n";
  for (int i = 0; i < positional_count; ++i) {
    std::cout << "  " << positionals[i] << "\n";
  }

  return 0;
}

编译后运行程序，测试不同参数：

cpp 复制代码

# 显示帮助
./program -h
# 输出：
# Usage: ./program [options]
# Options:
#   -v, --verbose    Enable verbose output
#   -o, --output=file  Set output file
#   -h, --help       Show help

# 带选项和位置参数
./program -v -o result.txt input1.txt input2.txt
# 输出：
# Verbose mode enabled
# Output file: result.txt
# Positionals (2):
#   input1.txt
#   input2.txt

6.应用案例和最佳实践

应用案例通常涉及如何在实际软件开发中有效地利用 cargs 解析复杂的命令行参数。比如，配置工具、自动化脚本、服务部署脚本等场景可以受益于其对长选项、短选项以及带参数的选项的支持。最佳实践中，应保持选项定义清晰，合理使用描述性文本，并在程序入口处提供详细的帮助信息，如 -h 或 --help 选项所示。

cpp 复制代码

if (cag_option_get_identifier(&context) == 'h') {
    printf("Usage: myapp [OPTIONS]\n");
    cag_option_print(options, CAG_ARRAY_SIZE(options), stdout);
    return EXIT_SUCCESS;
}

7.高级用法

1.必填选项：通过 flags = CAG_OPTION_FLAG_REQUIRED 标记选项为必填，解析时若未提供会自动报错。

cpp 复制代码

{.identifier = "input", .short_name = 'i', 
 .description = "Input file (required)", .value_name = "file", 
 .flags = CAG_OPTION_FLAG_REQUIRED}

2.长选项与短选项的优先级：若同时定义了短选项和长选项（如 -v 和 --verbose），解析时两者等效。

3.错误处理：cargs 会自动处理无效选项（如 --invalid），并输出错误提示（如 Unrecognized option: --invalid）。

8.与其他库的对比

库	特点	适用场景
cargs	轻量、单文件、无依赖、功能简单	中小型项目、快速集成
getopt（标准库）	功能基础、跨平台，但语法较繁琐	简单参数解析
Boost.Program_options	功能强大、支持复杂参数，但依赖 Boost	大型 C++ 项目、复杂参数需求

9.总结

cargs 是一个 "够用就好" 的命令行解析库，适合对参数解析需求不复杂、追求轻量和简单集成的项目。如果需要处理复杂的参数逻辑（如子命令、参数校验、类型转换等），可能需要考虑 Boost.Program_options 等更重型的库；但对于多数中小型项目，cargs 足以满足需求。