"getopt" --- C 形式のコマンドラインオプション解析
*************************************************

**ソースコード:** Lib/getopt.py

注釈:

  このモジュールは機能が完成したものとされています。 この API より宣言
  的で拡張しやすい代替手段として、"optparse" モジュールがあります。 コ
  マンドライン引数処理のさらなる機能拡張は、PyPI のサードパーティーモ
  ジュールか、"argparse" モジュールの機能として提供されます。

======================================================================

このモジュールは、スクリプトで "sys.argv" のコマンドライン引数を解析す
る際に役立ちます。 Unix の "getopt()" 関数と同じ規則をサポートします (
引数 ""-"" と ""--"" の特別な意味も含みます)。 省略可能な第 3 引数によ
り、GNU ソフトウェアがサポートするものと同様の長形式のオプションも使え
ます。

Unix の "getopt()" 関数に不慣れな場合は、代わりに "argparse" モジュー
ルの使用を検討してください。 Unix の "getopt()" 関数に慣れていて、同等
の動作をより少ないコードで実現し、より適切なヘルプやエラーメッセージを
得たい場合は、"optparse" モジュールの使用を検討してください。 詳しくは
引数解析ライブラリの選択 を参照してください。

このモジュールは2つの関数と1つの例外を提供しています:

getopt.getopt(args, shortopts, longopts=[])

   コマンドラインのオプションと引数のリストを解析します。 *args* は解
   析する引数のリストで、先頭にある実行中のプログラムを示す要素は除き
   ます。 通常は "sys.argv[1:]" です。 *shortopts* はスクリプトが認識
   するオプションの文字を並べた文字列です。 引数が必須のオプションの後
   ろにはコロン ("':'") を 1 つ、省略可能な引数を取るオプションの後ろ
   には 2 つ ("'::'") 付けます。 これは Unix の "getopt()" が使うのと
   同じ形式です。

   注釈:

     GNU の "getopt()" とは異なり、オプションでない引数が現れると、そ
     れ以降のすべての引数もオプションではないものとして扱います。 これ
     は GNU 以外の Unix システムと同様の動作です。

   *longopts* を指定する場合は、サポートする長形式のオプション名を文字
   列のリストとして渡してください。 オプション名には先頭の "'--'" を含
   めません。 引数が必須の長形式オプションの後ろには等号 ("'='") を、
   省略可能な引数を取るものには等号と疑問符 ("'=?'") を付けます。 長形
   式のオプションだけを受け付けるには、*shortopts* を空文字列にします
   。 コマンドライン上の長形式オプションは、その名前の先頭部分だけでも
   、受け付けるオプションのうちちょうど 1 つに一致すれば認識されます。
   例えば *longopts* が "['foo', 'frob']" の場合、"--fo" は "--foo" と
   して認識されますが、"--f" は一意に決まらないため "GetoptError" を送
   出します。

   *longopts* が文字列の場合は、要素が 1 つのリストとして扱います。

   返り値は2つの要素から成っています: 最初は "(option, value)" のタプ
   ルのリスト、2つ目はオプションリストを取り除いたあとに残ったプログラ
   ムの引数リストです (*args* の末尾部分のスライスになります)。それぞ
   れの引数と値のタプルの最初の要素は、短形式の時はハイフン 1つで始ま
   る文字列 (例: "'-x'")、長形式の時はハイフン2つで始まる文字列 (例:
   "'--long-option'") となり、引数が2番目の要素になります。引数をとら
   ない場合には空文字列が入ります。オプションは見つかった順に並んでい
   て、複数回同じオプションを指定できます。長形式と短形式のオプション
   は混在できます。

   バージョン 3.14 で変更: 省略可能な引数がサポートされました。

getopt.gnu_getopt(args, shortopts, longopts=[])

   この関数はデフォルトで GNU スタイルのスキャンモードを使う以外は
   "getopt()" と同じように動作します。つまり、オプションとオプションで
   ない引数とを混在させることができます。"getopt()" 関数はオプションで
   ない引数を見つけると解析を停止します。

   オプション文字列の最初の文字が "'+'" の場合、または環境変数
   "POSIXLY_CORRECT" が設定されている場合は、オプションでない引数が現
   れた時点でオプションの処理を停止します。

   オプション文字列の最初の文字が "'-'" の場合、後ろにオプションが続く
   非オプション引数は、オプションと値のペアのリストに追加されます。 こ
   のペアの最初の要素は "None"、2 番目の要素は非オプション引数のリスト
   です。 "gnu_getopt()" の戻り値の 2 番目の要素は、最後のオプションよ
   り後にあるプログラム引数のリストになります。

   バージョン 3.14 で変更: 混在するオプションと非オプション引数を順序
   どおりに返すことをサポートしました。

