\section{\module{optparse} ---
        より強力なコマンドラインオプション解析器}
\declaremodule{standard}{optparse}
\moduleauthor{Greg Ward}{gward@python.net}
\modulesynopsis{より便利で柔軟性に富んだ強力なコマンドライン解析ライブラリ}
\versionadded{2.3}
\sectionauthor{Greg Ward}{gward@python.net}
% An intro blurb used only when generating LaTeX docs for the Python
% manual (based on README.txt). 

\module{optparse} モジュールは、\code{getopt} よりも簡便で、柔軟性に富み、
かつ強力なコマンドライン解析ライブラリです。
\module{optparse} では、より明快なスタイルのコマンドライン解析手法、
すなわち\class{OptionParser} のインスタンスを作成してオプションを
追加してゆき、そのインスタンスでコマンドラインを解析するという手法を
とっています。\code{optparse} を使うと、GNU/POSIX 構文でオプションを
指定できるだけでなく、使用法やヘルプメッセージの生成も行えます。

\module{optparse} を使った簡単なスクリプト例を以下に示します:
\begin{verbatim}
from optparse import OptionParser

[...]
parser = OptionParser()
parser.add_option("-f", "--file", dest="filename",
                  help="write report to FILE", metavar="FILE")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose", default=True,
                  help="don't print status messages to stdout")

(options, args) = parser.parse_args()
\end{verbatim}

このようにわずかな行数のコードによって、スクリプトのユーザは
コマンドライン上で例えば以下のような 「よくある使い方」 を実行できるように
なります:
\begin{verbatim}
<yourscript> --file=outfile -q
\end{verbatim}

コマンドライン解析の中で、\code{optparse} はユーザの指定した
コマンドライン引数値に応じて\method{parse{\_}args()} の返す
\code{options} の属性値を設定してゆきます。
\method{parse{\_}args()} がコマンドライン解析から処理を戻したとき、
\code{options.filename} は\code{"outfile"} に、\code{options.verbose}
は \code{False} になっているはずです。\code{optparse} は
長い形式と短い形式の両方のオプション表記をサポートしており、
短い形式は結合して指定できます。また、様々な形でオプションに
引数値を関連付けられます。従って、以下のコマンドラインは全て上の例
と同じ意味になります:

\begin{verbatim}
<yourscript> -f outfile --quiet
<yourscript> --quiet --file outfile
<yourscript> -q -foutfile
<yourscript> -qfoutfile
\end{verbatim}

さらに、ユーザが

\begin{verbatim}
<yourscript> -h
<yourscript> --help
\end{verbatim}

のいずれかを実行すると、\module{optparse} はスクリプトの
オプションについて簡単にまとめた内容を出力します:

\begin{verbatim}
usage: <yourscript> [options]

options:
  -h, --help            show this help message and exit
  -f FILE, --file=FILE  write report to FILE
  -q, --quiet           don't print status messages to stdout
\end{verbatim}

\emph{yourscript} の中身は実行時に決まります
(通常は \code{sys.argv{[}0]} になります)。


\subsection{Background\label{optparse-background}}

\module{optparse} は、素直で慣習に則ったコマンドラインインタフェースを
備えたプログラムの作成を援助する目的で設計されました。
その結果、\UNIX{} で慣習的に使われているコマンドラインの構文や機能
だけをサポートするに留まっています。こうした慣習に詳しくなければ、
よく知っておくためにもこの節を読んでおきましょう。


\subsubsection{Terminology\label{optparse-terminology}}
\begin{description}
\item[引数 (argument)]
コマンドラインでユーザが入力するテキストの塊で、シェルが
\cfunction{execl()} や \cfunction{execv()} に引き渡すものです。Python
では、引数は \code{sys.argv[1:]} の要素となります。(\code{sys.argv[0]}
は実行しようとしているプログラムの名前です。引数解析に関しては、この要
素はあまり重要ではありません。) \UNIX{} シェルでは、 「語 (word)」 と
いう用語も使います。

場合によっては \code{sys.argv[1:]} 以外の引数リストを代入する方が望ま
しいことがあるので、「引数」 は 「\code{sys.argv[1:]} または
\code{sys.argv[1:]} の代替として提供される別のリストの要素」と読むべき
でしょう。

\item[オプション (option)]
追加的な情報を与えるための引数で、プログラムの実行に対する教示やカスタ
マイズを行います。オプションには多様な文法が存在します。伝統的な
\UNIX{} における書法はハイフン (``-'') の後ろに一文字が続くもので、例
えば \code{"-x"} や \code{"-F"} です。また、伝統的な \UNIX{} における
書法では、複数のオプションを一つの引数にまとめられます。例えば
\code{"-x -F"} は\code{"-xF"} と等価です。
GNU プロジェクトでは \code{"-{}-"} の後ろにハイフンで区切りの語を指定
する方法、例えば \code{"-{}-file"} や \code{"-{}-dry-run"} も提供して
います。\module{optparse} は、これら二種類のオプション書法だけをサポー
トしています。

他に見られる他のオプション書法には以下のようなものがあります:
\begin{itemize}
\item {} 
ハイフンの後ろに数個の文字が続くもので、例えば \code{"-pf"} 
(このオプションは複数のオプションを一つにまとめたものとは
\emph{違います})
\item {}
ハイフンの後ろに語が続くもので、例えば \code{"-file"} 
(これは技術的には上の書式と同じですが、通常同じプログラム上で一緒に
使うことはありません)
\item {}
プラス記号の後ろに一文字、数個の文字、または語を続けたもので、
例えば \code{"+f"} 、 \code{"+rgb"} 
\item {}
スラッシュ記号の後ろに一文字、数個の文字、または語を続けたもので、
例えば \code{"/f"} 、 \code{"/file"} 
\end{itemize}

上記のオプション書法は \module{optparse} ではサポートしておらず、
今後もサポートする予定はありません。これは故意によるものです:
最初の三つはどの環境の標準でもなく、最後の一つは VMS や MS-DOS,
そして Windows を対象にしているときにしか意味をなさないからです。

\item[オプション引数 (option argument)]
あるオプションの後ろに続く引数で、そのオプションに密接な関連を
もち、オプションと同時に引数リストから取り出されます。
\module{optparse} では、オプション引数は以下のように別々の引数にできます:
\begin{verbatim}
-f foo
--file foo
\end{verbatim}

また、一つの引数中にも入れられます:
\begin{verbatim}
-ffoo
--file=foo
\end{verbatim}
通常、オプションは引数をとることもとらないこともあります。
あるオプションは引数をとることがなく、またあるオプションは
常に引数をとります。多くの人々が 「オプションのオプション引数」
機能を欲しています。これは、あるオプションが引数が指定されている
場合には引数をとり、そうでない場合には引数をもたないようにするという機能です。
この機能は引数解析をあいまいにするため、議論の的となっています:
例えば、もし \programopt{-a} がオプション引数を
とり、\programopt{-b} がまったく別のオプションだとしたら、
\programopt{-ab} をどうやって解析すればいいのでしょうか？
こうした曖昧さが存在するため、\module{optparse} は今のところこの機能をサポートしていません。


\item[固定引数 (positional argument)]
他のオプションが解析される、すなわち他のオプションとその引数が
解析されて引数リストから除去された後に引数リストに置かれている
ものです。

\item[必須のオプション (required option)]
コマンドラインで与えなければならないオプションです; 「必須なオプション
(required option)」という語は、英語では矛盾した言葉です。\module{optparse}
では必須オプションの実装を妨げてはいませんが、とりたてて実装上役立つこともしていません。
\module{optparse} で必須オプションを実装する方法は、\module{optparse}
ソースコード配布物中の\code{examples/required{\_}1.py} や
\code{examples/required{\_}2.py} を参照してください。
\end{description}

例えば、下記のような架空のコマンドラインを考えてみましょう:
\begin{verbatim}
prog -v --report /tmp/report.txt foo bar
\end{verbatim}

\code{"-v"} と\code{"-{}-report"} はどちらもオプションです。
\longprogramopt{report} オプションが引数をとるとすれば、
\code{"/tmp/report.txt"} はオプションの引数です。
\code{"foo"}と\code{"bar"} は固定引数になります。


\subsubsection{オプションとは何か\label{optparse-what-options-for}}

オプションはプログラムの実行を調整したり、カスタマイズしたりするための補助的な
情報を与えるために使います。もっとはっきりいうと、オプションはあくまでもオプション
(省略可能)であるということです。本来、プログラムはともかくもオプションなしでうまく
実行できてしかるべきです。(\UNIX{} やGNU ツールセットのプログラムをランダムに
ピックアップしてみてください。オプションを全く指定しなくてもちゃんと動くでしょう？
例外は\code{find}, \code{tar}, \code{dd} くらいです---これらの例外は、
オプション文法が標準的でなく、インタフェースが混乱を招くと酷評されてきた変種の
はみ出しものなのです)

多くの人が自分のプログラムに「必須のオプション」を持たせたいと考えます。しかし
よく考えてください。必須なら、それは\emph{オプション(省略可能) ではないのです！}
プログラムを正しく動作させるのに絶対的に必要な情報があるとすれば、そこには
固定引数を割り当てるべきなのです。

良くできたコマンドラインインタフェース設計として、ファイルのコピーに使われる
\code{cp} ユーティリティのことを考えてみましょう。ファイルのコピーでは、
コピー先を指定せずにファイルをコピーするのは無意味な操作ですし、少なくとも一つの
コピー元が必要です。従って、\code{cp} は引数無しで実行すると失敗します。
とはいえ、\code{cp} はオプションを全く必要としない柔軟で便利なコマンドライン
文法を備えています:
\begin{verbatim}
cp SOURCE DEST
cp SOURCE ... DEST-DIR
\end{verbatim}

まだあります。ほとんどの \code{cp} の実装では、ファイルモードや変更時刻を変えずに
コピーする、シンボリックリンクの追跡を行わない、すでにあるファイルを上書きする前に
ユーザに尋ねる、など、ファイルをコピーする方法をいじるための一連のオプションを実装
しています。しかし、こうしたオプションは、一つのファイルを別の場所にコピーする、
または複数のファイルを別のディレクトリにコピーするという、\code{cp} の中心的な処理
を乱すことはないのです。


