Next: , Previous: Installation, Up: Top


2 基本的な使用方法

gengetoptが生成した関数で処理する必要があるコマンドラインオプションは, ファイル(通常は.ggoの拡張子)で指定します.このファイルは,以下の フォーマットの文で構築し,{}のコマンドはオプションです1

     package <packname>
     version <version>
     
     option <long> <short> <desc> {argtype} {typestr="<type descr>"} \
         {default="<default value>"} {required} {argoptional} {multiple}
     option <long> <short> <desc> {typestr="<type descr>"} \
         {values="value1","value2",...} {default="<default value>"} \
         {required} {argoptional} {multiple}
     option <long> <short> <desc> flag <on/off>

これらの意味は以下のようになります.

package
二重引用符で囲まれた文字列です.これは,autoconfが生成する PACKAGEに優先します.
version
二重引用符で囲まれた文字列です.これは,autoconfが生成する VERSIONに優先します.
purpose
プログラムの目的で(一行以上でもかまいません),ヘルプで出力されます.二 重引用符で囲まれた文字列です.
long
長いオプションで,二重引用符で囲まれた文字列で,大文字と小文字,数字, ダッシュ(-),そしてドット(.)を使用します.スペースは利用 できません.引数を保存するために生成される変数の名前は(このセクションの 後の部分を参照してください),正当なCの変数名に変換された長いオプション になります.これは,.-が両方とも_で置換されるこ とを意味します.
short
短いオプションで,単一の大文字や小文字,または数字です.-が指定 されている場合,短いオプションは,長いオプションに対するものとは考慮さ れません(このため,関聯する短いオプションが無い長いオプションが可能にな ります).
desc
二重引用符で囲まれた文字列で,大文字と小文字,数字,ダッシュ(-), そしてドット(.)を使用します.最初の文字はスペースにしてはいけま せん.この記述は,--helpの出力で表示されます.改行は自動的に行わ れ,\nは改行が要求されているものと解釈されます.
argtype
stringintshortlongfloatdoublelongdouble,またはlonglongです.型が指定さ れていない場合,オプションは引数を受けつけません.
typestr
オプション値の型の記述です.これは,--helpの出力で使用されます (例えば,単純なSTRINGの代わりに"filename",単純な INTの代わりに"portnumber").
values
オプションに渡すことが可能な利用可能なすべての値を含む文字列のリストで す.型は文字列だと考慮され,指定してはなりません.
default
オプションに対する追加のデフォルト値です.値は常に二重引用符で囲まれた 文字列として指定する必要があります.
required
yesまたはnoです.これは,そのオプションがプログラムの呼び 出しごとに能える必要があるかどうかを指定します.
argoptional
このフラグが指定されている場合,このオプションは追加の引数を取ります. この状況では,コマンドラインで引数を指定するとき,長いオプションの使用 時には=を使用し,短いオプションの場合はスペースを入れないで下さ い.例えば,追加の引数があるオプションでは,以下のコマンドラインの構文 を使用して下さい.-B15または--bar=15で,-B 15でも --bar 15でもありません
multiple
このフラグが指定されている場合,このオプションはコマンドラインで一度以 上指定することが可能になります.このオプションのすべての値が配列に保存 されます.Multiple Optionsを参照して下さい.
on/off
onまたはoffです.これは,プログラム開始時のフラグの状態と なります.ユーザがオプション指定している場合,フラグは切替えられます.

コメントは行の任意の場所の#で始まり,行の終わりで終了となります.

オプション-h,--help-V,--versionは自動的に追加されます. 短い形式のhや,長い形式のhelpを独自のオプションとして指定 した場合,追加されません(ヘルプオプションを手動で処理する必要がありま す).-V,--versionも同じです.

オプションはセクションの一部にすることが可能で,オプションのより意味の ある記述を提供します.sectionは以下の構文で定義され (sectiondescはオプションです),,セクション宣言が続くすべてのオ プションは,セクションの一部と考慮されます.

     section "section name" {sectiondesc="optional section description"}

