23.1. "cmd" --- 行指向のコマンドインタープリタのサポート
********************************************************

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

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

"Cmd" クラスでは、行指向のコマンドインタープリタを書くための簡単なフレ
ームワークを提供します。テストハーネスや管理ツール、そして、後により洗
練されたインターフェイスでラップするプロトタイプとして、こうしたインタ
ープリタはよく役に立ちます。

class cmd.Cmd([completekey[, stdin[, stdout]]])

   "Cmd" インスタンス、あるいはサブクラスのインスタンスは、行指向のイ
   ンタープリタ・フレームワークです。 "Cmd" 自身をインスタンス化するこ
   とはありません。むしろ、 "Cmd" のメソッドを継承したり、アクションメ
   ソッドをカプセル化するために、あなたが自分で定義するインタープリタ
   クラスのスーパークラスとしての便利です。

   オプション引数 *completekey* は、補完キーの "readline" 名です。デフ
   ォルトは "Tab" です。 *completekey* が "None" でなく、 "readline"
   が利用できるならば、コマンド補完は自動的に行われます。

   オプション引数 *stdin* と *stdout* には、Cmd またはそのサブクラスの
   インスタンスが入出力に使用するファイルオブジェクトを指定します。省
   略時には "sys.stdin" と "sys.stdout" が使用されます。

   引数に渡した *stdin* を使いたい場合は、インスタンスの
   "use_rawinput" 属性を "False" にセットしてください。そうしないと
   *stdin* は無視されます。

   バージョン 2.3 で変更: パラメータ *stdin* と *stdout* が追加されま
   した.


23.1.1. Cmdオブジェクト
=======================

"Cmd" インスタンスは、次のメソッドを持ちます:

Cmd.cmdloop([intro])

   プロンプトを繰り返し出力し、入力を受け取り、受け取った入力から取り
   去った先頭の語を解析し、その行の残りを引数としてアクションメソッド
   へディスパッチします。

   オプションの引数は、最初のプロンプトの前に表示されるバナーあるいは
   イントロ用の文字列です (これはクラス属性 "intro" をオーバーライドし
   ます)。

   "readline" モジュールがロードされているなら、入力は自動的に
   **bash** のような履歴リスト編集機能を受け継ぎます(例えば、
   "Control-P" は直前のコマンドへのスクロールバック、 "Control-N" は次
   のものへ進む、 "Control-F" はカーソルを右へ非破壊的に進める、
   "Control-B" はカーソルを非破壊的に左へ移動させる等)。

   入力のファイル終端は、文字列 "'EOF'" として渡されます。

   メソッド "do_foo()" を持っている場合に限って、インタープリタのイン
   スタンスはコマンド名 "foo" を認識します。特別な場合として、文字
   "'?'" で始まる行はメソッド "do_help()" へディスパッチします。他の特
   別な場合として、文字 "'!'" で始まる行はメソッド "do_shell()" へディ
   スパッチします(このようなメソッドが定義されている場合)。

   このメソッドは "postcmd()" メソッドが真を返したときに return します
   。 "postcmd()" に対する *stop* 引数は、このコマンドが対応する
   "do_*()" メソッドからの返り値です。

   補完が有効になっているなら、コマンドの補完が自動的に行われます。ま
   た、コマンド引数の補完は、引数 *text*, *line*, *begidx*, および
   *endidx* と共に "complete_foo()" を呼び出すことによって行われます。
   *text* は、マッチしようとしている文字列の先頭の語です。返されるマッ
   チは全てそれで始まっていなければなりません。 *line* は始めの空白を
   除いた現在の入力行です。 *begidx* と *endidx* は先頭のテキストの始
   まりと終わりのインデックスで、引数の位置に依存した異なる補完を提供
   するのに使えます。

   "Cmd" のすべてのサブクラスは、定義済みの "do_help()" を継承します。
   このメソッドは、(引数 "'bar'" と共に呼ばれたとすると)対応するメソッ
   ド "help_bar()" を呼び出します。そのメソッドが存在しない場合、
   "do_bar()" の docstring があればそれを表示します。引数がなければ、
   "do_help()" は、すべての利用可能なヘルプ見出し(すなわち、対応する
   "help_*()" メソッドを持つすべてのコマンドまたは docstring を持つコ
   マンド)をリストアップします。また、文書化されていないコマンドでも、
   すべてリストアップします。