\subsubsection{固定引数とは何か\label{optparse-what-positional-arguments-for}}

固定引数とは、プログラムを動作させる上で絶対的に必要な情報となる引数です。

よいユーザインタフェースとは、可能な限り少ない固定引数をもつものです。
プログラムを正しく動作させるために 17 個もの別個の情報が必要だとしたら、
その\emph{方法} はさして問題にはなりません ---ユーザはプログラムを正しく
動作させられないうちに諦め、立ち去ってしまうからです。
ユーザインタフェースがコマンドラインでも、設定ファイルでも、GUI やその他の
何であっても同じです: 多くの要求をユーザに押し付ければ、ほとんどのユーザはただ
音をあげてしまうだけなのです。

要するに、ユーザが絶対に提供しなければならない情報だけに制限する
 --- そして可能な限りよく練られたデフォルト設定を使うよう試みてください。
もちろん、プログラムには適度な柔軟性を持たせたいとも望むはずですが、
それこそがオプションの果たす役割です。繰り返しますが、設定ファイルのエントリ
であろうが、 GUI でできた「環境設定」ダイアログ上のウィジェットであろうが、
コマンドラインオプションであろうが関係ありません --- 
より多くのオプションを実装すればプログラムはより柔軟性を持ちますが、
実装はより難解になるのです。高すぎる柔軟性はユーザを閉口させ、コードの維持を
より難しくするのです。


\subsection{Tutorial\label{optparse-tutorial}}

\module{optparse} はとても柔軟で強力でありながら、ほとんどの場合には簡単に利用
できます。この節では、\module{optparse} ベースのプログラムで広く使われて
いるコードパターンについて述べます。

まず、\class{OptionParser} クラスを import しておかねばなりません。
次に、プログラムの冒頭で \class{OptionParser} インスタンスを生成しておきます:

\begin{verbatim}
from optparse import OptionParser
[...]
parser = OptionParser()
\end{verbatim}

これでオプションを定義できるようになりました。基本的な構文は以下の通りです:
\begin{verbatim}
parser.add_option(opt_str, ...,
                  attr=value, ...)
\end{verbatim}

各オプションには、\code{"-f"} や\code{"-{}-file"} のような一つまたは複数の
オプション文字列と、パーザがコマンドライン上のオプションを見つけた際に、
何を準備し、何を行うべきかを\module{optparse} に教えるためのオプション属性
(option attribute)がいくつか入ります。

通常、各オプションには短いオプション文字列と長いオプション文字列があります。
例えば:
\begin{verbatim}
parser.add_option("-f", "--file", ...)
\end{verbatim}
といった具合です。

オプション文字列は、(ゼロ文字の場合も含め)いくらでも短く、またいくらでも長く
できます。ただしオプション文字列は少なくとも一つなければなりません。

\method{add{\_}option()} に渡されたオプション文字列は、実際にはこの
関数で定義したオプションに対するラベルになります。簡単のため、以後では
コマンドライン上で\emph{オプションを見つける} という表現をしばしば使いますが、
これは実際には\module{optparse} がコマンドライン上の\emph{オプション文字列}
を見つけ、対応づけされているオプションを捜し出す、という処理に相当します。

オプションを全て定義したら、\module{optparse} にコマンドラインを解析するように
指示します:
\begin{verbatim}
(options, args) = parser.parse_args()
\end{verbatim}

(お望みなら、\method{parse{\_}args()} に自作の引数リストを渡してもかまいません。
とはいえ、実際にはそうした必要はほとんどないでしょう: \module{optionparser}
はデフォルトで\code{sys.argv{[}1:]}を使うからです。)

\method{parse{\_}args()} は二つの値を返します:
\begin{itemize}
\item {} 
全てのオプションに対する値の入ったオブジェクト\code{options} --- 例えば、
\code{"-{}-file"} が単一の文字列引数をとる場合、\code{options.file} は
ユーザが指定したファイル名になります。オプションを指定しなかった場合には
\code{None} になります。

\item {} 
オプションの解析後に残った固定引数からなるリスト\code{args}。

\end{itemize}

このチュートリアルの節では、最も重要な四つのオプション属性:
\member{action}, \member{type}, \member{dest} (destination), および
\member{help} についてしか触れません。このうち最も重要なのは\member{action}
です。


\subsubsection{オプション・アクションを理解する
\label{optparse-understanding-option-actions}}

アクション(action)は\module{optparse} が コマンドライン上にあるオプションを
見つけたときに何をすべきかを指示します。\module{optparse} には押し着せの
アクションのセットがハードコードされています。
新たなアクションの追加は上級者向けの話題であり、
\ref{optparse-extending-optparse} の「\module{optparse} の拡張」で触れます。
ほとんどのアクションは、値を何らかの変数に記憶するよう\module{optparse} に
指示します --- 例えば、文字列をコマンドラインから取り出して、\code{options} の
属性の中に入れる、といった具合にです。

オプション・アクションを指定しない場合、\module{optparse} のデフォルトの動作は
\code{store} になります。

\subsubsection{store アクション\label{optparse-store-action}}

もっとも良く使われるアクションは \code{store} です。このアクションは
次の引数 (あるいは現在の引数の残りの部分) を取り出し、正しい型の値か確かめ、
指定した保存先に保存するよう\module{optparse} に指示します。

例えば:
\begin{verbatim}
parser.add_option("-f", "--file",
                  action="store", type="string", dest="filename")
\end{verbatim}
のように指定しておき、偽のコマンドラインを作成して \module{optparse} に
解析させてみましょう:
\begin{verbatim}
args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)
\end{verbatim}

オプション文字列 \code{"-f"} を見つけると、\module{optparse} は次の
引数である \code{"foo.txt"} を消費し、その値を \code{options.filename} に
保存します。従って、この\method{parse{\_}args()}呼び出し後には
\code{options.filename} は\code{"foo.txt"}になっています。


オプションの型として、\module{optparse} は他にも\code{int} や\code{float}
をサポートしています。

整数の引数を想定したオプションの例を示します:
\begin{verbatim}
parser.add_option("-n", type="int", dest="num")
\end{verbatim}

このオプションには長い形式のオプション文字列がないため、設定に問題がないという
ことに注意してください。また、デフォルトのアクションは \code{store} なので、
ここでは action を明示的に指定していません。

架空のコマンドラインをもう一つ解析してみましょう。今度は、オプション引数を
オプションの右側にぴったりくっつけて一緒くたにします: \programopt{-n42} 
(一つの引数のみ) は \programopt{-n 42} (二つの引数からなる) と等価になるので、

\begin{verbatim}
(options, args) = parser.parse_args(["-n42"])
print options.num
\end{verbatim}

は \code{"42"} を出力します。

型を指定しない場合、 \module{optparse} は引数を\code{string} であると仮定します。
デフォルトのアクションが \code{store} であることも併せて考えると、最初の例はもっと
短くなります:

\begin{verbatim}
parser.add_option("-f", "--file", dest="filename")
\end{verbatim}

保存先 (destination) を指定しない場合、 \module{optparse} はデフォルト値として
オプション文字列から気のきいた名前を設定します: 最初に指定した長い形式のオプション
文字列が\code{"-{}-foo-bar"} であれば、デフォルトの保存先は \code{foo{\_}bar}
になります。長い形式のオプション文字列がなければ、\module{optparse} は最初に指定
した短い形式のオプション文字列を探します: 例えば、\code{"-f"} に対する保存先は
\code{f} になります。

\module{optparse} では、\code{long} や\code{complex} といった組み込み型も
取り入れています。型の追加は\ref{optparse-extending-optparse} 節の
「\module{optparse} の拡張」で触れています。


\subsubsection{ブール値 (フラグ) オプションの処理
  \label{optparse-handling-boolean-options}}

フラグオプション---特定のオプションに対して真または偽の値の値を設定するオプション---
はよく使われます。\module{optparse} では、二つのアクション、\code{store{\_}true}
および \code{store{\_}false} をサポートしています。例えば、
\code{verbose} というフラグを\code{"-v"} で有効にして、\code{"-q"} で無効に
したいとします:
\begin{verbatim}
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose")
\end{verbatim}

ここでは二つのオプションに同じ保存先を指定していますが、全く問題ありません
(下記のように、デフォルト値の設定を少し注意深く行わねばならないだけです)

\code{"-v"} をコマンドライン上に見つけると、\module{optparse} は
\code{options.verbose} を \code{True} に設定します。\code{"-q"}
を見つければ、\code{options.verbose} は \code{False} にセットされます。


\subsubsection{その他のアクション\label{optparse-other-actions}}

この他にも、\module{optparse} は以下のようなアクションをサポートしています:
\begin{description}
\item[\code{store{\_}const}]
定数値を保存します。
\item[\code{append}]
オプションの引数を指定のリストに追加します。
\item[\code{count}]
指定のカウンタを 1 増やします。
\item[\code{callback}]
指定の関数を呼び出します。
\end{description}

これらのアクションについては、\ref{optparse-reference-guide} 節の
「リファレンスガイド」および\ref{optparse-option-callbacks} 節の
「オプション・コールバック」で触れます。


\subsubsection{デフォルト値\label{optparse-default-values}}

上記の例は全て、何らかのコマンドラインオプションが見つかった時に
何らかの変数 (保存先: destination) に値を設定していました。
では、該当するオプションが見つからなかった場合には何が起きるのでしょうか？
デフォルトは全く与えていないため、これらの値は全て \code{None} になります。
たいていはこれで十分ですが、もっときちんと制御したい場合もあります。
\module{optparse} では各保存先に対してデフォルト値を指定し、コマンドライン
の解析前にデフォルト値が設定されるようにできます。

まず、 verbose/quiet の例について考えてみましょう。\module{optparse} に
対して、\code{"-q"} がない限り \code{verbose} を \code{True} に設定
させたいなら、以下のようにします:

\begin{verbatim}
parser.add_option("-v", action="store_true", dest="verbose", default=True)
parser.add_option("-q", action="store_false", dest="verbose")
\end{verbatim}

デフォルトの値は特定のオプションではなく \emph{保存先} に対して適用されます。
また、これら二つのオプションはたまたま同じ保存先を持っているにすぎないため、
上のコードは下のコードと全く等価になります:

