GNU Gengetopt 2.10 Usage 随便翻点东西

GNU Gengetopt 2.10 Usage

需要由gengetopt生成的函数处理的命令行选项在一个文件中指定（该文件的扩展名通常为 .ggo ）。文件组织为文本行，格式为：

package 
version 

option     {default=""}  {multiple}
option    flag      
option    no

其中：

package

双引号字符串。优先于autoconf生成的PACKAGE。

version

双引号字符串。优先于autoconf生成的VERSION。

purpose

双引号字符串。程序的功能（可多行），将会出现在输出的帮助中。

long

长选项，双引号字符串。可由大小写字母、数字、'-'和'.'组成，中间不能有空格。依据选项名生成的变量名保存该选项的参数。名字生成规则为：'.'和'-'被替换为'_'，并在最后附加'_arg'或'_flag'。

short

短选项，一个字符，可以为大小写字母或数字。如果该字符为'-'，就表示没有同此行定义的长选项对应的短选项。（也就是说长选项可以没有对应的短选项。）

desc

双引号字符串。 可由大小写字母、数字、'-'和'.'组成，第一个字符不能是空格。

argtype

string、int、short、long、float、double、longdouble或longlong。

default

该选项可选的默认值。该值必须用双引号括起来。

required

yes或no。

multiple

如果标记为multiple，就表示此选项可以出现多次，所有的值被组织在一个数组中。参见“高级特征”一节。

onoff

on或off。为程序启动时该flag的状态。如果用户的命令行上给出此选项，则对应的flag反转。

选项的第三种类型用于不需要任何参数的选项。它决不能是required。

文件中可以使用注释，注释的范围从'#'开始直到行尾。

下面是ggo文件的一个例子（该文件叫做sample1.ggo）
 

# file sample1.ggo option  "str-opt"     s "A string option"      string     no option  "my-opt"      m "Another integer option"      int     no option  "int-opt"     i "A int option"         int        yes option  "flag-opt"    - "A flag option"        flag       off option  "funct-opt"   F "A function option"    no  option  "long-opt"    - "A long option"        long       no option  "def-opt"     - "A string option with default" string default="Hello" no

gengetopt最简单的用法是将输入文件作为标准输入：

gengetopt < sample1.ggo

在默认情况下gengetopt生成 cmdline.h和 cmdline.c。如果你不喜欢，也可以通过命令行选项指定输出的文件名：

gengetopt < sample1.ggo --file-name=cmdline1 --unamed-opts

选项 --unamed-opts使生成的命令行选项解析器接受非选项的名字（例如，你可以直接传递一个文件名而无需将其作为一个选项的参数，还可以使用通配符，如*.c、foo*.?等等）。

在cmdline1.h中你可以发现一个自动生成的C结构gengetopt_args_info：
 

CMDLINE1_H CMDLINE1_H HAVE_CONFIG_H __cplusplus CMDLINE_PARSER_PACKAGE CMDLINE_PARSER_PACKAGE CMDLINE_PARSER_VERSION CMDLINE_PARSER_VERSION gengetopt_args_info str_opt_arg my_opt_arg int_opt_arg flag_opt_flag long_opt_arg def_opt_arg help_given version_given str_opt_given my_opt_given int_opt_given flag_opt_given funct_opt_given long_opt_given def_opt_given inputs inputs_num argc argv gengetopt_args_info args_info __cplusplus

注意，默认情况下生成的函数叫做cmdline_parser（下面给出的命令行选项可以将其命名为其他的名字），参数为main接收的参数和一个指向一个结构体的指针，运行的结果会保存在该结构体中。
在主程序中就可以使用该函数了：
 

argc argv  gengetopt_args_info args_info  cout endl   cout endl   cout endl   cout endl     argc argv args_info       cout endl  i i args_infoinputs_num i     cout args_infoinputsi endl   args_infofunct_opt_given     cout endl   args_infostr_opt_given     cout args_infostr_opt_arg       endl   args_infoint_opt_given     cout         args_infoint_opt_arg endl  args_infoflag_opt_given    cout endl  cout args_infoflag_opt_flag     endl   cout args_infodef_opt_arg   cout endl

