"code" --- Interpreter base classes
***********************************

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

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

"code" モジュールはread-eval-print (読み込み-評価-表示)ループをPython
で実装するための機能を提供します。対話的なインタプリタプロンプトを提供
するアプリケーションを作るために使える二つのクラスと便利な関数が含まれ
ています。

class code.InteractiveInterpreter(locals=None)

   This class deals with parsing and interpreter state (the user's
   namespace); it does not deal with input buffering or prompting or
   input file naming (the filename is always passed in explicitly).
   The optional *locals* argument specifies the dictionary in which
   code will be executed; it defaults to a newly created dictionary
   with key "'__name__'" set to "'__console__'" and key "'__doc__'"
   set to "None".

class code.InteractiveConsole(locals=None, filename='<console>')

   Closely emulate the behavior of the interactive Python interpreter.
   This class builds on "InteractiveInterpreter" and adds prompting
   using the familiar "sys.ps1" and "sys.ps2", and input buffering.

code.interact(banner=None, readfunc=None, local=None, exitmsg=None)

   Convenience function to run a read-eval-print loop.  This creates a
   new instance of "InteractiveConsole" and sets *readfunc* to be used
   as the "InteractiveConsole.raw_input()" method, if provided.  If
   *local* is provided, it is passed to the "InteractiveConsole"
   constructor for use as the default namespace for the interpreter
   loop.  The "interact()" method of the instance is then run with
   *banner* and *exitmsg* passed as the banner and exit message to
   use, if provided.  The console object is discarded after use.

   バージョン 3.6 で変更: *exitmsg* 引数が追加されました.

code.compile_command(source, filename='<input>', symbol='single')

   この関数はPythonのインタプリタメインループ(別名、read-eval-printル
   ープ)をエミュレートしようとするプログラムにとって役に立ちます。扱い
   にくい部分は、ユーザが(完全なコマンドや構文エラーではなく)さらにテ
   キストを入力すれば完全になりうる不完全なコマンドを入力したときを決
   定することです。この関数は *ほとんど* の場合に実際のインタプリタメ
   インループと同じ決定を行います。

   *source* はソース文字列です。*filename* はオプションのソースが読み
   出されたファイル名で、デフォルトで "'<input>'" です。*symbol* はオ
   プションの文法の開始記号で、"'single'" (デフォルト)または "'eval'"
   か "'exec'" にすべきです。

   コマンドが完全で有効ならば、コードオブジェクトを返します
   ("compile(source, filename, symbol)" と同じ)。コマンドが完全でない
   ならば、 "None" を返します。コマンドが完全で構文エラーを含む場合は
   、 "SyntaxError" を発生させます。または、コマンドが無効なリテラルを
   含む場合は、 "OverflowError" もしくは "ValueError" を発生させます。


対話的なインタプリタオブジェクト
================================

InteractiveInterpreter.runsource(source, filename='<input>', symbol='single')

   インタプリタ内のあるソースをコンパイルし実行します。引数は
   "compile_command()" のものと同じです。 *filename* のデフォルトは
   "'<input>'" で、 *symbol* は "'single'" です。あるいくつかのことが
   起きる可能性があります:

   * 入力が不正。 "compile_command()" が例外("SyntaxError" か
     "OverflowError")を起こした場合。 "showsyntaxerror()" メソッドの呼
     び出によって、構文トレースバックが表示されるでしょう。
     "runsource()" は "False" を返します。

   * 入力が完全でなく、さらに入力が必要。 "compile_command()" が
     "None" を返した場合。 "runsource()" は "True" を返します。

   * 入力が完全。 "compile_command()" がコードオブジェクトを返した場合
     。 ("SystemExit" を除く実行時例外も処理する) "runcode()" を呼び出
     すことによって、コードは実行されます。 "runsource()" は "False"
     を返します。

   戻り値は、次の行のプロンプトに "sys.ps1" か "sys.ps2" のどちらを使
   うのか判断するために使えます。

InteractiveInterpreter.runcode(code)

   コードオブジェクトを実行します。例外が生じたときは、トレースバック
   を表示するために "showtraceback()" が呼び出されます。伝搬することが
   許されている "SystemExit" を除くすべての例外が捉えられます。

   "KeyboardInterrupt" についての注意。このコードの他の場所でこの例外
   が生じる可能性がありますし、常に捕らえることができるとは限りません
   。呼び出し側はそれを処理するために準備しておくべきです。

InteractiveInterpreter.showsyntaxerror(filename=None)

   起きたばかりの構文エラーを表示します。複数の構文エラーに対して一つ
   あるのではないため、これはスタックトレースを表示しません。
   *filename* が与えられた場合は、Pythonのパーサが与えるデフォルトのフ
   ァイル名の代わりに例外の中へ入れられます。なぜなら、文字列から読み
   込んでいるときはパーサは常に "'<string>'" を使うからです。出力は
   "write()" メソッドによって書き込まれます。

InteractiveInterpreter.showtraceback()

   起きたばかりの例外を表示します。スタックの最初の項目を取り除きます
   。なぜなら、それはインタプリタオブジェクトの実装の内部にあるからで
   す。出力は "write()" メソッドによって書き込まれます。

   バージョン 3.5 で変更: 最初のトレースバックではなく、完全なトレース
   バックの連鎖が表示されます。

InteractiveInterpreter.write(data)

   文字列を標準エラーストリーム("sys.stderr")へ書き込みます。必要に応
   じて適切な出力処理を提供するために、派生クラスはこれをオーバーライ
   ドすべきです。


対話的なコンソールオブジェクト
==============================

"InteractiveConsole" クラスは "InteractiveInterpreter" のサブクラスで
す。以下の追加メソッドだけでなく、インタプリタオブジェクトのすべてのメ
ソッドも提供します。

InteractiveConsole.interact(banner=None, exitmsg=None)

   対話的な Python コンソールをそっくりにエミュレートします。オプショ
   ンの *banner* 引数は最初のやりとりの前に表示するバナーを指定します
   。デフォルトでは、標準 Python インタプリタが表示するものと同じよう
   なバナーを表示します。それに続けて、実際のインタプリタと混乱しない
   ように (とても似ているから!) 括弧の中にコンソールオブジェクトのクラ
   ス名を表示します。

   オプション引数の *exitmsg* は、終了時に出力される終了メッセージを指
   定します。空文字列を渡すと、出力メッセージを抑止します。もし、
   *exitmsg* が与えられないか、"None" の場合は、デフォルトのメッセージ
   が出力されます。

   バージョン 3.4 で変更: バナーの表示を抑制するには、空の文字列を渡し
   てください。

   バージョン 3.6 で変更: 終了時に、終了メッセージを表示します。

InteractiveConsole.push(line)

   Push a line of source text to the interpreter. The line should not
   have a trailing newline; it may have internal newlines.  The line
   is appended to a buffer and the interpreter's "runsource()" method
   is called with the concatenated contents of the buffer as source.
   If this indicates that the command was executed or invalid, the
   buffer is reset; otherwise, the command is incomplete, and the
   buffer is left as it was after the line was appended.  The return
   value is "True" if more input is required, "False" if the line was
   dealt with in some way (this is the same as "runsource()").

InteractiveConsole.resetbuffer()

   入力バッファから処理されていないソーステキストを取り除きます。

InteractiveConsole.raw_input(prompt='')

   プロンプトを書き込み、一行を読み込みます。返る行は末尾に改行を含み
   ません。ユーザがEOFキーシーケンスを入力したときは、 "EOFError" を発
   生させます。基本実装では、 "sys.stdin" から読み込みます。サブクラス
   はこれを異なる実装と置き換えるかもしれません。