\begin{verbatim}
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose", default=True)
\end{verbatim}

下のような場合を考えてみましょう:
\begin{verbatim}
parser.add_option("-v", action="store_true", dest="verbose", default=False)
parser.add_option("-q", action="store_false", dest="verbose", default=True)
\end{verbatim}

やはり\code{verbose} のデフォルト値は \code{True} になります;
特定の目的変数に対するデフォルト値として有効なのは、最後に指定した値だからです。

デフォルト値をすっきりと指定するには、\class{OptionParser} の
\method{set{\_}defaults()} メソッドを使います。このメソッドは
\method{parse{\_}args()} を呼び出す前ならいつでも使えます:
\begin{verbatim}
parser.set_defaults(verbose=True)
parser.add_option(...)
(options, args) = parser.parse_args()
\end{verbatim}

前の例と同様、あるオプションの値の保存先に対するデフォルトの値は最後に指定した
値になります。コードを読みやすくするため、デフォルト値を設定するときには両方のやり方
を混ぜるのではなく、片方だけを使うようにしましょう。


\subsubsection{ヘルプの生成\label{optparse-generating-help}}

\module{optparse} にはヘルプと使い方の説明 (usage text) を生成する機能があり、
ユーザに優しいコマンドラインインタフェースを作成する上で役立ちます。
やらなければならないのは、各オプションに対する\member{help} の値と、
必要ならプログラム全体の使用法を説明する短いメッセージを与えることだけです。

ユーザフレンドリな (ドキュメント付きの) オプションを追加した
\class{OptionParser} を以下に示します:

\begin{verbatim}
usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
                  action="store_true", dest="verbose", default=True,
                  help="make lots of noise [default]")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose", 
                  help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--filename",
                  metavar="FILE", help="write output to FILE"),
parser.add_option("-m", "--mode",
                  default="intermediate",
                  help="interaction mode: novice, intermediate, "
                       "or expert [default: %default]")
\end{verbatim}

\module{optparse} がコマンドライン上で\code{"-h"} や\code{"-{}-help"} を
見つけた場合やユーザが\method{parser.print{\_}help()} を呼び出した場合、
この\class{OptionParser} は以下のようなメッセージを標準出力に出力します:

\begin{verbatim}
usage: <yourscript> [options] arg1 arg2

options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                        expert [default: intermediate]
\end{verbatim}

(help オプションでヘルプを出力した場合、\module{optparse} は出力後に
プログラムを終了します。)

\module{optparse} ができるだけうまくメッセージを生成するよう手助けするには、
他にもまだまだやるべきことがあります:
\begin{itemize}
\item {} 
スクリプト自体の利用法を表すメッセージを定義します:
\begin{verbatim}
usage = "usage: %prog [options] arg1 arg2"
\end{verbatim}

\module{optparse} は \code{"{\%}prog"} を現在のプログラム名、すなわち
\code{os.path.basename(sys.argv{[}0{]})} と置き換えます。この文字列は
詳細なオプションヘルプの前に展開され出力されます。

usage の文字列を指定しない場合、\module{optparse} は型どおりとはいえ
気の効いたデフォルト値、 \code{"usage: {\%}prog {[}options{]}"} を
使います。固定引数をとらないスクリプトの場合はこれで十分でしょう。

\item {} 
全てのオプションにヘルプ文字列を定義します。行の折り返しは気にしなくて
かまいません --- \module{optparse} は行の折り返しに気を配り、見栄えの
よいヘルプ出力を生成します。

\item {} 
オプションが値をとるということは自動的に生成されるヘルプメッセージの中で
分かります。例えば、``mode'' option の場合には:
\begin{verbatim}
-m MODE, --mode=MODE
\end{verbatim}
のようになります。

ここで ``MODE'' はメタ変数 (meta-variable) と呼ばれます: メタ変数は、
ユーザが \programopt{-m}/\longprogramopt{mode} に対して指定するはずの
引数を表します。デフォルトでは、\module{optparse} は保存先の変数名を
大文字だけにしたものをメタ変数に使います。これは時として期待通りの結果に
なりません --- 例えば、上の例の\longprogramopt{filename} オプションでは
明示的に \code{metavar="FILE"} を設定しており、その結果自動生成された
オプション説明テキストは:
\begin{verbatim}
-f FILE, --filename=FILE
\end{verbatim}
のようになります。

この機能の重要さは、単に表示スペースを節約するといった理由にとどまりません: 
上の例では、手作業で書いたヘルプテキストの中でメタ変数として ``FILE'' を
使っています。その結果、ユーザに対してやや堅苦しい表現の書法 ``-f FILE''
と、より平易に意味付けを説明した ``write output to FILE'' との間に
対応があるというヒントを与えています。これは、エンドユーザにとってより明解で
便利なヘルプテキストを作成する単純でありながら効果的な手法なのです。

\item {} 
デフォルト値を持つオプションのヘルプ文字列には\code{{\%}default} を入れられ
ます --- \module{optparse} は\code{{\%}default} をデフォルト値の
\function{str()} で置き換えます。該当するオプションにデフォルト値がない場合
(あるいはデフォルト値が \code{None} である場合) \code{{\%}default} の
展開結果は \code{none} になります。

\end{itemize}


\subsubsection{バージョン番号の出力\label{optparse-printing-version-string}}

\module{optparse} では、使用法メッセージと同様にプログラムのバージョン文字列を
出力できます。\class{OptionParser} の\code{version} 引数に文字列を渡します:
\begin{verbatim}
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
\end{verbatim}

\code{"{\%}prog"} は\var{usage} と同じような展開を受けます。
その他にも\code{version} には何でも好きな内容を入れられます。
\code{version} を指定した場合、\module{optparse} は自動的に\code{"-{}-version"}
オプションをパーザに渡します。
コマンドライン中に\code{"-{}-version"} が見つかると、\module{optparse}
は\code{version} 文字列を展開して (\code{"{\%}prog"} を置き換えて)
標準出力に出力し、プログラムを終了します。

例えば、 \code{/usr/bin/foo} という名前のスクリプトなら:
\begin{verbatim}
$ /usr/bin/foo --version
foo 1.0
\end{verbatim}
のようになります。


\subsubsection{\module{optparse} のエラー処理法
  \label{optparse-how-optparse-handles-errors}}

\module{optparse} を使う場合に気を付けねばならないエラーには、
大きく分けてプログラマ側のエラーとユーザ側のエラーという二つの種類があります。
プログラマ側のエラーの多くは、例えば不正なオプション文字列や定義されていない
オプション属性の指定、あるいはオプション属性を指定し忘れるといった、
誤った\code{parser.add{\_}option()} 呼び出しによるものです。
こうした誤りは通常通りに処理されます。すなわち、例外(\code{optparse.OptionError}
や \code{TypeError}) を送出して、プログラムをクラッシュさせます。
もっと重要なのはユーザ側のエラーの処理です。というのも、ユーザの操作エラーという
ものはコードの安定性に関係なく起こるからです。
\module{optparse} は、誤ったオプション引数の指定 (整数を引数にとるオプション
\programopt{-n} に対して \code{"-n4x"} と指定してしまうなど) や、引数を
指定し忘れた場合 (\programopt{-n} が何らかの引数をとるオプションであるのに、
\code{"-n"} が引数の末尾に来ている場合) といった、ユーザによるエラーを自動的に
検出します。また、アプリケーション側で定義されたエラー条件が起きた場合、
\code{parser.error()} を呼び出してエラーを通知できます:

\begin{verbatim}
(options, args) = parser.parse_args()
[...]
if options.a and options.b:
    parser.error("options -a and -b are mutually exclusive")
\end{verbatim}

いずれの場合にも \module{optparse} はエラーを同じやり方で処理します。すなわち、
プログラムの使用法メッセージとエラーメッセージを標準エラー出力に出力して、
終了ステータス 2 でプログラムを終了させます。

上に挙げた最初の例、すなわち整数を引数にとるオプションにユーザが \code{"4x"} を
指定した場合を考えてみましょう:

\begin{verbatim}
$ /usr/bin/foo -n 4x
usage: foo [options]

foo: error: option -n: invalid integer value: '4x'
\end{verbatim}

値を全く指定しない場合には、以下のようになります:
\begin{verbatim}
$ /usr/bin/foo -n
usage: foo [options]

foo: error: -n option requires an argument
\end{verbatim}

\module{optparse} は、常にエラーを引き起こしたオプションについて説明の入った
エラーメッセージを生成するよう気を配ります; 従って、\code{parser.error()} を
アプリケーションコードから呼び出す場合にも、同じようなメッセージになるように
してください。

\module{optparse} のデフォルトのエラー処理動作が気に入らないのなら、
\class{OptionParser} をサブクラス化して、\code{exit()} かつ/または
\method{error()} をオーバライドする必要があります。


\subsubsection{全てをつなぎ合わせる\label{optparse-putting-it-all-together}}

\module{optparse} を使ったスクリプトは、通常以下のようになります:
\begin{verbatim}
from optparse import OptionParser
[...]
def main():
    usage = "usage: %prog [options] arg"
    parser = OptionParser(usage)
    parser.add_option("-f", "--file", dest="filename",
                      help="read data from FILENAME")
    parser.add_option("-v", "--verbose",
                      action="store_true", dest="verbose")
    parser.add_option("-q", "--quiet",
                      action="store_false", dest="verbose")
    [...]
    (options, args) = parser.parse_args()
    if len(args) != 1:
        parser.error("incorrect number of arguments")
    if options.verbose:
        print "reading %s..." % options.filename
    [...]

if __name__ == "__main__":
    main()
\end{verbatim}


\subsection{リファレンスガイド\label{optparse-reference-guide}}

\subsubsection{Creating the parser\label{optparse-creating-parser}}

\module{optparse} を使う最初の一歩は OptionParser インスタンスを作ることです。
\begin{verbatim}
parser = OptionParser(...)
\end{verbatim}

