GNU Gengetopt 2.10 Usage 隨便翻點東西

GNU Gengetopt 2.10 Usage

需要由gengetopt生成的函數處理的命令行選項在一個文件中指定（該文件的擴展名通常爲 .ggo ）。文件組織爲文本行，格式爲：

package <packname>
version <version>

option <long> <short> <desc> <argtype> {default="<default value>"} <required> {multiple}
option <long> <short> <desc> flag      <onoff>
option <long> <short> <desc> 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 "<group name>" {yes}
groupoption <long> <short> <desc> <argtype> group="<group name>"

如果組被定義爲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選項，那麼除了標準的命令行解析器之外，還會生成另一個解析器（名爲<commandline_parser>_configfile）：

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

配置文件中以#開始的行是註釋，此外的語法如下：

• <option_name> {<option_val>} 意思是如果給出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 <[email protected]>
Report bugs to <[email protected]>

選項的含義應該說的很清楚了，詳細解釋一下：

• 如果不指定--func-name，則使用cmdline_parser作爲默認值。
• 如果指定--long-help選項，"Usage"之後會顯示所有的選項；如果有很多選項就會比較煩人。
• 如果指定--unamed-opts選項，我們就能接受不屬於option的參數，在大多數情況下，這意味着我們可以將文件名傳遞給程序（參見前面sample1 *.h這個例子）。
• 如果指定--no-handle-help（--no-handle-version），就不會自動處理命令行選項--help|-h（--version|-V），這樣程序員就可以輸出其它的信息，而且還可以在隨後調用標準的幫助（版本）輸出函數，該函數名爲<parser-name>_print_help（<parser-name>_print_version），其中<parser-name>是通過--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.

---