5.19.1 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_help()は、すべての利用可能なヘルプ見出し(すなわち、対応するhelp_*()メソッドを持つすべてのコマンド)をリストアップします。また、文書化されていないコマンドでも、すべてリストアップします。

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

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

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

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

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

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

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

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

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

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

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

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

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

doc_header: ヘルプの出力に文書化されたコマンドの部分がある場合に表示するヘッダ。

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

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

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

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

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。