OptionParser のコンストラクタの引数はどれも必須ではありませんが、いくつ
ものキーワード引数がオプションとして使えます。これらはキーワード引数と
して渡さなければなりません。すなわち、引数が宣言されている順番に頼っては
いけません。
\begin{quote}
\begin{description}
\item[\code{usage} (デフォルト: \code{"{\%}prog {[}options]"})]
プログラムが間違った方法で実行されるかまたはヘルプオプションを付けて
実行された場合に表示される使用法です。\module{optparse} は使用法の文
字列を表示する際に \code{{\%}prog} を
\code{os.path.basename(sys.argv{[}0])} (または
\code{prog} キーワード引数が指定されていればその値) に展開します。
使用法メッセージを抑制するためには特別な
\code{optparse.SUPPRESS{\_}USAGE} という値を指定します。
\item[\code{option{\_}list} (デフォルト: \code{{[}]})]
パーザに追加する Option オブジェクトのリストです。\code{option{\_}list} の
中のオプションは \code{standard{\_}option{\_}list} (OptionParser の
サブクラスでセットされる可能性のあるクラス属性) の後に追加されますが、バージョンや
ヘルプのオプションよりは前になります。
このオプションの使用は推奨されません。パーザを作成した後で、\method{add{\_}option()}
を使って追加してください。
\item[\code{option{\_}class} (デフォルト: optparse.Option)]
\method{add{\_}option()} でパーザにオプションを追加するときに使用されるクラス。
\item[\code{version} (デフォルト: \code{None})]
ユーザがバージョンオプションを与えたときに表示されるバージョン文字列です。
\code{version} に真の値を与えると、\module{optparse} は自動的に
単独のオプション文字列 \code{"-{}-version"} とともにバージョンオプションを
追加します。部分文字列 \code{"{\%}prog"} は \code{usage} と同様に
展開されます。
\item[\code{conflict{\_}handler} (デフォルト: \code{"error"})]
オプション文字列が衝突するようなオプションがパーザに追加されたときにどうするかを
指定します。\ref{optparse-conflicts-between-options} 節「オプション間の衝突」
を参照して下さい。
\item[\code{description} (デフォルト: \code{None})]
プログラムの概要を表す一段落のテキストです。\module{optparse} は
ユーザがヘルプを要求したときにこの概要を現在のターミナルの幅に合わせて
整形し直して表示します (\code{usage} の後、オプションリストの前に表示されます)。
\item[\code{formatter} (デフォルト: 新しい IndentedHelpFormatter)]
ヘルプテキストを表示する際に使われる optparse.HelpFormatter のインスタンスです。
\module{optparse} はこの目的のためにすぐ使えるクラスを二つ提供しています。
IndentedHelpFormatter と TitledHelpFormatter がそれです。
\item[\code{add{\_}help{\_}option} (デフォルト: \code{True})]
もし真ならば、\module{optparse} はパーザにヘルプオプションを
(オプション文字列 \code{"-h"} と \code{"-{}-help"} とともに)
追加します。
\item[\code{prog}]
\code{usage} や \code{version} の中の \code{"{\%}prog"} を展開するときに
\code{os.path.basename(sys.argv{[}0])} の代わりに使われる文字列です。
\end{description}
\end{quote}


\subsubsection{パーザへのオプション追加\label{optparse-populating-parser}}

パーザにオプションを加えていくにはいくつか方法があります。推奨するのは
\ref{optparse-tutorial} 節のチュートリアルで示したような
 \code{OptionParser.add{\_}option()} を使う方法です。
\method{add{\_}option()} は以下の二つのうちいずれかの方法で
呼び出せます:
\begin{itemize}
\item {} 
\function{make{\_}option()}に (すなわち\class{Option} のコンストラクタに)
固定引数とキーワード引数の組み合わせを渡して、\class{Option} インスタンスを
生成させます。

\item {}
(\function{make{\_}option()} などが返す)\class{Option}インスタンスを渡します。
\end{itemize}

もう一つの方法は、あらかじめ作成しておいた\class{Option} インスタンスから
なるリストを、以下のようにして \class{OptionParser} のコンストラクタに渡す
というものです:

\begin{verbatim}
option_list = [
    make_option("-f", "--filename",
                action="store", type="string", dest="filename"),
    make_option("-q", "--quiet",
                action="store_false", dest="verbose"),
    ]
parser = OptionParser(option_list=option_list)
\end{verbatim}

(\function{make{\_}option()} は \class{Option} インスタンスを生成する
ファクトリ関数です; 現在のところ、個の関数は\class{Option} のコンストラクタの
別名にすぎません。\module{optparse}の将来のバージョンでは、\class{Option} を
複数のクラスに分割し、\function{make{\_}option()} は適切なクラスを選んで
インスタンスを生成するようになる予定です。従って、\class{Option} を直接
インスタンス化しないでください。)


\subsubsection{オプションの定義\label{optparse-defining-options}}

各々の\class{Option} インスタンス、は\programopt{-f} や\longprogramopt{file}
といった同義のコマンドラインオプションからなる集合を表現しています。
一つの\class{Option} には任意の数のオプションを短い形式でも長い形式でも
指定できます。ただし、少なくとも一つは指定せねばなりません。

正しい方法で\class{Option} インスタンスを生成するには、
\class{OptionParser} の \method{add{\_}option()} を使います:
\begin{verbatim}
parser.add_option(opt_str[, ...], attr=value, ...)
\end{verbatim}

短い形式のオプション文字列を一つだけ持つようなオプションを生成するには:
\begin{verbatim}
parser.add_option("-f", attr=value, ...)
\end{verbatim}
のようにします。

また、長い形式のオプション文字列を一つだけ持つようなオプションの定義は:
\begin{verbatim}
parser.add_option("--foo", attr=value, ...)
\end{verbatim}
のようになります。

キーワード引数は新しい \class{Option}
オブジェクトの属性を定義します。オプションの属性のうちでもっとも重要なのは
\member{action} です。\member{action} は他のどの属性と関連があるか、そして
どの属性が必要かに大きく作用します。関係のないオプション属性を指定したり、
必要な属性を指定し忘れたりすると、\module{optparse} は誤りを解説した
\exception{OptionError}例外を送出します。

コマンドライン上にあるオプションが見つかったときの\module{optparse} の
振舞いを決定しているのは \emph{アクション(action)} です。 
\module{optparse} でハードコードされている標準的なアクションには
以下のようなものがあります:
\begin{description}
\item[\code{store}]
オプションの引数を保存します (デフォルトの動作です)
\item[\code{store{\_}const}]
定数を保存します
\item[\code{store{\_}true}]
真 (\constant{True}) を保存します
\item[\code{store{\_}false}]
偽 (\constant{False}) を保存します
\item[\code{append}]
オプションの引数をリストに追加します
\item[\code{append{\_}const}]
定数をリストに追加します
\item[\code{count}]
カウンタを一つ増やします
\item[\code{callback}]
指定された関数を呼び出します
\item[\member{help}]
全てのオプションとそのドキュメントの入った使用法メッセージを出力します。
\end{description}

(アクションを指定しない場合、デフォルトは \code{store} になります。このアクション
では、 \member{type} および \member{dest} オプション属性を指定せねばなりません。
下記を参照してください。)

すでにお分かりのように、ほとんどのアクションはどこかに値を保存したり、値を更新
したりします。
この目的のために、\module{optparse} は常に特別なオブジェクトを作り出し、
それは通常 \code{options} と呼ばれます (\code{optparse.Values} の
インスタンスになっています)。
オプションの引数 (や、その他の様々な値) は、\member{dest} (保存先: 
destination) オプション属性に従って、\var{options}の属性として保存されます。

例えば、
\begin{verbatim}
parser.parse_args()
\end{verbatim}

を呼び出した場合、\module{optparse} はまず \code{options} オブジェクト
を生成します:

\begin{verbatim}
options = Values()
\end{verbatim}

パーザ中で以下のようなオプション
\begin{verbatim}
parser.add_option("-f", "--file", action="store", type="string", dest="filename")
\end{verbatim}

が定義されていて、パーズしたコマンドラインに以下のいずれかが入っていた場合:
\begin{verbatim}
-ffoo
-f foo
--file=foo
--file foo
\end{verbatim}

\module{optparse} はこのオプションを見つけて、

\begin{verbatim}
options.filename = "foo"
\end{verbatim}
と同等の処理を行います。

\member{type} および \member{dest} オプション属性は \member{action} と同じくらい
重要ですが、\emph{全ての} オプションで意味をなすのは\member{action} だけなのです。


\subsubsection{標準的なオプション・アクション
  \label{optparse-standard-option-actions}}

様々なオプション・アクションにはどれも互いに少しづつ異なった条件と作用があります。
ほとんどのアクションに関連するオプション属性がいくつかあり、値を指定して
\module{optparse}の挙動を操作できます; いくつかのアクションには必須の属性
があり、必ず値を指定せねばなりません。
\begin{itemize}
\item {} 
\code{store} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]

オプションの後には必ず引数が続きます。引数は\member{type} に従った値に変換されて
\member{dest} に保存されます。\var{nargs} {\textgreater} 1 の場合、
複数の引数をコマンドラインから取り出します; 引数は全て \member{type} に従って
変換され、\member{dest} にタプルとして保存されます。
下記の \ref{optparse-standard-option-types} 節「標準のオプション型」 を
参照してください。

\code{choices} を(文字列のリストかタプルで) 指定した場合、型のデフォルト値は
 ``choice'' になります。


\member{type} を指定しない場合、デフォルトの値は \code{string} です。

\member{dest} を指定しない場合、 \module{optparse} は保存先を最初の長い形式の
オプション文字列から導出します (例えば、\code{"-{}-foo-bar"} は
 \code{foo{\_}bar} になります)。長い形式のオプション文字列がない場合、
\module{optparse} は最初の短い形式のオプションから保存先の変数名を導出します
(\code{"-f"} は \code{f} になります)。

例えば:
\begin{verbatim}
parser.add_option("-f")
parser.add_option("-p", type="float", nargs=3, dest="point")
\end{verbatim}
とすると、以下のようなコマンドライン:

\begin{verbatim}
-f foo.txt -p 1 -3.5 4 -fbar.txt
\end{verbatim}
を解析した場合、\module{optparse} は
\begin{verbatim}
options.f = "foo.txt"
options.point = (1.0, -3.5, 4.0)
options.f = "bar.txt"
\end{verbatim}
のように設定を行います。

