:mod:`symtable` --- コンパイラの記号表へのアクセス
==========================================================

.. module:: symtable
   :synopsis: コンパイラ内部の記号表へのインターフェイス。

.. moduleauthor:: Jeremy Hylton <jeremy@alum.mit.edu>
.. sectionauthor:: Benjamin Peterson <benjamin@python.org>


.. Symbol tables are generated by the compiler from AST just before bytecode is
.. generated.  The symbol table is responsible for calculating the scope of every
.. identifier in the code.  :mod:`symtable` provides an interface to examine these
.. tables.

記号表(symbol table)は、コンパイラが AST からバイトコードを生成する直前に作られます。
記号表はコード中の全ての識別子のスコープの算出に責任を持ちます。
:mod:`symtable` はこうした記号表を調べるインターフェイスを提供します。


.. Generating Symbol Tables
.. ------------------------

記号表の生成
------------

.. function:: symtable(code, filename, compile_type)

   .. Return the toplevel :class:`SymbolTable` for the Python source *code*.
   .. *filename* is the name of the file containing the code.  *compile_type* is
   .. like the *mode* argument to :func:`compile`.

   Python ソース *code* に対するトップレベルの :class:`SymbolTable`
   を返します。 *filename* はコードを収めてあるファイルの名前です。
   *compile_type* は :func:`compile` の *mode* 引数のようなものです。


.. Examining Symbol Tables
.. -----------------------

記号表の検査
------------

.. class:: SymbolTable

   .. A namespace table for a block.  The constructor is not public.

   ブロックに対する名前空間の記号表。
   コンストラクタはパブリックではありません。

   .. method:: get_type()

      .. Return the type of the symbol table.  Possible values are ``'class'``,
      .. ``'module'``, and ``'function'``.

      記号表の型を返します。
      有り得る値は ``'class'``, ``'module'``, ``'function'`` です。

   .. method:: get_id()

      .. Return the table's identifier.

      記号表の識別子を返します。

   .. method:: get_name()

      .. Return the table's name.  This is the name of the class if the table is
      .. for a class, the name of the function if the table is for a function, or
      .. ``'top'`` if the table is global (:meth:`get_type` returns ``'module'``).

      記号表の名前を返します。この名前は記号表がクラスに対するものであればクラス名であり、
      関数に対するものであれば関数名であり、グローバルな (:meth:`get_type` が
      ``'module'`` を返す) 記号表であれば ``'top'`` です。

   .. method:: get_lineno()

      .. Return the number of the first line in the block this table represents.

      この記号表に対応するブロックの一行目の行番号を返します。

   .. method:: is_optimized()

      .. Return ``True`` if the locals in this table can be optimized.

      この記号表に含まれるローカル変数が最適化できるならば ``True`` を返します。

   .. method:: is_nested()

      .. Return ``True`` if the block is a nested class or function.

      ブロックが入れ子のクラスまたは関数のとき ``True`` を返します。

   .. method:: has_children()

      .. Return ``True`` if the block has nested namespaces within it.  These can
      .. be obtained with :meth:`get_children`.

      ブロックが入れ子の名前空間を含んでいるならば ``True`` を返します。
      入れ子の名前空間は :meth:`get_children` で得られます。

   .. method:: has_exec()

      .. Return ``True`` if the block uses ``exec``.

      ブロックの中で ``exec`` が使われているならば ``True`` を返します。

   .. method:: has_import_star()

      .. Return ``True`` if the block uses a starred from-import.

      ブロックの中で * を使った from-import が使われているならば
      ``True`` を返します。

   .. method:: get_identifiers()

      .. Return a list of names of symbols in this table.

      この記号表にある記号の名前のリストを返します。

   .. method:: lookup(name)

      .. Lookup *name* in the table and return a :class:`Symbol` instance.

      記号表から名前 *name* を見つけ出して :class:`Symbol` インスタンスとして返します。

   .. method:: get_symbols()

      .. Return a list of :class:`Symbol` instances for names in the table.

      記号表中の名前を表す :class:`Symbol` インスタンスのリストを返します。

   .. method:: get_children()

      .. Return a list of the nested symbol tables.

      入れ子になった記号表のリストを返します。


