D 2.0
About Japanese Translation

Last update Sun Dec 19 23:27:26 2010

std.getopt

コマンドラインオプションの解析処理。

getopt モジュールは getopt 関数を実装し、 POSIX形式のコマンドラインオプションを扱います。 GNU拡張は二重ダッシュ("--")で始まる長いオプションという形でサポートされています。 複数のオプションを一つにまとめる機能は、 提供されていますが デフォルトではoffになっています。

Source:
std/getopt.d

License:
Boost License 1.0

Authors:
Andrei Alexandrescu

Credits:
このモジュールとドキュメントは、Perl の Getopt::Long モジュールにインスパイアされました。 D の getopt の構文は、 期待されるパラメータの形式を引数の静的な型から推論できるので、より簡単になっています。

void getopt(T...)(ref string[] args, T opts);
Synopsis:
import std.getopt;

string data = "file.dat";
int length = 24;
bool verbose;

void main(string[] args)
{
  getopt(
    args,
    "length",  &length,    // numeric
    "file",    &data,      // string
    "verbose", &verbose);  // flag
  ...
}
getopt 関数はコマンドライン引数への参照 (main に渡されるもの) を先頭の引数として受け取り、 その後ろに任意個の文字列とポインタのペアを受け取ります。 それぞれの文字列は、続く引数のポインタ ("束縛される"ポインタ) に値を埋めるためのオプションと解釈されます。 getopt のオプションはdashで始めないで下さい。

どの場合でも、getopt によってparseされ使われたコマンドライン引数は args から取り除かれます。 オプションっぽくない形をした引数は全てそのまま args に残るので、その後のプログラムで使用できます。 オプションが指定されなかった値は変更されないので、一般的なイディオムとしては、 まずオプション用の変数をデフォルト値に初期化してから getopt を呼び出すことになります。コマンドライン引数がパラメタ付きのオプションと解釈されたけれど そのパラメタが正しくparseできなかった場合 (例えば 数値が期待されてるオプションに数値がなかった場合)、 ConvException 例外を投げます。

束縛されたポインタの型に応じて、getopt は以下の形式のオプションと解釈します：

  1. フラグオプション。もっともシンプルなオプションです。 単純に、bool変数を true にセットします：


    2.   bool verbose, debugging;
  getopt(args, "verbose", &verbose, "debug", &debugging);
  2. 数値オプション。オプションが数値型に束縛されている場合、 直後に数値があるか、オプション内の "=" 記号で数値が指定されていると解釈されます: 

      uint timeout;
  getopt(args, "timeout", &timeout);
    プログラムを "--timeout=5" または "--timeout 5" というオプションで起動すると、 timeout が 5 に設定されます。


    • インクリメントオプション オプション名が "+" で終わっていて数値型に束縛されている場合、 コマンドライン中にそのオプションが現れた回数がカウントされます: 

        uint paranoid;
  getopt(args, "paranoid+", &paranoid);
      プログラムを "--paranoid --paranoid --paranoid" で起動すると paranoid が 3 に設定されます。 インクリメントオプションはパラメタを指定できないことに注意して下さい。例えば、"--paranoid 42 --paranoid" と書くと "42" が paranoid にセットされるわけではありません。 そうではなく、paranoid は 2 になり、"42" はオプションではないと解釈されます。


  3. 文字列オプション。オプションが文字列に束縛されている場合、 直後に文字列があるか、オプション内の "=" 記号で文字列が指定されていると解釈されます: 

    string outputFile;
getopt(args, "output", &outputFile);
    プログラムを "--output=myfile.txt" や "--output myfile.txt" で起動すると outputFile が "myfile.txt" になります。
    4. 空白文字を含んだ文字列を渡したい場合は、 シェルの文法に従って、例えば --output='my file.txt' のように引用符で囲って下さい。

  4. 配列オプション。オプションが配列に束縛されている場合、 オプションが出現するたびに新しい要素が配列に追加されます: 

    string[] outputFiles;
getopt(args, "output", &outputFiles);
    プログラムを "--output=myfile.txt --output=yourfile.txt" や "--output myfile.txt --output yourfile.txt" で起動すると、outputFiles が [ "myfile.txt", "yourfile.txt" ] にセットされます


  5. ハッシュオプション。オプションが連想配列に束縛されている場合、 直後もしくはオプション内で"="記号に続けて "name=value" の形式が続くと解釈されます: 

    double[string] tuningParms;
getopt(args, "tune", &tuningParms);
    プログラムを例えば "--tune=alpha=0.5 --tune beta=0.6" で起動すると tuningParms が [ "alpha" : 0.5, "beta" : 0.6 ] にセットされます keyとvalueはparse可能な型なら何でも構いません

  6. デリゲートオプション オプションを void delegate()、 void delegate(string option)、 または void delegate(string option, string value) 型に束縛することが可能です。

    • void delegate() の場合、 オプションが見つかった時点でこのdelegateが呼び出されます。
    • void delegate(string option) の場合、 オプション文字列 (からダッシュを除いた物) がdelegateに引き渡されます。 その後、オプション文字列は処理されたと判断され、 配列から削除されます。


      • void main(string[] args)
{
  uint verbosityLevel = 1;
  void myHandler(string option)
  {
    if (option == "quiet")
    {
      verbosityLevel = 0;
    }
    else
    {
      assert(option == "verbose");
      verbosityLevel = 2;
    }
  }
  getopt(args, "verbose", &myHandler, "quiet", &myHandler);
}
    • void delegate(string option, string value)の場合、 オプション文字列は引数を１個とるオプションと解釈され、 そのようにparse処理が行われます。オプションとその値がdelegateに渡り、 その後、delegateに渡された文字列は 配列から削除されます。


      • void main(string[] args)
{
  uint verbosityLevel = 1;
  void myHandler(string option, string value)
  {
    switch (value)
    {
      case "quiet": verbosityLevel = 0; break;
      case "verbose": verbosityLevel = 2; break;
      case "shouting": verbosityLevel = verbosityLevel.max; break;
      default :
        stderr.writeln("Dunno how verbose you want me to be by saying ",
          value);
        exit(1);
    }
  }
  getopt(args, "verbosity", &myHandler);
}