Cmd.onecmd(str)

   プロンプトに答えてタイプしたかのように引数を解釈実行します。これを
   オーバーライドすることがあるかもしれませんが、通常は必要ないでしょ
   う。便利な実行フックについては、 "precmd()" と "postcmd()" メソッド
   を参照してください。戻り値は、インタープリタによるコマンドの解釈実
   行をやめるかどうかを示すフラグです。コマンド *str* に対応する
   "do_*()" メソッドがある場合、そのメソッドの返り値が返されます。そう
   でない場合は "default()" メソッドからの返り値が返されます。

Cmd.emptyline()

   プロンプトに空行が入力されたときに呼び出されるメソッド。このメソッ
   ドがオーバーライドされていないなら、最後に入力された空行でないコマ
   ンドが繰り返されます。

Cmd.default(line)

   コマンドの先頭の語が認識されないときに、入力行に対して呼び出されま
   す。このメソッドがオーバーライドされていないなら、エラーメッセージ
   を表示して戻ります。

Cmd.completedefault(text, line, begidx, endidx)

   利用可能なコマンド固有の "complete_*()" が存在しないときに、入力行
   を補完するために呼び出されるメソッド。デフォルトでは、空行を返しま
   す。

Cmd.precmd(line)

   コマンド行 *line* が解釈実行される直前、しかし入力プロンプトが作ら
   れ表示された後に実行されるフックメソッド。このメソッドは "Cmd" 内の
   スタブであって、サブクラスでオーバーライドされるために存在します。
   戻り値は "onecmd()" メソッドが実行するコマンドとして使われます。
   "precmd()" の実装では、コマンドを書き換えるかもしれないし、あるいは
   単に変更していない *line* を返すかもしれません。

Cmd.postcmd(stop, line)

   コマンドディスパッチが終わった直後に実行されるフックメソッド。この
   メソッドは "Cmd" 内のスタブで、サブクラスでオーバーライドされるため
   に存在します。 *line* は実行されたコマンド行で、 *stop* は
   "postcmd()" の呼び出しの後に実行を停止するかどうかを示すフラグです
   。これは "onecmd()" メソッドの戻り値です。このメソッドの戻り値は、
   *stop* に対応する内部フラグの新しい値として使われます。偽を返すと、
   実行を続けます。

Cmd.preloop()

   "cmdloop()" が呼び出されたときに一度だけ実行されるフックメソッド。
   このメソッドは "Cmd" 内のスタブであって、サブクラスでオーバーライド
   されるために存在します。

Cmd.postloop()

   "cmdloop()" が戻る直前に一度だけ実行されるフックメソッド。このメソ
   ッドは "Cmd" 内のスタブであって、サブクラスでオーバーライドされるた
   めに存在します。

"Cmd" のサブクラスのインスタンスは、公開されたインスタンス変数をいくつ
か持っています:

Cmd.prompt

   入力を求めるために表示されるプロンプト。

Cmd.identchars

   コマンドの先頭の語として受け入れられる文字の文字列。

Cmd.lastcmd

   最後の空でないコマンドプリフィックス。

Cmd.cmdqueue

   キューに入れられた入力行のリスト。cmdqueue リストは新たな入力が必要
   な際に "cmdloop()" 内でチェックされます; これが空でない場合、その要
   素は、あたかもプロンプトから入力されたかのように順に処理されます。

Cmd.intro

   イントロあるいはバナーとして表示される文字列。 "cmdloop()" メソッド
   に引数を与えるために、オーバーライドされるかもしれません。

Cmd.doc_header

   ヘルプ出力に文書化されたコマンドのセクションがある場合に表示するヘ
   ッダ。

Cmd.misc_header

   ヘルプの出力にその他のヘルプ見出しがある(すなわち、 "do_*()" メソッ
   ドに対応していない "help_*()" メソッドが存在する)場合に表示するヘッ
   ダ。

Cmd.undoc_header

   ヘルプ出力に文書化されていないコマンドのセクションがある(すなわち、
   対応する "help_*()" メソッドを持たない "do_*()" メソッドが存在する)
   場合に表示するヘッダ。

Cmd.ruler

   ヘルプメッセージのヘッダの下に、区切り行を表示するために使われる文
   字。空のときは、ルーラ行が表示されません。デフォルトでは、"'='" で
   す。

Cmd.use_rawinput

   フラグで、デフォルトでは真です。真ならば、 "cmdloop()" はプロンプト
   を表示して次のコマンド読み込むために "raw_input()" を使います。偽な
   らば、 "sys.stdout.write()" と "sys.stdin.readline()" が使われます
   。 (これが意味するのは、 "readline" を import することによって、そ
   れをサポートするシステム上では、インタープリタが自動的に **Emacs**
   形式の行編集とコマンド履歴のキーストロークをサポートするということ
   です。)
