takina(A CLI options utility)

Introduction

takina是一个方便CLI应用设置选项(options)而编写的函数库。

由于只有一个源文件，所以可以很简单地引入你的项目！

Usage

添加CLI的使用方式

// For example
takina::AddUsage("./process-name [options]");

添加CLI的描述

takina::AddDescription("...");

上述两个函数没必要按照顺序写，即AddDescription()->AddUsage()编写生成的help是一样的。

添加命令行选项的节(section)

我将分割命令行的标题称为节：

Section title:
-xxx, --xxxx  xxxx
// ...

Section title2:
// ...

takina::AddSection("Section title1");
// set options
takina::AddSection("Section title2");

注意AddSection()是调用位置相关的(call-position-dependent)，因此只有之后设置的选项属于该节。

效果可以看最下面的help信息的输出。

添加命令行选项

takina支持长选项(long option)和短选项(short option)，前者是必须的(required)，而后者是*可选(optional)*的。 表示无短选项用空字符串即可。

takina::AddOption({"", "long-option", ...}, ...);

同时，选项参数支持以下格式：

• 无参(unary)
• 单参(single)
• 固定个数参数(fixed number)
• 多参(multiple)
• 用户自定义参数类型(user-defined)

而支持的参数类型有字符串，整型，浮点数。
在C++中分别用std::string，int(我认为int够用了)，double表示。

其中，help是内置的长选项，help没有短选项，因为我认为-h留给别的选项更好。

无参

无参仅表示该选项用户是否设置，因此用bool型变量表示。

bool has_option;
takina::AddOption({"short-option", "long-option", "description"}, &has_option);

单参:

只接受一个实参。

std::string param;
// OR int param;
// OR double param;
takina::AddOption({"short-option", "long-option", "description", "PARAMETER_NAME"}, &param);

除此之外，也支持给参数指定名称来表示参数的意义或语义（比如单参/多参）

目前仅支持用户自定义选项指定 PARAMETER_NAME 有效，其他选项由库根据选项类型自动生成。

多参

接受不定个数的实参。 如果数目固定，用下面这种参数格式。

takina::MultiParams<std::string> str_params;
takina::AddOption({...}, &str_params);

固定个数的参数

接受固定个数的实参。

int params[2];
takina::AddOption({...}, params, 2);

用户自定义参数

takina通过用户注册的回调解析并设置选项的参数。至于参数个数，合理性等均由用户控制，不由库本身负责。

回调签名(signature of callback)：

/* \param arg argument of the current option
 * \return 
 *  true -- success
 */
typedef std::function<bool(char const *arg)> OptionFunction;

如果传递的实参按用户回调的逻辑不合理，可以返回false表示解析错误。 为了方便检测选项的实参合理性， 允许由用户指定接受的实参个数（AddOption()的第三参数），默认为1，最大为MAX_OPTION_ARGS_NUM，表示无论多少实参都接受。

位置无关的非选项实参（position-independent non-option arguments）

非选项实参是指不应视作选项的实参，而位置无关是指无论它出现在哪都应该被视作非选项实参。e.g.

ssh -p 6000 xxxx@xxxx
# 与下面的命令等价
ssh xxxx@xxxx -p 6000

这里-p的可接受实参个数为1个，因此多出来的被视为非选项实参。

相关函数：

// NOTICE: position省略了
takina::EnableIndependentNonOptionArgument(bool);
takina::GetNonOptionArguments()

Parse

最后，调用takina::Parse()解析命令行参数，返回值表示解析是否成功，如果有错误，那么错误信息会写入第三参数中，比如单参选项实参个数超过1等。

std::string err_msg;
const bool success = takina::Parse(argc, argv, &err_msg);
if (success) {
  takina::Teardown(); // free all the resources used for parse the cmd args
  // do something
} else {
  // do something
  // e.g. print the err_msg
}

如果解析成功，可以调用takina::Teardown()释放用于解析命令行参数的资源，因为不再需要了。

Example/Test

在项目根目录中有一个测试文件，可以编译并运行。

g++ -o takina_test takina_test.cc takina.cc

Run

./takina_test --help

help信息是由该库生成的，其中短选项和长选项的输出行都进行了左对齐，因此较为整齐，结果如下：

Usage: ./takina_test [options]

The program is just a test

Options: 

Information:
     --version                        Display the version information

Parameter set test:
-s , --string <string>                Set string argument
-i , --int <integer>                  Set int argument
-f , --float <float number>           Set floating-point number

Multiple Parameters set test:
-ms, --multi_string <n strings>       Set multiple-string arguments
-mi, --multi_int <n integers>         Set multiple-int arguments
-mf, --multi_float <n float numbers>  Set multiple-floating-point-number arguments

Fixed parameters set test:
-fs, --fixed_string <2 strings>       Set Fixed-string arguments
-fi, --fixed_int <2 integers>         Set Fixed-int arguments
-ff, --fixed_float <2 float numbers>  Set Fixed-floating-point-number arguments
-e , --enum ENUM                      Set enum argument
     --help                           Display the help message