複数の名前を持つオプション

しばしば、オプションに別名をつけたくなることがあります。例えば "--verbose" と "--loquacious" と "--garrulous" に同じ効果を持たせたい場合です。 このような代替オプション名は、 "|" で区切って指定することができます: 

bool verbose;
getopt(args, "verbose|loquacious|garrulous", &verbose);
大文字小文字の区別

デフォルトでは、大文字と小文字は区別されません。この挙動は getopt に caseSensitive を以下のように渡すことで変更できます: 

bool foo, bar;
getopt(args,
    std.getopt.config.caseSensitive,
    "foo", &foo,
    "bar", &bar);
上の例では、"--foo", "--bar", "--FOo", "--bAr" などが全て認識されます。このディレクティブは getoptの最後まで、あるいは逆の意味のディレクティブ caseInsensitive が出現するまで有効です: 

bool foo, bar;
getopt(args,
    std.getopt.config.caseSensitive,
    "foo", &foo,
    std.getopt.config.caseInsensitive,
    "bar", &bar);
オプション "--Foo" は std.getopt.config.caseSensitive によってはじかれますが、 その後また std.getopt.config.caseInsensitive が指定されているので、 "--Bar", "--bAr" などは利用可能です。

"short" 対 "long" オプション

古くは、プログラムはダッシュ一つのあとに一文字、という形式のオプション (例 -t) を受け取るのが通例でした。getopt はそのようなオプションを問題なく扱えます。二つのダッシュ (例 --t) をつけると、一文字オプションは複数文字オプションと同様に振る舞います。 一つのダッシュで使った場合には、一文字オプションとして受理されます。 つまりオプションにパラメタを指定するときには、 間にスペースや"="を挟まず"くっつけて"書かなければいけません。 

uint timeout;
getopt(args, "timeout|t", &timeout);
timeout を 5 にするには、以下の形式のいずれかを使います: --timeout=5, --timeout 5, --t=5, --t 5, or -t5。例えば -t 5 や -timeout=5 は受け付けられません。

shortオプションについてｈの詳細は、次の節をご参照下さい。

Bundling

一文字オプションをまとめる機能です。つまり、"-abc" が "-a -b -c" と同じ意味になります。デフォルトでは、この設定はoffになっています。onにするには std.getopt.config.bundling ディレクティブを使用します: 

bool foo, bar;
getopt(args,
    std.getopt.config.bundling,
    "foo|f", &foo,
    "bar|b", &bar);
一部のパラメタでのみbundlingをonにしたい場合は、std.getopt.config.noBundling で設定をoffに戻します。

認識されなかったオプションの扱い

getopt が扱わなかったオプションをアプリケーションが自力で処理したい場合、std.getopt.config.passThrough ディレクティブを getopt に渡します: 

bool foo, bar;
getopt(args,
    std.getopt.config.passThrough,
    "foo", &foo,
    "bar", &bar);
未認識のオプション (例えば "--baz") は、getopt がreturnした後もそのままargs に残ります。

オプション終了記号

単独の二重ダッシュがあると、そこで getopt がオプションを集めるのを終了します。これは、オプションをその他の引数 (例えば、他のプログラムに渡す別のオプション等) と区別するのに使用されます。上の例を "--foo -- --bar" で起動すると、foo は処理されますが "--bar" はそのまま args に残ります。二重ダッシュそのものはarg配列から取り除かれます。

enum config;
getopt の設定です。 オプション文字列と対応する引数の間でなければ、getopt 関数の何番目の引数として渡しても構いません。

caseSensitive
大文字小文字の区別を on にします

caseInsensitive
大文字小文字の区別を off にします

bundling
bundling を on にします

noBundling
bundling を off にします

passThrough
認識できなかったオプションはそのまま通します

noPassThrough
認識できなかったオプションがあるとエラーとします

stopOnFirstNonOption
オプションとして認識できなかった最初の引数で処理を停止します

dchar optionChar;
オプション指定文字。デフォルトは '-' ですが、 getopt の呼び出し前に別の値に設定することも可能です。

string endOfOptions;
オプション列の終端を表す文字列。 デフォルトは "--" ですが、getopt の呼び出し前に別の値に設定することも可能です。空文字列を endOfOptions に設定すると、この機能が無効化されます。

dchar assignChar;
パラメタ付きオプションで使用される代入記号文字。 デフォルトは '=' ですが getopt の呼び出し前に別の値に設定することも可能です。