Cmd クラスでは、行指向のコマンドインタープリタを書くための簡単なフレームワークを提供します。テストハーネスや管理ツール、そして、後により洗練されたインターフェイスでラップするプロトタイプとして、こうしたインタープリタはよく役に立ちます。
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 を追加.
Cmd インスタンスは、次のメソッドを持ちます:
プロンプトを繰り返し出力し、入力を受け取り、受け取った入力から取り去った先頭の語を解析し、その行の残りを引数としてアクションメソッドへディスパッチします。
オプションの引数は、最初のプロンプトの前に表示されるバナーあるいはイントロ用の文字列です (これはクラスメンバ 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 を持つコマンド)をリストアップします。また、文書化されていないコマンドでも、すべてリストアップします。
プロンプトに答えてタイプしたかのように引数を解釈実行します。これをオーバーライドすることがあるかもしれませんが、通常は必要ないでしょう。便利な実行フックについては、 precmd() と postcmd() メソッドを参照してください。戻り値は、インタープリタによるコマンドの解釈実行をやめるかどうかを示すフラグです。コマンド str に対応する do_*() メソッドがある場合、そのメソッドの返り値が返されます。そうでない場合は default() メソッドからの返り値が返されます。
プロンプトに空行が入力されたときに呼び出されるメソッド。このメソッドがオーバーライドされていないなら、最後に入力された空行でないコマンドが繰り返されます。
コマンドの先頭の語が認識されないときに、入力行に対して呼び出されます。このメソッドがオーバーライドされていないなら、エラーメッセージを表示して戻ります。
利用可能なコマンド固有の complete_*() が存在しないときに、入力行を補完するために呼び出されるメソッド。デフォルトでは、空行を返します。
コマンド行 line が解釈実行される直前、しかし入力プロンプトが作られ表示された後に実行されるフックメソッド。このメソッドは Cmd 内のスタブであって、サブクラスでオーバーライドされるために存在します。戻り値は onecmd() メソッドが実行するコマンドとして使われます。 precmd() の実装では、コマンドを書き換えるかもしれないし、あるいは単に変更していない line を返すかもしれません。
コマンドディスパッチが終わった直後に実行されるフックメソッド。このメソッドは Cmd 内のスタブで、サブクラスでオーバーライドされるために存在します。 line は実行されたコマンド行で、 stop は postcmd() の呼び出しの後に実行を停止するかどうかを示すフラグです。これは onecmd() メソッドの戻り値です。このメソッドの戻り値は、 stop に対応する内部フラグの新しい値として使われます。偽を返すと、実行を続けます。
Cmd のサブクラスのインスタンスは、公開されたインスタンス変数をいくつか持っています:
入力を求めるために表示されるプロンプト。
コマンドの先頭の語として受け入れられる文字の文字列。
最後の空でないコマンドプリフィックス。
ヘルプ出力に文書化されたコマンドのセクションがある場合に表示するヘッダ。
ヘルプの出力にその他のヘルプ見出しがある(すなわち、 do_*() メソッドに対応していない help_*() メソッドが存在する)場合に表示するヘッダ。
ヘルプ出力に文書化されていないコマンドのセクションがある(すなわち、対応する help_*() メソッドを持たない do_*() メソッドが存在する)場合に表示するヘッダ。
ヘルプメッセージのヘッダの下に、区切り行を表示するために使われる文字。空のときは、ルーラ行が表示されません。デフォルトでは、 '=' です。
フラグで、デフォルトでは真です。真ならば、 cmdloop() はプロンプトを表示して次のコマンド読み込むために raw_input() を使います。偽ならば、 sys.stdout.write() と sys.stdin.readline() が使われます。 (これが意味するのは、 readline を import することによって、それをサポートするシステム上では、インタープリタが自動的に Emacs 形式の行編集とコマンド履歴のキーストロークをサポートするということです。)