
:mod:`cmd` --- 行指向のコマンドインタープリタのサポート
=======================================================

.. module:: cmd
   :synopsis: 行指向のコマンドインタープリタを構築
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>


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


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

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

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

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

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

   .. versionchanged:: 2.3
      引数 *stdin* と *stdout* を追加.


.. _cmd-objects:

Cmdオブジェクト
---------------

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


.. method:: Cmd.cmdloop([intro])

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

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

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

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

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

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

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

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


.. method:: Cmd.onecmd(str)

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


.. method:: Cmd.emptyline()

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


.. method:: Cmd.default(line)

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


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

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


.. method:: Cmd.precmd(line)

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


.. method:: Cmd.postcmd(stop, line)

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


.. method:: Cmd.preloop()

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


.. method:: Cmd.postloop()

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

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


.. attribute:: Cmd.prompt

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


.. attribute:: Cmd.identchars

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


.. attribute:: Cmd.lastcmd

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


.. attribute:: Cmd.intro

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


.. attribute:: Cmd.doc_header

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


.. attribute:: Cmd.misc_header

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


.. attribute:: Cmd.undoc_header

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


.. attribute:: Cmd.ruler

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


.. attribute:: Cmd.use_rawinput

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