.. class:: Function

   .. A namespace for a function or method.  This class inherits
   .. :class:`SymbolTable`.

   関数またはメソッドの名前空間。
   このクラスは :class:`SymbolTable` を継承しています。

   .. method:: get_parameters()

      .. Return a tuple containing names of parameters to this function.

      この関数の引数名からなるタプルを返します。

   .. method:: get_locals()

      .. Return a tuple containing names of locals in this function.

      この関数のローカル変数の名前からなるタプルを返します。

   .. method:: get_globals()

      .. Return a tuple containing names of globals in this function.

      この関数のグローバル変数の名前からなるタプルを返します。

   .. method:: get_frees()

      .. Return a tuple containing names of free variables in this function.

      この関数の自由変数の名前からなるタプルを返します。


.. class:: Class

   .. A namespace of a class.  This class inherits :class:`SymbolTable`.

   クラスの名前空間。
   このクラスは :class:`SymbolTable` を継承しています。

   .. method:: get_methods()

      .. Return a tuple containing the names of methods declared in the class.

      このクラスで宣言されているメソッド名からなるタプルを返します。


.. class:: Symbol

   .. An entry in a :class:`SymbolTable` corresponding to an identifier in the
   .. source.  The constructor is not public.

   :class:`SymbolTable` のエントリーでソースの識別子に対応するものです。
   コンストラクタはパブリックではありません。

   .. method:: get_name()

      .. Return the symbol's name.

      記号の名前を返します。

   .. method:: is_referenced()

      .. Return ``True`` if the symbol is used in its block.

      記号がそのブロックの中で使われていれば ``True`` を返します。

   .. method:: is_imported()

      .. Return ``True`` if the symbol is created from an import statement.

      記号が import 文で作られたものならば ``True`` を返します。

   .. method:: is_parameter()

      .. Return ``True`` if the symbol is a parameter.

      記号がパラメータならば ``True`` を返します。

   .. method:: is_global()

      .. Return ``True`` if the symbol is global.

      記号がグローバルならば ``True`` を返します。

   .. method:: is_declared_global()

      .. Return ``True`` if the symbol is declared global with a global statement.

      記号が global 文によってグローバルであると宣言されているなら ``True`` を返します。

   .. method:: is_local()

      .. Return ``True`` if the symbol is local to its block.

      記号がそのブロックに対してローカルならば ``True`` を返します。

   .. method:: is_free()

      .. Return ``True`` if the symbol is referenced in its block, but not assigned
      .. to.

      記号がそのブロックの中で参照されていて、しかし代入は行われないならば ``True`` を返します。

   .. method:: is_assigned()

      .. Return ``True`` if the symbol is assigned to in its block.

      記号がそのブロックの中で代入されているならば ``True`` を返します。

   .. method:: is_namespace()

      .. Return ``True`` if name binding introduces new namespace.

      名前の束縛が新たな名前空間を導入するならば ``True`` を返します。

      .. If the name is used as the target of a function or class statement, this
      .. will be true.

      名前が関数または class 文のターゲットとして使われるならば、真です。

      .. For example:

      例えば::

         >>> table = symtable.symtable("def some_func(): pass", "string", "exec")
         >>> table.lookup("some_func").is_namespace()
         True

      .. Note that a single name can be bound to multiple objects.  If the result
      .. is ``True``, the name may also be bound to other objects, like an int or
      .. list, that does not introduce a new namespace.

      一つの名前が複数のオブジェクトに束縛されうることに注意しましょう。
      結果が ``True`` であったとしても、その名前は他のオブジェクトにも束縛されるかもしれず、
      それがたとえば整数やリストであれば、そこでは新たな名前空間は導入されません。

   .. method:: get_namespaces()

      .. Return a list of namespaces bound to this name.

      この名前に束縛された名前空間のリストを返します。

   .. method:: get_namespace()

      .. Return the namespace bound to this name.  If more than one namespace is
      .. bound, a :exc:`ValueError` is raised.

      この名前に束縛されたただ一つの名前空間を返します。
      束縛された名前空間が一つより多くあれば :exc:`ValueError` が送出されます。