现在你可以编译main1.cc和由gengetopt生成的cmdline1.c，然后将它们连接成sample1可执行程序：

gcc -c cmdline1.c
g++ -c main1.cc
g++ -o sample1 cmdline1.o main1.o

（这里我们假设getopt_long被包含在标准C库中）。

现在我们来测试生成的程序：

$ ./sample1 -s "hello" --int-opt 1234
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
Here are the options you passed...
You inserted hello for --str-opt option.
This is the integer you input: 1234.
The flag is off.
Have a nice day! :-)

你也可以在命令行中指定很多文件名（也演示了flag的用法）：

$ ./sample1 *.h -i -100 -x
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
Here are the options you passed...
file: cmdline1.h
file: cmdline2.h
file: cmdline.h
file: getopt.h
This is the integer you input: -100.
The flag is on.
Have a nice day! :-)

如果我们试图省略 --int-opt（或 -i）这个标记为required的选项，我们就会得到一个错误：

$ ./sample1
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
sample1: `--int-opt' (`-i') option required!

如果你好奇，可以看看生成的C文件。

高级特征

选项分组

可以给选项分组；属于同一组的选项是互斥的。如果要使用这个特征，首先需要定义组，然后使用 groupoption定义组选项。组选项同标准选项的语法基本相同，区别是不能使用required标志（因为同一组内的选项是互斥的，所以使用这个标志就不合道理了），另外需要指定该选项所属的 group。

defgroup "" {yes}
groupoption     group=""

如果组被定义为required（其实使用yes标志标识的），则必须在命令行上出现一个（且只有一个）属于该组的选项。

这儿有一个例子（取自于 test_group_cmd.ggo）：

defgroup "my grp2"
defgroup "grp1" yes
groupoption "opta" a "string a" group="grp1"
groupoption "optb" b "string b" group="grp1"
groupoption "optc" - "string c" group="my grp2"
groupoption "optd" d "string d" group="my grp2"

组 grp1被标记为required，所以必须指定 opta、 optb二者之一（且不能全选）。输出为：

$ ./test_groups
gengetopt: 0 options of group grp1 were given. One is required
$ ./test_groups -a          OK
$ ./test_groups -a -b
gengetopt: 2 options of group grp1 were given. One is required
$ ./test_groups -a -c       OK
$ ./test_groups -a --optc -d
gengetopt: 2 options of group my grp2 were given. At most one is required

配置文件

通常，将命令行选项放到配置文件里是一个很有用的特性。这样，如果某些选项没有在命令行上出现，就可以从文件中获得它们的值。如果调用gengetopt时指定了 --conf-parser选项，那么除了标准的命令行解析器之外，还会生成另一个解析器（名为 _configfile）：

int
_configfile (char * const filename,
                              struct gengetopt_args_info *args_info,
                              int override);

配置文件中以 #开始的行是注释，此外的语法如下：

• {} 意思是如果给出option_name，并且该选项接受参数，那么其值为option_val

下面给出了一个使用此特征的例子（ test_conf_parser）：

gengetopt_args_info args_info argc argv argc argv args_info args_infoconf_file_arg args_info args_inforequired_arg args_infostring_arg args_infono_short_given args_infoint_arg args_infofloat_arg

如果我们使用配置文件（ test_conf.conf）

# required option
required "this is a test"
float 3.14
no-short
string another

并这样运行 test_conf_parser，结果为：

./test_conf_parser -r bar -i 100 --conf-file test_conf.conf 
value of required: this is a test
value of string: another
value of no-short: 1
value of int: 100
value of float: 3.140000

multiple选项

如果一个选项被标记为 multiple，则可以在命令行上多次指定此选项。在这种情况下，假定该选项叫做foo，生成 foo_given字段就保存该选项出现的次数，而相应的 foo_arg字段为包含该选项值的数组。