\item {} 
\code{store{\_}const} {[}required: \code{const}; relevant: \member{dest}]

値\code{cost} を\member{dest} に保存します。

例えば:
\begin{verbatim}
parser.add_option("-q", "--quiet",
                  action="store_const", const=0, dest="verbose")
parser.add_option("-v", "--verbose",
                  action="store_const", const=1, dest="verbose")
parser.add_option("--noisy",
                  action="store_const", const=2, dest="verbose")
\end{verbatim}
とします。

\code{"-{}-noisy"} が見つかると、 \module{optparse} は
\begin{verbatim}
options.verbose = 2
\end{verbatim}
のように設定を行います。

\item {} 
\code{store{\_}true} {[}relevant: \member{dest}]

\code{store{\_}const} の特殊なケースで、真 (True) を\member{dest} に保存します。

\item {} 
\code{store{\_}false} {[}relevant: \member{dest}]

\code{store{\_}true} と同じですが、偽 (False) を保存します。

例:
\begin{verbatim}
parser.add_option("--clobber", action="store_true", dest="clobber")
parser.add_option("--no-clobber", action="store_false", dest="clobber")
\end{verbatim}

\item {} 
\code{append} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]

このオプションの後ろには必ず引数が続きます。引数は\member{dest} のリストに
追加されます。\member{dest} のデフォルト値を指定しなかった場合、
\module{optparse} がこのオプションを最初にみつけた時点で空のリストを自動的に生成します。
\code{nargs} {\textgreater} 1 の場合、複数の引数をコマンドラインから取り出し、
長さ \code{nargs} のタプルを生成して \member{dest}に追加します。

\member{type} および \member{dest} のデフォルト値は \code{store} アクションと
同じです。

例:
\begin{verbatim}
parser.add_option("-t", "--tracks", action="append", type="int")
\end{verbatim}

\code{"-t3"} がコマンドライン上で見つかると、\module{optparse} は:
\begin{verbatim}
options.tracks = []
options.tracks.append(int("3"))
\end{verbatim}
と同等の処理を行います。

その後、\code{"-{}-tracks=4"} が見つかると:
\begin{verbatim}
options.tracks.append(int("4"))
\end{verbatim}
を実行します。

\item {} 
\code{append{\_}const} {[}required: \code{const}; relevant: \member{dest}]

\code{store{\_}const} と同様ですが、\code{const} の値は \member{dest} に
追加(append)されます。
\code{append} の場合と同じように \member{dest} のデフォルトは \code{None} ですが
このオプションを最初にみつけた時点で空のリストを自動的に生成します。

\item {} 
\code{count} {[}relevant: \member{dest}]

\member{dest} に保存されている整数値をインクリメントします。
\member{dest} は (デフォルトの値を指定しない限り) 最初にインクリメントを
行う前にゼロに設定されます。

例:
\begin{verbatim}
parser.add_option("-v", action="count", dest="verbosity")
\end{verbatim}

コマンドライン上で最初に \code{"-v"} が見つかると、\module{optparse} は:
\begin{verbatim}
options.verbosity = 0
options.verbosity += 1
\end{verbatim}
と同等の処理を行います。

以後、\code{"-v"} が見つかるたびに、
\begin{verbatim}
options.verbosity += 1
\end{verbatim}
を実行します。

\item {} 
\code{callback} {[}required: \code{callback};
relevant: \member{type}, \code{nargs}, \code{callback{\_}args}, \code{callback{\_}kwargs}]

\code{callback} に指定された関数を次のように呼び出します。
\begin{verbatim}
func(option, opt_str, value, parser, *args, **kwargs)
\end{verbatim}

詳細は、\ref{optparse-option-callbacks} 節「オプション処理コールバック」を
参照してください。


\item {} 
\member{help}

現在のオプションパーザ内の全てのオプションに対する完全なヘルプメッセージを出力します。
ヘルプメッセージは \class{OptionParser} のコンストラクタに渡した\code{usage} 
文字列と、各オプションに渡した \member{help} 文字列から生成します。

オプションに \member{help} 文字列が指定されていなくても、オプションは
ヘルプメッセージ中に列挙されます。オプションを完全に表示させないようにするには、
特殊な値 \code{optparse.SUPPRESS{\_}HELP} を使ってください。

\module{optparse} は全ての\class{OptionParser} に自動的に\member{help} 
オプションを追加するので、通常自分で生成する必要はありません。

例:
\begin{verbatim}
from optparse import OptionParser, SUPPRESS_HELP

parser = OptionParser()
parser.add_option("-h", "--help", action="help"),
parser.add_option("-v", action="store_true", dest="verbose",
                  help="Be moderately verbose")
parser.add_option("--file", dest="filename",
                  help="Input file to read data from"),
parser.add_option("--secret", help=SUPPRESS_HELP)
\end{verbatim}

\module{optparse} がコマンドライン上に \code{"-h"} または 
\code{"-{}-help"} を見つけると、以下のようなヘルプメッセージを
標準出力に出力します (\code{sys.argv{[}0]} は\code{"foo.py"}
だとします):
\begin{verbatim}
usage: foo.py [options]

options:
  -h, --help        Show this help message and exit
  -v                Be moderately verbose
  --file=FILENAME   Input file to read data from
\end{verbatim}

ヘルプメッセージの出力後、\module{optparse} は \code{sys.exit(0)}
でプロセスを終了します。

\item {} 
\code{version}

\class{OptionParser} に指定されているバージョン番号を標準出力に
出力して終了します。バージョン番号は、実際には \class{OptionParser}
の\method{print_version()} メソッドで書式化されてから出力されます。
通常、 \class{OptionParser} のコンストラクタに \var{version}
が指定されたときのみ関係のあるアクションです。
\member{help} オプションと同様、\module{optparse} はこのオプションを
必要に応じて自動的に追加するので、\code{version} オプションを作成する
ことはほとんどないでしょう。
\end{itemize}


\subsubsection{オプション属性\label{optparse-option-attributes}}

以下のオプション属性は \code{parser.add{\_}option()} へのキーワード引数として
渡すことができます。特定のオプションに無関係なオプション属性を渡した場合、
または必須のオプションを渡しそこなった場合、\module{optparse} は OptionError
を送出します。
\begin{itemize}
\item {}
\member{action} (デフォルト: \code{"store"})

このオプションがコマンドラインにあった場合に \module{optparse} に何をさせるかを決めます。
取りうるオプションについては既に説明しました。

\item {} 
\member{type} (デフォルト: \code{"string"})

このオプションに与えられる引数の型 (たとえば \code{"string"} や
\code{"int"}) です。取りうるオプションの型については既に説明しました。

\item {} 
\member{dest} (デフォルト: オプション文字列から)

このオプションのアクションがある値をどこかに書いたり書き換えたりを意味する場合、
これは \module{optparse} にその書く場所を教えます。詳しく言えば
\member{dest} には \module{optparse} がコマンドラインを解析しながら
組み立てる \code{options} オブジェクトの属性の名前を指定します。

\item {} 
\code{default} (非推奨)

コマンドラインに指定がなかったときにこのオプションの対象に使われる値です。
使用は推奨されません。代わりに \code{parser.set{\_}defaults()} を使ってください。

\item {} 
\code{nargs} (デフォルト: 1)

このオプションがあったときに幾つの \member{type} 型の引数が消費されるべきかを
指定します。もし {\textgreater} 1 ならば、\module{optparse} は \member{dest}
に値のタプルを格納します。

\item {} 
\code{const}

定数を格納する動作のための、その定数です。

\item {} 
\code{choices}

\code{"choice"} 型オプションに対してユーザがその中から選べる文字列のリストです。

\item {} 
\code{callback}

アクションが \code{"callback"} であるオプションに対し、このオプションがあったときに
呼ばれる呼び出し可能オブジェクトです。\code{callable} に渡す引数の詳細については、
\ref{optparse-option-callbacks} 節「オプション処理コールバック」を参照してください。

\item {} 
\code{callback{\_}args}, \code{callback{\_}kwargs}

\code{callback} に渡される標準的な4つのコールバック引数の後ろに追加する
位置による引数またはキーワード引数です。

\item {} 
\member{help}

ユーザが \member{help} オプション(\code{"-{}-help"} のような)を指定したときに
表示される使用可能な全オプションのリストの中のこのオプションに関する説明文です。
説明文を提供しておかなければ、オプションは説明文なしで表示されます。
オプションを隠すには特殊な値 \code{SUPPRESS{\_}HELP} を使います。

\item {} 
\code{metavar} (デフォルト: オプション文字列から)

説明文を表示する際にオプションの引数の身代わりになるものです。
例は \ref{optparse-tutorial} 節のチュートリアルを参照してください。

\end{itemize}


\subsubsection{標準のオプション型\label{optparse-standard-option-types}}

\module{optparse} には、\dfn{string} (文字列)、\dfn{int} (整数)、 
\dfn{long} (長整数)、 \dfn{choice} (選択肢)、 \dfn{float} (浮動小数点数) 
および \dfn{complex} (複素数) の 6 種類のオプション型があります。
新たなオプションの型を追加したければ、\ref{optparse-extending-optparse} 節、
「\module{optparse} の拡張」を参照してください。

文字列オプションの引数はチェックや変換を一切受けません: コマンドライン上のテキストは
保存先にそのまま保存されます (またはコールバックに渡されます)。

整数引数 (\code{int} 型や \code{long} 型) は次のように読み取られます。
\begin{quote}
\begin{itemize}
\item {} 
数が \code{0x} から始まるならば、16進数として読み取られます

\item {} 
数が \code{0} から始まるならば、8進数として読み取られます

\item {} 
数が \code{0b} から始まるならば、2進数として読み取られます

\item {} 
それ以外の場合、数は10進数として読み取られます

\end{itemize}
\end{quote}

変換は適切な底(2, 8, 10, 16 のどれか)とともに \code{int()} または \code{long()}
を呼び出すことで行なわれます。
この変換が失敗した場合 \module{optparse} の処理も失敗に終わりますが、
より役に立つエラーメッセージを出力します。

\code{float} および \code{complex} のオプション引数は直接
\code{float()} や \code{complex()} で変換されます。
エラーは同様の扱いです。

