# FFlags 参数解析程序
## 关于FFlags
fflags是基于C语言的命令行参数解析程序，它可以支持解析`unix-like`和`windows`风格的命令行程序。
支持使用子程序，例如`math sub xxx`，其中`sub`即`math`的子程序，不同的子程序可以使用不同的解析方式。
fflags是线程安全的，他不是用全局变量来保存数据。
实际上，fflags不仅可以解析命令行参数，还是以解析任意签名为`int argc, char **agrv`函数的参数。
fflags设计被用于项目`aFun`的命令行参数解析，具体可以参考[aFun on github](https://github.com/aFun-org/aFunlang) 。
## 基本功能
* 针对不同的子程序创建解析语法, 例如`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的宏。
### 定义子程序及其参数解析语法
```c
ff_defArg(<子程序名字>, <是否为default true/false>)
ff_argRule(<短参书 一个字符(无单引号)>, <长参数>, <是否接受参数, not/can/must>, <标识符 int>)
...
ff_endArg(<子程序名字>, <是否为default true/false>);
```
**注意：标识符不建议使用`0`，`-1`以及`-2`。具体见下文。**
例如：
```c
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_`定义：
```c
ff_argRule(<短参书 一个字符(包含单引号)>, <长参数字符串>, <是否接受参数, not/can/must>, <标识符>)
```
### 定义子程序表
将多个子程序汇聚起来，需要定义一个子程序表
```c
ff_childList(<主程序名字>, ff_child(<子程序名字>) ...);
```
### 开始解析参数
#### 解析器的创建与释放
使用`ff_initFFlags(<参数个数>, <参数数组>, <是否忽略第一个参数>, <是否支持斜杠参数>, <错误输出位置>, <主程序名字>)`创建一个解析器，例如：
```c
ff_FFlags *ff = ff_initFFlags(argc, argv, true, false, sys);
```
当该操作返回值为`NULL`时，意味着初始化失败，通常的原因是遇到错误的参数或无适配的子程序。
使用`ff_getChild(<解析器>)`获取匹配的子程序名字。
```c
ff_getChild(ff);
```
参数处理完成后，使用`ff_freeFFlags(<解析器>)`释放解析器，例如：
```c
ff_freeFFlags(ff);
```
#### 解析参数
使用`ff_getopt(<字符串指针>, <解析器>);`读取一个选项参数。若选项参数有附属参数，则该参数存储到字符串指针中。
```c
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(<字符串指针>, <解析器>)`取出非开关参数。
```c
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`构建项目。
```shell
$ mkdir build
$ cd build
$ cmake ..
```
可以通过`-D`选项添加`cmake`参数。
FFlags支持的参数包括：
```
FFLAGS_BUILD_TEST # 是否构建测试项目
SET_OUTPUT_DIRECTORY # 是否重新设定output位置 (当fflags作为子项目时, 请设置为OFF)
```
通常，使用`make`工具编译和安装项目。
```shell
$ make
$ make install
```
亦可使用`CTest`运行测试用例。
经测试，可以为`windows`以及`linux`操作系统中，使用`mingw`, `msvc`, `clang`进行编译。
### 编译目标
编译后可得到`FFlags`动态库，以及`fflags.h`头文件。
使用该库时，将`FFlags`动态库连接到你的程序，并且在程序在包含`fflags.h`头文件即可。
### 作为子项目
可以直接将`FFlags`作为子项目包含到你的项目中, 在`CMakeLists.txt`添加如下代码：
```c
set(FFLAGS_BUILD_TEST OFF)
set(SET_OUTPUT_DIRECTORY OFF)
add_subdirectory(fflags)
```
## 声明
### 免责声明
FFlags为免费开源程序。
编译、运行该程序过程中造成的任何损失（包括但不限于系统损坏、文件丢失）均由您个人承担，与程序的开发者无关。
### LICENSE
FFlags是在 MIT License 下发布的。
FFlags代码归属其代码贡献者。