例如，如果gengetopt文件如下：

# test options that can be given more than once option "string"      s "string option" string no multiple option "int"         i "int option" int no multiple

就会采用如下方式接收命令行选项：

gengetopt_args_info args_info argc argv i argc argv args_info i i args_infostring_given i args_infostring_argi i i args_infoint_given i args_infoint_argi

如果采用如下方式调用程序：

./test_multiple -s "foo" -s "bar" -s "hello" -i 100 -i 200 -s "world"

输出为：

passed string: world
passed string: hello
passed string: bar
passed string: foo
passed int: 200
passed int: 100

给Windows用户的提醒

如果你运行Windows，请记住DOS shell不会翻译通配符，因此前面使用' *.h'的例子无法正常运行。

选项

下面是 gengetopt --help的输出：

$ gengetopt --help
gengetopt 2.10

Purpose:
  This program generates a C function that uses getopt_long function
  to parse the command line options, validate them and fill a struct.

Usage: gengetopt [OPTIONS]...
   -h         --help              Print help and exit
   -V         --version           Print version and exit
   -iSTRING   --input=STRING      input file (default std input)
   -fSTRING   --func-name=STRING  name of generated function (default='cmdline_parser')
   -FSTRING   --file-name=STRING  name of generated file (default='cmdline')
   -l         --long-help         long usage line in help
   -u         --unamed-opts       accept filenames
              --no-handle-help    do not handle --help|-h automatically
              --no-handle-version do not handle --version|-V automatically
              --no-handle-error   do not exit on errors 
              --conf-parser         generate a config file parser

Maintained by Lorenzo Bettini 
Report bugs to 

选项的含义应该说的很清楚了，详细解释一下：

• 如果不指定--func-name，则使用cmdline_parser作为默认值。
• 如果指定--long-help选项，"Usage"之后会显示所有的选项；如果有很多选项就会比较烦人。
• 如果指定--unamed-opts选项，我们就能接受不属于option的参数，在大多数情况下，这意味着我们可以将文件名传递给程序（参见前面sample1 *.h这个例子）。
• 如果指定--no-handle-help（--no-handle-version），就不会自动处理命令行选项--help|-h（--version|-V），这样程序员就可以输出其它的信息，而且还可以在随后调用标准的帮助（版本）输出函数，该函数名为_print_help（_print_version），其中是通过--func-name指定的名字或默认的cmdline_parser。
• 如果指定--no-handle-error，解析过程中的错误并不会造成程序退出；由于发生错误时解析器函数会返回非0值，程序可以自己打印帮助信息，就像gengetopt的行为那样（试一下！）。

也许你已经猜到了： gengetopt自己就是用自己生成的函数解析命令行选项的 ，下面是gengetopt使用的ggo文件：
 

purpose "This program generates a C function that uses getopt_long function to parse the command line options, validate them and fill a struct." option  "input"         i "input file. default std input"  string     no option  "func-name"     f "name of generated function"  string default="cmdline_parser" no option  "file-name"     F "name of generated file"  string default="cmdline" no option  "long-help"     l "long usage line in help" no option  "unamed-opts"   u "accept filenames" no option  "no-handle-help"   - "do not handle --help|-h automatically" no  option  "no-handle-version"   - "do not handle --version|-V automatically" no option  "no-handle-error" - "do not exit on errors" no

gengetopt自己使用的生成命令如下：

gengetopt --input=cmdline.ggo --no-handle-version --no-handle-help --no-handle-error

当指定 --help| -h选项时，gengetopt会调用 cmdline_parser_print_help()然后输出报告bug的请求。当指定 --version| -V时，gengetopt会调用 cmdline_parser_print_version()并输出版权信息。
如果发生错误，会输出错误消息到屏幕上：

$ ./gengetopt --zzzz
./gengetopt: unrecognized option `--zzzz'
Run gengetopt --help to see the list of options.

---