exception getopt.GetoptError

   引数リストに認識できないオプションがある場合、または必須の引数がオ
   プションに指定されていない場合に送出されます。 例外の引数はエラーの
   原因を示す文字列です。 長形式のオプションでは、引数を取らないオプシ
   ョンに引数が指定された場合もこの例外を送出します。 "msg" と "opt"
   属性は、それぞれエラーメッセージと関連するオプションを表します。 エ
   ラーに関連する特定のオプションがなければ、"opt" は空文字列です。

exception getopt.error

   "GetoptError" へのエイリアスです。後方互換性のために残されています
   。

Unix スタイルのオプションを使った例です:

   >>> import getopt
   >>> args = '-a -b -cfoo -d bar a1 a2'.split()
   >>> args
   ['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
   >>> optlist, args = getopt.getopt(args, 'abc:d:')
   >>> optlist
   [('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
   >>> args
   ['a1', 'a2']

長形式のオプションを使っても同様です:

   >>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
   >>> args = s.split()
   >>> args
   ['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
   >>> optlist, args = getopt.getopt(args, 'x', [
   ...     'condition=', 'output-file=', 'testing'])
   >>> optlist
   [('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
   >>> args
   ['a1', 'a2']

省略可能な引数は、次のように明示的に指定してください。

   >>> s = '-Con -C --color=off --color a1 a2'
   >>> args = s.split()
   >>> args
   ['-Con', '-C', '--color=off', '--color', 'a1', 'a2']
   >>> optlist, args = getopt.getopt(args, 'C::', ['color=?'])
   >>> optlist
   [('-C', 'on'), ('-C', ''), ('--color', 'off'), ('--color', '')]
   >>> args
   ['a1', 'a2']

オプションと非オプション引数の順序を保持できます。

   >>> s = 'a1 -x a2 a3 a4 --long a5 a6'
   >>> args = s.split()
   >>> args
   ['a1', '-x', 'a2', 'a3', 'a4', '--long', 'a5', 'a6']
   >>> optlist, args = getopt.gnu_getopt(args, '-x:', ['long='])
   >>> optlist
   [(None, ['a1']), ('-x', 'a2'), (None, ['a3', 'a4']), ('--long', 'a5')]
   >>> args
   ['a6']

スクリプトでの典型的な使用例は次のようになります。

   import getopt, sys

   def main():
       try:
           opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
       except getopt.GetoptError as err:
           # ヘルプ情報を表示して終了する:
           print(err)  # "option -a not recognized" などと表示する
           usage()
           sys.exit(2)
       output = None
       verbose = False
       for o, a in opts:
           if o == "-v":
               verbose = True
           elif o in ("-h", "--help"):
               usage()
               sys.exit()
           elif o in ("-o", "--output"):
               output = a
           else:
               assert False, "unhandled option"
       process(args, output=output, verbose=verbose)

   if __name__ == "__main__":
       main()

"optparse" モジュールを使うと、同等のコマンドラインインターフェースを
より少ないコードで作成でき、ヘルプやエラーメッセージもより詳しくなりま
す。

   import optparse

   if __name__ == '__main__':
       parser = optparse.OptionParser()
       parser.add_option('-o', '--output')
       parser.add_option('-v', dest='verbose', action='store_true')
       opts, args = parser.parse_args()
       process(args, output=opts.output, verbose=opts.verbose)

この場合は "argparse" モジュールを使っても、ほぼ同等のコマンドラインイ
ンターフェースを作成できます。

   import argparse

   if __name__ == '__main__':
       parser = argparse.ArgumentParser()
       parser.add_argument('-o', '--output')
       parser.add_argument('-v', dest='verbose', action='store_true')
       parser.add_argument('rest', nargs='*')
       args = parser.parse_args()
       process(args.rest, output=args.output, verbose=args.verbose)

このコードの "argparse" 版と "optparse" (および "getopt") 版の動作の違
いについては、引数解析ライブラリの選択 を参照してください。

参考:

  "optparse" モジュール
     宣言的なコマンドラインオプション解析。

  "argparse" モジュール
     コマンドラインのオプションと引数を、より明確な方針に沿って解析す
     るライブラリ。