オプションに渡す値のリストを指定することも可能です(その状況では,オプショ ンの型はstringです).値が渡されたリストに無い場合,エラーとなり ます.そのようなオプションは列挙型オプションだと考えることができ ます.

以下は,そのようなファイルの例です(ファイルはsample1.ggoとしま す).

     # file sample1.ggo
     option  "str-opt"     s "A string option, for a filename" \
          string typestr="filename" no
     option  "my-opt"      m "Another integer option, \
          this time the description of the \
          option should be quite long to require wrapping... possibly \
          more than one wrapping :-) especially if I\nrequire a line break" int no
     option  "int-opt"     i "A int option"         int        yes
     section "more involved options" \
          sectiondesc="the following options\nare more complex"
     option  "flag-opt"    - "A flag option"        flag       off
     option  "funct-opt"   F "A function option"    no
     section "last option section"
     option  "long-opt"    - "A long option"        long       no
     option  "def-opt"     - "A string option with default" \
          string default="Hello" no
     option  "enum-opt"    - "A string option with list of values" \
          values="foo","bar","hello" default="hello" no

gengetoptを使用するもっとも簡単な方法は,このファイルを標準入力として渡 す方法です.すなわち以下のようにします.

     gengetopt < sample1.ggo

デフォルトで,gengetoptはcmdline.hcmdline.cを生成します. それ以外では,これらの名前をコマンドラインオプションで指定することが可 能です.

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

オプション--unamed-optsで生成するコマンドライン構文解析器にも名 前を付けることが可能となり,オプションが無い場合(例えば,その前にオプショ ンが無ければファイル名を渡すことが可能で,そこでは,*.cfoo*.?などのようなワイルドカードを使用することが可能です).これ らはパラメータとも呼ばれています(see Terminology).これらの 追加の名前に,追加の記述を指定することが可能です(デフォルトは FILESです).

ファイルcmdline1.hで,生成されるCの構造体を見つけましょう.

     /* cmdline1.h */
     
     /* File autogenerated by gengetopt version 2.14rc  */
     
     #ifndef CMDLINE1_H
     #define CMDLINE1_H
     
     /* If we use autoconf.  */
     #ifdef HAVE_CONFIG_H
     #include "config.h"
     #endif
     
     #ifdef __cplusplus
     extern "C" {
     #endif /* __cplusplus */
     
     #ifndef CMDLINE_PARSER_PACKAGE
     #define CMDLINE_PARSER_PACKAGE "sample1"
     #endif
     
     #ifndef CMDLINE_PARSER_VERSION
     #define CMDLINE_PARSER_VERSION "2.0"
     #endif
     
     struct gengetopt_args_info
     {
       char * str_opt_arg;       /* A string option, for a filename.  */
       char * str_opt_orig;       /* A string option, for a filename original value given at command line.  */
       int my_opt_arg;       /* Another integer option, this time the description of the option should be quite long to require wrapping... possibly more than one wrapping :-) especially if I\nrequire a line break.  */
       char * my_opt_orig;       /* Another integer option, this time the description of the option should be quite long to require wrapping... possibly more than one wrapping :-) especially if I\nrequire a line break original value given at command line.  */
       int int_opt_arg;       /* A int option.  */
       char * int_opt_orig;       /* A int option original value given at command line.  */
       int flag_opt_flag;       /* A flag option (default=off).  */
       long long_opt_arg;       /* A long option.  */
       char * long_opt_orig;       /* A long option original value given at command line.  */
       char * def_opt_arg;       /* A string option with default (default='Hello').  */
       char * def_opt_orig;       /* A string option with default original value given at command line.  */
       char * enum_opt_arg;       /* A string option with list of values (default='hello').  */
       char * enum_opt_orig;       /* A string option with list of values original value given at command line.  */
     
       int help_given ;       /* Whether help was given.  */
       int version_given ;       /* Whether version was given.  */
       int str_opt_given ;       /* Whether str-opt was given.  */
       int my_opt_given ;       /* Whether my-opt was given.  */
       int int_opt_given ;       /* Whether int-opt was given.  */
       int flag_opt_given ;       /* Whether flag-opt was given.  */
       int funct_opt_given ;       /* Whether funct-opt was given.  */
       int long_opt_given ;       /* Whether long-opt was given.  */
       int def_opt_given ;       /* Whether def-opt was given.  */
       int enum_opt_given ;       /* Whether enum-opt was given.  */
     
       char **inputs ; /* unamed options */
       unsigned inputs_num ; /* unamed options number */
     } ;
     
     int cmdline_parser (int argc, char * const *argv, struct gengetopt_args_info *args_info);
     int cmdline_parser2 (int argc, char * const *argv, struct gengetopt_args_info *args_info, int override, int initialize, int check_required);
     int cmdline_parser_file_save(const char *filename, struct gengetopt_args_info *args_info);
     
     void cmdline_parser_print_help(void);
     void cmdline_parser_print_version(void);
     
     void cmdline_parser_init (struct gengetopt_args_info *args_info);
     void cmdline_parser_free (struct gengetopt_args_info *args_info);
     
     int cmdline_parser_required (struct gengetopt_args_info *args_info, const char *prog_name);
     
     extern char *cmdline_parser_enum_opt_values[] ;       /* Possible values for enum-opt.  */
     
     
     #ifdef __cplusplus
     }
     #endif /* __cplusplus */
     #endif /* CMDLINE1_H */
     