\code{choice} オプションは \code{string} オプションのサブタイプです。
\code{choice} オプションの属性 (文字列からなるシーケンス) には、利用できる
オプション引数のセットを指定します。\code{optparse.check{\_}choice()}
はユーザの指定したオプション引数とマスタリストを比較して、無効な文字列が
指定された場合には\exception{OptionValueError} を送出します。


\subsubsection{引数の解析\label{optparse-parsing-arguments}}

OptionParser を作成してオプションを追加していく上で大事なポイントは、
\method{parse{\_}args()} メソッドの呼び出しです。
\begin{verbatim}
(options, args) = parser.parse_args(args=None, options=None)
\end{verbatim}

ここで入力パラメータは
\begin{description}
\item[\code{args}]
処理する引数のリスト (デフォルト: \code{sys.argv{[}1:]})
\item[\code{options}]
オプション引数を格納するオブジェクト (デフォルト: 新しい optparse.Values のインスタンス)
\end{description}

であり、戻り値は
\begin{description}
\item[\code{options}]
\code{options} に渡されたものと同じオブジェクト、または
\module{optparse} によって生成された optparse.Values インスタンス
\item[\code{args}]
全てのオプションの処理が終わった後で残った位置引数
\end{description}
です。

一番普通の使い方は一切キーワード引数を使わないというものです。
\code{options} を指定した場合、それは繰り返される \code{setattr()}
の呼び出し (大雑把に言うと保存される各オプション引数につき一回ずつ)
で更新されていき、\method{parse{\_}args()} で返されます。

\method{parse{\_}args()} が引数リストでエラーに遭遇した場合、
OptionParser の \method{error()} メソッドを適切なエンドユーザ向けの
エラーメッセージとともに呼び出します。この呼び出しにより、最終的に終了ステータス 2
(伝統的な \UNIX{} におけるコマンドラインエラーの終了ステータス)
でプロセスを終了させることになります。


\subsubsection{オプション解析器への問い合わせと操作\label{optparse-querying-manipulating-option-parser}}

自前のオプションパーザをつつきまわして、何が起こるかを調べると便利
なことがあります。\class{OptionParser} では便利な二つのメソッドを提供
しています:

\begin{description}
\item[\code{has{\_}option(opt{\_}str)}]
\class{OptionParser} に(\code{"-q"} や \code{"-{}-verbose"} のような)
オプション \code{opt{\_}str} がある場合、真を返します。
\item[\code{get{\_}option(opt{\_}str)}]
オプション文字列\code{opt{\_}str}に対する\class{Option} インスタンスを返します。
該当するオプションがなければ \code{None} を返します。
\item[\code{remove{\_}option(opt{\_}str)}]
\class{OptionParser} に\code{opt{\_}str} に対応するオプションがある場合、
そのオプションを削除します。該当するオプションに他のオプション文字列が指定されて
いた場合、それらのオプション文字列は全て無効になります。
\code{opt{\_}str} がこの \class{OptionParser} オブジェクトのどのオプション
にも属さない場合、\exception{ValueError} を送出します。
\end{description}


\subsubsection{オプション間の衝突\label{optparse-conflicts-between-options}}

注意が足りないと、衝突するオプションを定義しやすくなります:

\begin{verbatim}
parser.add_option("-n", "--dry-run", ...)
[...]
parser.add_option("-n", "--noisy", ...)
\end{verbatim}

(とりわけ、\class{OptionParser} から標準的なオプションを備えた自前のサブクラスを
定義してしまった場合にはよく起きます。)

ユーザがオプションを追加するたびに、\module{optparse} は既存のオプションとの衝突
がないかチェックします。何らかの衝突が見付かると、現在設定されている衝突処理メカニズム
を呼び出します。衝突処理メカニズムはコンストラクタ中で呼び出せます:
\begin{verbatim}
parser = OptionParser(..., conflict_handler=handler)
\end{verbatim}

個別にも呼び出せます:
\begin{verbatim}
parser.set_conflict_handler(handler)
\end{verbatim}

衝突時の処理をおこなうハンドラ(handler)には、以下のものが利用できます:
\begin{quote}
\begin{description}
\item[\code{error} (デフォルトの設定)]
オプション間の衝突をプログラム上のエラーとみなし、
\exception{OptionConflictError} を送出します。
\item[\code{resolve}]
オプション間の衝突をインテリジェントに解決します (下記参照)。
\end{description}
\end{quote}

一例として、衝突をインテリジェントに解決する\class{OptionParser}
を定義し、衝突を起こすようなオプションを追加してみましょう:
\begin{verbatim}
parser = OptionParser(conflict_handler="resolve")
parser.add_option("-n", "--dry-run", ..., help="do no harm")
parser.add_option("-n", "--noisy", ..., help="be noisy")
\end{verbatim}

この時点で、\module{optparse} はすでに追加済のオプションが
オプション文字列 \code{"-n"} を使っていることを検出します。
\code{conflict{\_}handler} が \code{"resolve"} なので、
\module{optparse}は既に追加済のオプションリストの方から
\code{"-n"} を除去して問題を解決します。従って、\code{"-n"} の除去
されたオプションは\code{"-{}-dry-run"} だけでしか有効にできなく
なります。ユーザがヘルプ文字列を要求した場合、問題解決の結果を反映した
メッセージが出力されます:
\begin{verbatim}
options:
  --dry-run     do no harm
  [...]
  -n, --noisy   be noisy
\end{verbatim}

これまでに追加したオプション文字列を跡形もなく削り去り、ユーザがそのオプションを
コマンドラインから起動する手段をなくせます。
この場合、\module{optparse} はオプションを完全に除去してしまうので、
こうしたオプションはヘルプテキストやその他のどこにも表示されなくなります。
例えば、現在の \class{OptionParser} の場合、以下の操作:

\begin{verbatim}
parser.add_option("--dry-run", ..., help="new dry-run option")
\end{verbatim}

を行った時点で、最初の \programopt{-n/-{}-dry-run}
オプションはもはやアクセスできなくなります。このため、\module{optparse} は
オプションを消去してしまい、ヘルプテキスト:

\begin{verbatim}
options:
  [...]
  -n, --noisy   be noisy
  --dry-run     new dry-run option
\end{verbatim}

だけが残ります。


\subsubsection{クリーンアップ\label{optparse-cleanup}}

OptionParser インスタンスはいくつかの循環参照を抱えています。
このことは Python のガーベジコレクタにとって問題になるわけではありませんが、
使い終わった OptionParser に対して \code{destroy()} を呼び出すことで
この循環参照を意図的に断ち切るという方法を選ぶこともできます。
この方法は特に長時間実行するアプリケーションで OptionParser から
大きなオブジェクトグラフが到達可能になっているような場合に有用です。


\subsubsection{その他のメソッド\label{optparse-other-methods}}

OptionParser にはその他にも幾つかの公開されたメソッドがあります:
\begin{itemize}
\item {} 
\code{set{\_}usage(usage)}

上で説明したコンストラクタの \code{usage} キーワード引数での規則に従った
使用法の文字列をセットします。\code{None} を渡すとデフォルトの使用法文字列が
使われるようになり、\code{SUPPRESS{\_}USAGE} によって使用法メッセージを
抑制できます。

\item {} 
\code{enable{\_}interspersed{\_}args()}, \code{disable{\_}interspersed{\_}args()}

位置引数をオプションと混ぜこぜにする GNU getopt のような扱いを有効化/無効化する
(デフォルトでは有効)。たとえば、\code{"-a"} と \code{"-b"} はどちらも引数を
取らない単純なオプションだとすると、\module{optparse} は通常つぎのような文法を
受け入れます。
\begin{verbatim}
prog -a arg1 -b arg2
\end{verbatim}

そして扱いは次のように指定した時と同じです。
\begin{verbatim}
prog -a -b arg1 arg2
\end{verbatim}

この機能を無効化したい時は \code{disable{\_}interspersed{\_}args()} を
呼び出してください。この呼び出しにより、伝統的な \UNIX{} 文法に回帰し、
オプションの解析は最初のオプションでない引数で止まるようになります。

\item {} 
\code{set{\_}defaults(dest=value, ...)}

幾つかの保存先に対してデフォルト値をまとめてセットします。
\method{set{\_}defaults()} を使うのは複数のオプションにデフォルト値をセットする
好ましいやり方です。というのも複数のオプションが同じ保存先を共有することがあり得るからです。
たとえば幾つかの ``mode'' オプションが全て同じ保存先をセットするものだったとすると、
どのオプションもデフォルトをセットすることができ、しかし最後に指定したものが勝ちます。
\begin{verbatim}
parser.add_option("--advanced", action="store_const",
                  dest="mode", const="advanced",
                  default="novice")    # 上書きされます
parser.add_option("--novice", action="store_const",
                  dest="mode", const="novice",
                  default="advanced")  # 上の設定を上書きします
\end{verbatim}

こうした混乱を避けるために \method{set{\_}defaults()} を使います。
\begin{verbatim}
parser.set_defaults(mode="advanced")
parser.add_option("--advanced", action="store_const",
                  dest="mode", const="advanced")
parser.add_option("--novice", action="store_const",
                  dest="mode", const="novice")
\end{verbatim}

\end{itemize}


\subsection{オプション処理コールバック\label{optparse-option-callbacks}}

\module{optparse} の組み込みのアクションや型が望みにかなったものでない
場合、二つの選択肢があります: 一つは \module{optparse} の拡張、もう一つは
callback オプションの定義です。
\module{optparse} の拡張は汎用性に富んでいますが、単純なケースに対して
いささか大げさでもあります。大体は簡単なコールバックで事足りるでしょう。

\code{callback} オプションの定義は二つのステップからなります:
\begin{itemize}
\item {} 
\code{callback} アクションを使ってオプション自体を定義する。

\item {} 
コールバックを書く。コールバックは少なくとも後で説明する 4 つの引数を
とる関数 (またはメソッド) でなければなりません。

\end{itemize}


\subsubsection{callbackオプションの定義\label{optparse-defining-callback-option}}

callbackオプションを最も簡単に定義するには、
\code{parser.add{\_}option()} メソッドを使います。
\member{action} の他に指定しなければならない属性は \code{callback}、
すなわちコールバックする関数自体です:
\begin{verbatim}
parser.add_option("-c", action="callback", callback=my_callback)
\end{verbatim}

