FFlags 参数解析程序

关于FFlags

fflags是基于C语言的命令行参数解析程序，它可以支持解析unix-like和windows风格的命令行程序。
支持使用子程序，例如math sub xxx，其中sub即math的子程序，不同的子程序可以使用不同的解析方式。
fflags是线程安全的，他不是用全局变量来保存数据。
实际上，fflags不仅可以解析命令行参数，还是以解析任意签名为int argc, char **agrv函数的参数。

fflags设计被用于项目aFun的命令行参数解析，具体可以参考aFun on github 。

基本功能

• 针对不同的子程序创建解析语法, 例如math sub 10 20中，sub即math的子程序(child)，10和20为sub子程序的参数。
• 有默认子程序，例如设置sub为默认子程序，则math 10 20和math sub 10 20使用相同的方式解析参数。
• 支持unix-like参数
  • 短杠-即短参数，例如-a。
  • 短参数允许多个缩写，例如-abc
  • 双短杠--即长参数，例如--point
  • 短参数和长参数统称为选项，选项后可跟附属参数，例如--point 21
  • --后链接的参数为非开关参数，即不属于选项参数又不是选项参数的附属参数的其他参数。
    • 例如--point 21 22 -- -p 20中，21是point长参数的附属参数，22 -p 20是非开关参数
• 支持windows的斜杠参数
  • 斜杠后只有一个字符的参数即短参数，例如/a。
  • 斜杠后有多于一个字符的参数即长参数，例如/point。

使用方式

在fflags.h文件中，定义了可以简便实用fflags的宏。

定义子程序及其参数解析语法

ff_defArg(<子程序名字>, <是否为default true/false>)
    ff_argRule(<短参书 一个字符(无单引号)>, <长参数>, <是否接受参数, not/can/must>, <标识符 int>)
    ...
ff_endArg(<子程序名字>, <是否为default true/false>);

注意：标识符不建议使用0，-1以及-2。具体见下文。 例如：

ff_defArg(main, true)
    ff_argRule('m', message, not, 1)
    ff_argRule('w', msg2, not, 2)
    ff_argRule('e', msg3, can, 3)
    ff_argRule('r', msg4, must, 4)
ff_endArg(main, true);

如果ff_argRule时，长参数包含空格符，则需要使用ff_argRule_定义：

ff_argRule(<短参书 一个字符(包含单引号)>, <长参数字符串>, <是否接受参数, not/can/must>, <标识符>)

定义子程序表

将多个子程序汇聚起来，需要定义一个子程序表

ff_childList(<主程序名字>, ff_child(<子程序名字>) ...);

开始解析参数

解析器的创建与释放

使用ff_initFFlags(<参数个数>, <参数数组>, <是否忽略第一个参数>, <是否支持斜杠参数>, <错误输出位置>, <主程序名字>)创建一个解析器，例如：

ff_FFlags *ff = ff_initFFlags(argc, argv, true, false, sys);

当该操作返回值为NULL时，意味着初始化失败，通常的原因是遇到错误的参数或无适配的子程序。

使用ff_getChild(<解析器>)获取匹配的子程序名字。

ff_getChild(ff);

参数处理完成后，使用ff_freeFFlags(<解析器>)释放解析器，例如：

ff_freeFFlags(ff);

解析参数

使用ff_getopt(<字符串指针>, <解析器>);读取一个选项参数。若选项参数有附属参数，则该参数存储到字符串指针中。

char *text = NULL;
int mark = ff_getopt(&text, ff);

mark即ff_argRule时定义的标识符，test上的内容即附属参数（若无附属参数则设置为NULL）。
执行ff_getop会沿顺序读取选项参数，跳过非开关参数。

当ff_getop返回值为0时，表示参数解析遭遇错误。
当ff_getop返回值为0或-2时，表示参数解析遭遇错误。
当ff_getop返回-1时，表示选项参数已经全部解析完成。

当ff_getopt返回-1（即所有参数解析完成时），方可调用ff_getopt_wild(<字符串指针>, <解析器>)取出非开关参数。

char *text = NULL;
bool re = ff_getopt_wild(&text, ff);

test上的内容即非开关参数内容。（若读取完成则设置为NULL）。
执行ff_getopt_wild会沿顺序读取非开关参数。

当ff_getopt_wild返回值为false代表非开关参数全部读取完成。
当ff_getopt_wild返回值为true代表非开关参数还未读取完成。
只有选项参数解析完成后，才可解析非开关参数

构建

FFlags使用cmake构建项目。

$ mkdir build
$ cd build
$ cmake ..

可以通过-D选项添加cmake参数。
FFlags支持的参数包括：

FFLAGS_BUILD_TEST  # 是否构建测试项目
SET_OUTPUT_DIRECTORY  # 是否重新设定output位置 (当fflags作为子项目时, 请设置为OFF)

通常，使用make工具编译和安装项目。

$ make
$ make install

亦可使用CTest运行测试用例。
经测试，可以为windows以及linux操作系统中，使用mingw, msvc, clang进行编译。

编译目标

编译后可得到FFlags动态库，以及fflags.h头文件。
使用该库时，将FFlags动态库连接到你的程序，并且在程序在包含fflags.h头文件即可。

作为子项目

可以直接将FFlags作为子项目包含到你的项目中, 在CMakeLists.txt添加如下代码：

set(FFLAGS_BUILD_TEST OFF)
set(SET_OUTPUT_DIRECTORY OFF)
add_subdirectory(fflags)

声明

免责声明

FFlags为免费开源程序。
编译、运行该程序过程中造成的任何损失（包括但不限于系统损坏、文件丢失）均由您个人承担，与程序的开发者无关。

LICENSE

FFlags是在 MIT License 下发布的。
FFlags代码归属其代码贡献者。