<option>_givenフィールドは,<option>の引数が指定されてい るとき,0以外の値が設定されます.オプションが引数を受け入れ, flagの型ではない場合,<option>_argフィールドはコマンドラ インで渡された値に設定されます.<option>_argフィールドは, gengetoptに渡されたファイルで指定されている,対応するCの型を持ちます. 追加のフィールド<option>_origは常に,コマンドラインで渡された元 の値を含む文字列です.これは,例えば数値の引数の状況では異なる可能性が あります.gengetoptは渡された値(文字列)を対応する数値の型に変換します. 変換のため,浮動小数点表現などになり,これは,コマンドラインで渡された 元の値とは正確に一致しない可能性があります.ユーザは, <option>_argの代わりに<option>_origを使用することで,この 元の値にアクセスすることが,足元を見るのと同じくらい,いつでも可能です 2.例えば, gengetopt自身,コマンドラインオプションをファイルに保存するとき,元の値 を使用しています(以下の_file_save関数を参照して下さい).

flagの型の場合,<option>_flagフィールドだけ生成されます.

<option>_givenが0の場合でも,対応する<option>_argはデフォ ルト値になります(<option>が指定されている場合).しかし,この状況 では,<option>_origNULLに設定されます.

デフォルトで,生成される関数はcmdline_parserと呼ばれ(この名前に 優先させる方法は,以下のコマンドラインオプションを参照して下さい), main関数が受け取る引数と,値が充填されている構造体へのポインタを受け取 ります.

cmdline_parser_freeは,文字列と複数回オプションの構文解析器で確 保されたメモリを解放するために呼び出すことが可能です.

この関数の呼び出し後,構文解析関数を呼び出してはならないことに注意して ください.

cmdline_parser_initは,構造体の初期化をするために呼び出すことが 可能です(それは必須ではなく,その理由はコマンドライン構造解析器が自動的 に行うためです).

cmdline_parser_file_save3は,コマンドラインオプションをファイルに保存するために使用する ことが可能です.このファイルの内容は,コンフィグレーションファイル (Configuration files)と両立します.オプションにデフォルト値がある 場合,このオプションではコマンドラインで明示的に渡されたもの(または,コ ンフィグレーションファイルから読み込まれたもの)だけをファイルに保存する ことに注意してください.つまり,デフォルト値はファイルに保存されません.

