次: Invoking gengetopt, 前: Installation, 上: Top
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>
これらの意味は以下のようになります．
packagePACKAGEに優先します．
versionVERSIONに優先します．
purposelong-)，そしてドット(.)を使用します．スペースは利用
できません．引数を保存するために生成される変数の名前は(このセクションの
後の部分を参照してください)，正当なCの変数名に変換された長いオプション
になります．これは，.と-が両方とも_で置換されるこ
とを意味します．
short-が指定
されている場合，短いオプションは，長いオプションに対するものとは考慮さ
れません(このため，関聯する短いオプションが無い長いオプションが可能にな
ります)．
desc-)，
そしてドット(.)を使用します．最初の文字はスペースにしてはいけま
せん．この記述は，--helpの出力で表示されます．改行は自動的に行わ
れ，\nは改行が要求されているものと解釈されます．
argtypestring，int，short，long，float，
double，longdouble，またはlonglongです．型が指定さ
れていない場合，オプションは引数を受けつけません．
typestr--helpの出力で使用されます
(例えば，単純なSTRINGの代わりに"filename"，単純な
INTの代わりに"portnumber")．
valuesdefaultrequiredyesまたはnoです．これは，そのオプションがプログラムの呼び
出しごとに能える必要があるかどうかを指定します．
argoptional=を使用し，短いオプションの場合はスペースを入れないで下さ
い．例えば，追加の引数があるオプションでは，以下のコマンドラインの構文
を使用して下さい．-B15または--bar=15で，-B 15でも
--bar 15でもありません．
multipleon/offonまたは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.hとcmdline.cを生成します． それ以外では，これらの名前をコマンドラインオプションで指定することが可 能です．
gengetopt < sample1.ggo --file-name=cmdline1 --unamed-opts
オプション--unamed-optsで生成するコマンドライン構文解析器にも名
前を付けることが可能となり，オプションが無い場合(例えば，その前にオプショ
ンが無ければファイル名を渡すことが可能で，そこでは，*.c，
foo*.?などのようなワイルドカードを使用することが可能です)．これ
らはパラメータとも呼ばれています(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>_origはNULLに設定されます．
デフォルトで，生成される関数は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ライブラリからインクルードされてい
ることを仮定しています．InstallationとNo 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が出力されること(typestrがsample1.ggoファ
イルで使用されています)，--my-optの記述が80文字でおりかえされて
いること，そして，\nが実際に改行が要求されていることとして解釈さ
れていることに注目してください．
心配であれば，生成されたCファイルcmdline1.cを見てください．
/prefix/share/doc/gengetopt/examplesや，ソースのtarballの testsで他の例も見つかるでしょう．