\code{callback} は関数 (または呼び出し可能オブジェクト)なので、callback
オプションを定義する時にはあらかじめ \code{my{\_}callback()} を定義しておかねば
なりません。この単純なケースでは、\module{optparse} は \programopt{-c} が
何らかの引数をとるかどうか判別できず、通常は\programopt{-c} が引数を
伴わないことを意味します --- 知りたいことはただ単に \programopt{-c} がコマンドライン上に
現れたどうかだけです。とはいえ、場合によっては、自分のコールバック関数に
任意の個数のコマンドライン引数を消費させたいこともあるでしょう。これがコールバック関数
をトリッキーなものにしています; これについてはこの節の後の方で説明します。

\module{optparse} は常に四つの引数をコールバックに渡し、その他には
\code{callback{\_}args} および \code{callback{\_}kwargs} で指定した
追加引数しか渡しません。従って、最小のコールバック関数シグネチャは:
\begin{verbatim}
def my_callback(option, opt, value, parser):
\end{verbatim}
のようになります。

コールバックの四つの引数については後で説明します。

callback オプションを定義する場合には、他にもいくつかオプション属性を
指定できます:
\begin{description}
\item[\member{type}]
他で使われているのと同じ意味です: \code{store} や \code{append} アクションの時と同じく、
この属性は\module{optparse}に引数を一つ消費して、\member{type} に指定した
型に変換させます。\module{optparse} は変換後の値をどこかに保存する代わりに
コールバック関数に渡します。
\item[\code{nargs}]
これも他で使われているのと同じ意味です: このオプションが指定されていて、
かつ \code{nargs} {\textgreater} 1 である場合、 \module{optparse}
は\code{nargs} 個の引数を消費します。このとき各引数は \member{type} 
型に変換できねばなりません。変換後の値はタプルとしてコールバックに渡されます。
\item[\code{callback{\_}args}]
その他の固定引数からなるタプルで、コールバックに渡されます。
\item[\code{callback{\_}kwargs}]
その他のキーワード引数からなるタプルで、コールバックに渡されます。
\end{description}


\subsubsection{コールバック関数はどのように呼び出されるか\label{optparse-how-callbacks-called}}

コールバックは全て以下の形式で呼び出されます:
\begin{verbatim}
func(option, opt_str, value, parser, *args, **kwargs)
\end{verbatim}

ここで、
\begin{description}
\item[\code{option}]
コールバックを呼び出している \class{Option} のインスタンスです。
\item[\code{opt{\_}str}]
は、コールバック呼び出しのきっかけとなったコマンドライン上のオプション文字列です。
(長い形式のオプションに対する省略形が使われている場合、\var{opt} は完全な、
正式な形のオプション文字列となります --- 
例えば、ユーザが \longprogramopt{foobar} の短縮形として
\code{"-{}-foo"} をコマンドラインに入力した時には、\var{opt{\_}str} 
は \code{"-{}-foobar"} となります。)
\item[\code{value}]
オプションの引数で、コマンドライン上に見つかったものです。
\module{optparse} は、\code{type} が設定されている場合、
単一の引数しかとりません;\code{value} の型はオプションの型
として指定された型になります。このオプションに対する \member{type} が
None である(引数なしの) 場合、\var{value} は None になります。
\samp{nargs} {\textgreater} 1 であれば、\code{value} は
は適切な型をもつ値のタプルになります。
\item[\code{parser}]
現在のオプション解析の全てを駆動している \class{OptionParser} 
インスタンスです。この変数が有用なのは、この値を介してインスタンス属性と
していくつかの興味深いデータにアクセスできるからです:
\begin{description}
\item[\code{parser.largs}]
現在放置されている引数、すなわち、すでに消費されたものの、オプションでも
オプション引数でもない引数からなるリストです。
\code{parser.largs} は自由に変更でき、
たとえば引数を追加したりできます (このリストは \code{args} 、すなわち
\method{parse{\_}args()} の二つ目の戻り値になります)
\item[\code{parser.rargs}]
現在残っている引数、すなわち、 \code{opt{\_}str} および
\code{value} があれば除き、それ以外の引数が残っているリストです。
\code{parser.rargs} は自由に変更でき、例えばさらに引数を消費したり
できます。
\item[\code{parser.values}]
オプションの値がデフォルトで保存されるオブジェクト (\code{optparse.OptionValues}
のインスタンス} です。この値を使うと、コールバック関数がオプションの値を記憶するために、
他の\module{optparse} と同じ機構を使えるようにするため、グローバル変数や閉包
(closure) を台無しにしないので便利です。
コマンドライン上にすでに現れているオプションの値にもアクセスできます。
\end{description}
\item[\code{args}]
\code{callback{\_}args} オプション属性で与えられた任意の固定引数
からなるタプルです。
\item[\code{kwargs}]
\code{callback{\_}args} オプション属性で与えられた任意のキーワード引数
からなるタプルです。
\end{description}


\subsubsection{コールバック中で例外を送出する\label{optparse-raising-errors-in-callback}}

オプション自体か、あるいはその引数に問題があるばあい、コールバック関数は
\exception{OptionValueError} を送出せねばなりません。\module{optparse} は
この例外をとらえてプログラムを終了させ、ユーザが指定しておいたエラーメッセージを
標準エラー出力に出力します。エラーメッセージは明確、簡潔かつ正確で、どの
オプションに誤りがあるかを示さねばなりません。さもなければ、ユーザは自分の
操作のどこに問題があるかを解決するのに苦労することになります。


\subsubsection{コールバックの例 1: ありふれたコールバック\label{optparse-callback-example-1}}

引数をとらず、発見したオプションを単に記録するだけのコールバックオプションの例を
以下に示します:
\begin{verbatim}
def record_foo_seen(option, opt_str, value, parser):
    parser.saw_foo = True

parser.add_option("--foo", action="callback", callback=record_foo_seen)
\end{verbatim}

もちろん、\code{store{\_}true} アクションを使っても実現できます。


\subsubsection{コールバックの例 2: オプションの順番をチェックする\label{optparse-callback-example-2}}