以下は,これらの関数をmainプログラムで使用する方法を記述しています.

     /* main1.cc */
     /* we try to use gengetopt generated file in a C++ program */
     /* we don't use autoconf and automake vars */
     
     #include <iostream>
     #include "stdlib.h"
     
     #include "cmdline1.h"
     
     using std::cout;
     using std::endl;
     
     int
     main (int argc, char **argv)
     {
       gengetopt_args_info args_info;
     
       cout << "This one is from a C++ program" << endl ;
       cout << "Try to launch me with some options" << endl ;
       cout << "(type sample1 --help for the complete list)" << endl ;
       cout << "For example: ./sample1 *.* --funct-opt" << endl ;
     
       /* let's call our cmdline parser */
       if (cmdline_parser (argc, argv, &args_info) != 0)
         exit(1) ;
     
       cout << "Here are the options you passed..." << endl;
     
       for ( unsigned i = 0 ; i < args_info.inputs_num ; ++i )
         cout << "file: " << args_info.inputs[i] << endl ;
     
       if ( args_info.funct_opt_given )
         cout << "You chose --funct-opt or -F." << endl ;
     
       if ( args_info.str_opt_given )
         cout << "You inserted " << args_info.str_opt_arg << " for " <<
           "--str-opt option." << endl ;
     
       if ( args_info.int_opt_given )
         cout << "This is the integer you input: " <<
           args_info.int_opt_arg << "." << endl;
     
       if (args_info.flag_opt_given)
         cout << "The flag option was given!" << endl;
     
       cout << "The flag is " << ( args_info.flag_opt_flag ? "on" : "off" ) <<
         "." << endl ;
     
       cout << args_info.def_opt_arg << "! ";
     
       cout << "Have a nice day! :-)" << endl ;
     
       cmdline_parser_free (&args_info); /* release allocated memory */
     
       return 0;
     }
     

さて,main1.ccとgengetoptで生成したcmdline1.cをコンパイル し,sample1という実行形式を入手するために,すべてをリンクするこ とが可能となりました.

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

(ここでは,getopt_longが標準Cライブラリからインクルードされてい ることを仮定しています.InstallationNo getopt_longを参照 してください)

さて,このプログラムでテストしてみましょう.

     $ ./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! :-)

たくさんのファイル名をコマンドラインに渡すことも可能です(これでもフラグ の動作方法が分かります).

     $ ./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)を省略してみると,それは必 須なのでエラーになります.

     $ ./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!

以下は,--helpの出力です.

     sample1 2.0
     
     Usage: sample1 -iINT|--int-opt=INT [-h|--help] [-V|--version]
              -sfilename|--str-opt=filename -mINT|--my-opt=INT [--flag-opt]
              [-F|--funct-opt] --long-opt=LONG --def-opt=STRING  [FILES]...
     
       -h, --help              Print help and exit
       -V, --version           Print version and exit
       -s, --str-opt=filename  A string option, for a filename
       -m, --my-opt=INT        Another integer option, this time the description of
                                 the option should be quite long to require
                                 wrapping... possibly more than one wrapping :-)
                                 especially if I
                                 require a line break
       -i, --int-opt=INT       A int option
     
     more involved options:
     the following options
     are more complex
           --flag-opt          A flag option  (default=off)
       -F, --funct-opt         A function option
     
     last option section:
           --long-opt=LONG     A long option
           --def-opt=STRING    A string option with default  (default=`Hello')
           --enum-opt=STRING   A string option with list of values  (possible
                                 values="foo", "bar", "hello" default=`hello')

オプション--str-optに対して,STRINGではなく filenameが出力されること(typestrsample1.ggoファ イルで使用されています),--my-optの記述が80文字でおりかえされて いること,そして,\nが実際に改行が要求されていることとして解釈さ れていることに注目してください.

心配であれば,生成されたCファイルcmdline1.cを見てください.

/prefix/share/doc/gengetopt/examplesや,ソースのtarballの testsで他の例も見つかるでしょう.


脚注

[1] 長す ぎるコマンドラインは複数の行に\で分割します.もちろん,これらの コマンドは,いずれにせよ一行だけであたえることになります.

[2] <option>_origは,リリース2.14で導入されました

[3] この関数はリリース2.14で導入さ れました