もう少し面白みのある例を示します: この例では、\code{"-b"} を発見して、その後で
\code{"-a"} がコマンドライン中に現れた場合にはエラーになります。
\begin{verbatim}
def check_order(option, opt_str, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use -a after -b")
    parser.values.a = 1
[...]
parser.add_option("-a", action="callback", callback=check_order)
parser.add_option("-b", action="store_true", dest="b")
\end{verbatim}


\subsubsection{コールバックの例 3: オプションの順番をチェックする (汎用的)\label{optparse-callback-example-3}}

このコールバック (フラグを立てるが、\code{"-b"} が既に指定されていればエラーになる) 
を同様の複数のオプションに対して再利用したければ、もう少し作業する必要があります:
エラーメッセージとセットされるフラグを一般化しなければなりません。
\begin{verbatim}
def check_order(option, opt_str, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use %s after -b" % opt_str)
    setattr(parser.values, option.dest, 1)
[...]
parser.add_option("-a", action="callback", callback=check_order, dest='a')
parser.add_option("-b", action="store_true", dest="b")
parser.add_option("-c", action="callback", callback=check_order, dest='c')
\end{verbatim}


\subsubsection{コールバックの例 4: 任意の条件をチェックする\label{optparse-callback-example-4}}

もちろん、単に定義済みのオプションの値を調べるだけにとどまらず、コールバックには
任意の条件を入れられます。例えば、満月でなければ呼び出してはならないオプション
があるとしましょう。やらなければならないことはこれだけです:
\begin{verbatim}
def check_moon(option, opt_str, value, parser):
    if is_moon_full():
        raise OptionValueError("%s option invalid when moon is full"
                               % opt_str)
    setattr(parser.values, option.dest, 1)
[...]
parser.add_option("--foo",
                  action="callback", callback=check_moon, dest="foo")
\end{verbatim}

(\code{is{\_}moon{\_}full()} の定義は読者への課題としましょう。


\subsubsection{コールバックの例5: 固定引数\label{optparse-callback-example-5}}

決まった数の引数をとるようなコールパックオプションを定義するなら、問題はやや興味深く
なってきます。引数をとるようコールバックに指定するのは、\code{store} や
\code{append} オプションの定義に似ています: \member{type} を定義していれば、
そのオプションは引数を受け取ったときに該当する型に変換できねばなりません;
さらに \code{nargs} を指定すれば、オプションは \code{nargs} 個の引数を
受け取ります。

標準の \code{store} アクションをエミュレートする例を以下に示します:
\begin{verbatim}
def store_value(option, opt_str, value, parser):
    setattr(parser.values, option.dest, value)
[...]
parser.add_option("--foo",
                  action="callback", callback=store_value,
                  type="int", nargs=3, dest="foo")
\end{verbatim}

\module{optparse} は 3 個の引数を受け取り、それらを整数に変換するところまで
面倒をみてくれます; ユーザは単にそれを保存するだけです。 (他の処理もできます;
いうまでもなく、この例にはコールバックは必要ありません) 


\subsubsection{コールバックの例6: 可変個の引数\label{optparse-callback-example-6}}

あるオプションに可変個の引数を持たせたいと考えているなら、問題はいささか手強く
なってきます。この場合、\module{optparse} では該当する組み込みのオプション解析
機能を提供していないので、自分でコールバックを書かねばなりません。さらに、
\module{optparse} が普段処理している、伝統的な \UNIX{} コマンドライン解析における
難題を自分で解決せねばなりません。とりわけ、コールバック関数では
引数が裸の\code{"-{}-"} や \code{"-"} の場合における慣習的な処理規則:
\begin{itemize}
\item {} 
either \code{"-{}-"} or \code{"-"} can be option arguments

\item {} 
裸の \code{"-{}-"} (何らかのオプションの引数でない場合): コマンドライン処理を
停止し、\code{"-{}-"}を無視します。

\item {} 
裸の\code{"-"} (何らかのオプションの引数でない場合): コマンドライン処理を停止しますが、
\code{"-"} は残します (\code{parser.largs} に追加します)。

\end{itemize}

を実装せねばなりません。

オプションが可変個の引数をとるようにさせたいなら、いくつかの
巧妙で厄介な問題に配慮しなければなりません。どういう実装を
とるかは、アプリケーションでどのようなトレードオフを考慮するか
によります (このため、\module{optparse} では可変個の引数に
関する問題を直接的に取り扱わないのです)。

とはいえ、可変個の引数をもつオプションに対するスタブ (stub、仲介
インタフェース) を以下に示しておきます:

\begin{verbatim}
def vararg_callback(option, opt_str, value, parser):
    assert value is None
    done = 0
    value = []
    rargs = parser.rargs
    while rargs:
        arg = rargs[0]

        # "--foo", "-a", "-fx", "--file=f" といった引数で停止。
        # "-3" や "-3.0" でも止まるので、オプションに数値が入る場合には
        # それを処理せねばならない。
        if ((arg[:2] == "--" and len(arg) > 2) or
            (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):
            break
        else:
            value.append(arg)
            del rargs[0]

     setattr(parser.values, option.dest, value)

[...]
parser.add_option("-c", "--callback",
                  action="callback", callback=varargs)
\end{verbatim}

この実装固有の弱点は、\code{"-c"} 以後に続いて負の数を表す
引数があった場合、その引数は \code{"-c"} の引数ではなく次の
オプションとして解釈される(そしておそらくエラーを引き起こす)
ということです。この問題の修正は読者の練習課題としておきます。


\subsection{\module{optparse} の拡張\label{optparse-extending-optparse}}

\module{optparse} がコマンドラインオプションをどのように解釈するかを決
める二つの重要な要素はそれぞれのオプションのアクションと型なので、拡張
の方向は新しいアクションと型を追加することになると思います。


\subsubsection{新しい型の追加\label{optparse-adding-new-types}}

新しい型を追加するためには、\module{optparse} の Option クラスのサブクラスを
自身で定義する必要があります。このクラスには \module{optparse} における型を定義する
一対の属性があります。それは \member{TYPES} と \member{TYPE{\_}CHECKER} です。

\member{TYPES} は型名のタプルです。新しく作るサブクラスでは、
タプル \member{TYPES} は単純に標準的なもののを利用して定義すると良いでしょう。

\member{TYPE{\_}CHECKER} は辞書で型名を型チェック関数に対応付けるものです。
型チェック関数は以下のような引数をとります。
\begin{verbatim}
def check_mytype(option, opt, value)
\end{verbatim}

ここで \code{option} は \class{Option} のインスタンスであ
り、\code{opt} はオプション文字列(たとえ
ば \code{"-f"})で、\code{value} は望みの型としてチェックされ変換される
べくコマンドラインで与えられる文字列です。\code{check{\_}mytype()} は想
定されている型 \code{mytype} のオブジェクトを返さなければなりません。型
チェック関数から返される値は \method{OptionParser.parse{\_}args()} で返
されるOptionValues インスタンスに収められるか、またはコールバック
に \code{value} パラメータとして渡されます。

型チェック関数は何か問題に遭遇したら OptionValueError を送出しなければなりません。
OptionValueError は文字列一つを引数に取り、それはそのまま OptionParser の
\method{error()} メソッドに渡され、そこでプログラム名と文字列 \code{"error:"}
が前置されてプロセスが終了する前に stderr に出力されます。

馬鹿馬鹿しい例ですが、Python スタイルの複素数を解析する \code{complex} オプション型
を作ってみせることにします。(\module{optparse} 1.3 が複素数のサポートを
組み込んでしまったため以前にも増して馬鹿らしくなりましたが、気にしないでください。)

最初に必要な import 文を書きます。
\begin{verbatim}
from copy import copy
from optparse import Option, OptionValueError
\end{verbatim}

まずは型チェック関数を定義しなければなりません。
これは後で(これから定義する Option のサブクラスの \member{TYPE{\_}CHECKER} クラス属性
の中で)参照されることになります。
\begin{verbatim}
def check_complex(option, opt, value):
    try:
        return complex(value)
    except ValueError:
        raise OptionValueError(
            "option %s: invalid complex value: %r" % (opt, value))
\end{verbatim}

最後に Option のサブクラスです。
\begin{verbatim}
class MyOption (Option):
    TYPES = Option.TYPES + ("complex",)
    TYPE_CHECKER = copy(Option.TYPE_CHECKER)
    TYPE_CHECKER["complex"] = check_complex
\end{verbatim}

(もしここで \member{Option.TYPE{\_}CHECKER} に \function{copy()} を適用しなければ、
\module{optparse} の Option クラスの \member{TYPE{\_}CHECKER} 属性をいじってしまう
ことになります。Python の常として、良いマナーと常識以外にそうすることを止めるものは
ありません。)

これだけです! もう新しいオプション型を使うスクリプトを他の \module{optparse} に基づいた
スクリプトとまるで同じように書くことができます。ただし、 OptionParser に Option でなく
MyOption を使うように指示しなければなければなりません。
\begin{verbatim}
parser = OptionParser(option_class=MyOption)
parser.add_option("-c", type="complex")
\end{verbatim}

別のやり方として、オプションリストを構築して OptionParser に渡すという方法もあります。
\method{add{\_}option()} を上でやったように使わないならば、OptionParser に
どのクラスを使うのか教える必要はありません。
\begin{verbatim}
option_list = [MyOption("-c", action="store", type="complex", dest="c")]
parser = OptionParser(option_list=option_list)
\end{verbatim}


\subsubsection{新しいアクションの追加\label{optparse-adding-new-actions}}

新しいアクションの追加はもう少しトリッキーです。というのも \module{optparse} 
が使っている二つのアクションの分類を理解する必要があるからです。
\begin{description}
\item[``store'' アクション]
\module{optparse} が値を現在の OptionValues の属性に格納することになるアクションです。
この種類のオプションは Option のコンストラクタに \member{dest} 属性を与えることが
要求されます。
\item[``typed'' アクション]
コマンドラインから引数を受け取り、それがある型であることが期待されているアクションです。
もう少しはっきり言えば、その型に変換される文字列を受け取るものです。
この種類のオプションは Option のコンストラクタに \member{type} 属性を与えることが
要求されます。
\end{description}

この分類には重複する部分があります。デフォルトの ``store'' アクションには
\code{store}、\code{store{\_}const}、\code{append}、\code{count} などがありますが、
デフォルトの ``typed'' オプションは \code{store}、\code{append}、\code{callback}
の三つです。

アクションを追加する際に、以下の Option のクラス属性(全て文字列のリストです)
の中の少なくとも一つに付け加えることでそのアクションを分類する必要があります。
\begin{description}
\item[\member{ACTIONS}]
全てのアクションは ACTIONS にリストされていなければなりません
\item[\member{STORE{\_}ACTIONS}]
``store'' アクションはここにもリストされます
\item[\member{TYPED{\_}ACTIONS}]
``typed'' アクションはここにもリストされます
\item[\code{ALWAYS{\_}TYPED{\_}ACTIONS}]
型を取るアクション (つまりそのオプションが値を取る) はここにもリストされます。
このことの唯一の効果は \module{optparse} が、型の指定が無くアクション
が \code{ALWAYS{\_}TYPED{\_}ACTIONS} のリストにあるオプションに、
デフォルト型 \code{string} を割り当てるということだけです。
\end{description}

実際に新しいアクションを実装するには、Option の \method{take{\_}action()} 
メソッドをオーバライドしてそのアクションを認識する場合分けを追加しなければなりません。

例えば、\code{extend} アクションというのを追加してみましょう。このアクションは
標準的な \code{append} アクションと似ていますが、コマンドラインから一つだけ値を
読み取って既存のリストに追加するのではなく、複数の値をコンマ区切りの文字列として
読み取ってそれらで既存のリストを拡張します。すなわち、もし \code{"-{}-names"} が
\code{string} 型の \code{extend} オプションだとすると、次のコマンドライン
\begin{verbatim}
--names=foo,bar --names blah --names ding,dong
\end{verbatim}

の結果は次のリストになります。
\begin{verbatim}
["foo", "bar", "blah", "ding", "dong"]
\end{verbatim}

再び Option のサブクラスを定義します。
\begin{verbatim}
class MyOption (Option):

    ACTIONS = Option.ACTIONS + ("extend",)
    STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
    TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
    ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)

    def take_action(self, action, dest, opt, value, values, parser):
        if action == "extend":
            lvalue = value.split(",")
            values.ensure_value(dest, []).extend(lvalue)
        else:
            Option.take_action(
                self, action, dest, opt, value, values, parser)
\end{verbatim}

注意すべきは次のようなところです。
\begin{itemize}
\item {} 
\code{extend} はコマンドラインの値を予期していると同時にその値をどこかに格納します
ので、\member{STORE{\_}ACTIONS} と \member{TYPED{\_}ACTIONS} の両方に入ります。

\item {} 
\module{optparse} が \code{extend} アクションに \code{string} 型を割り当てるように
\code{extend} アクションは \code{ALWAYS{\_}TYPED{\_}ACTIONS} にも入れてあります。

\item {} 
\method{MyOption.take{\_}action()} にはこの新しいアクション一つの扱いだけを
実装してあり、他の標準的な \module{optparse} のアクションについては
\method{Option.take{\_}action()} に制御を戻すようにしてあります。

\item {} 
\code{values} は optparse{\_}parser.Values クラスのインスタンスであり、
非常に有用な \method{ensure{\_}value()} メソッドを提供しています。
\method{ensure{\_}value()} は本質的に安全弁付きの \function{getattr()} です。
次のように呼び出します。
\begin{verbatim}
values.ensure_value(attr, value)
\end{verbatim}

\code{values} に \code{attr} 属性が無いか None だった場合に、
\method{ensure{\_}value()} は最初に \code{value} をセットし、
それから \code{value} を返します。
この振る舞いは \code{extend}、\code{append}、\code{count} のように、データを変数に
集積し、またその変数がある型 (最初の二つはリスト、最後のは整数) であると期待されるアクション
を作るのにとても使い易いものです。\method{ensure{\_}value()} を使えば、
作ったアクションを使うスクリプトはオプションに保存先にデフォルト値をセットすることに
煩わされずに済みます。デフォルトを None にしておけば \method{ensure{\_}value()} が
それが必要になったときに適当な値を返してくれます。

\end{itemize}
