fparser.two.symbol_table
========================

.. py:module:: fparser.two.symbol_table

.. autoapi-nested-parse::

   The fparser2 symbol-table module. Defines various classes as well as
   the single, global SYMBOL_TABLES instance. The latter is a container
   for all of the top-level scoping units encountered during parsing.



Attributes
----------

.. autoapisummary::

   fparser.two.symbol_table.SYMBOL_TABLES


Exceptions
----------

.. autoapisummary::

   fparser.two.symbol_table.SymbolTableError


Classes
-------

.. autoapisummary::

   fparser.two.symbol_table.SymbolTables
   fparser.two.symbol_table.SymbolTable


Module Contents
---------------

.. py:exception:: SymbolTableError

   Bases: :py:obj:`Exception`


   Base class exception for symbol-table related errors.


.. py:class:: SymbolTables

   Class encapsulating functionality for the global symbol-tables object.
   This is a container for all symbol tables constructed while parsing
   code. All names are converted to lower case (since Fortran is not
   case sensitive).



   .. py:attribute:: _symbol_tables


   .. py:attribute:: _current_scope
      :value: None



   .. py:attribute:: _enable_checks
      :value: False



   .. py:method:: __str__()


   .. py:method:: enable_checks(value)

      Sets whether or not to enable consistency checks in every symbol
      table that is created during a parse.

      :param bool value: whether or not checks are enabled.




   .. py:method:: clear()

      Deletes any stored SymbolTables.




   .. py:method:: add(name, node=None)

      Add a new symbol table with the supplied name. The name will be
      converted to lower case if necessary.

      :param str name: the name for the new table.
      :param node: the node in the parse tree associated with this table.
      :type node: Optional[:py:class:`fparser.two.utils.Base`]

      :returns: the new symbol table.
      :rtype: :py:class:`fparser.two.symbol_table.SymbolTable`

      :raises SymbolTableError: if there is already an entry with the
                                supplied name.



   .. py:method:: lookup(name)

      Find the named symbol table and return it.

      :param str name: the name of the required symbol table (not case                          sensitive).

      :returns: the named symbol table.
      :rtype: :py:class:`fparser.two.symbol_table.SymbolTable`




   .. py:property:: current_scope

      :returns: the symbol table for the current scoping unit or None.
      :rtype: :py:class:`fparser.two.symbol_table.SymbolTable` or NoneType



   .. py:method:: enter_scope(name, node=None)

      Called when the parser enters a new scoping region (i.e. when it
      encounters one of the classes listed in `_scoping_unit_classes`).
      Sets the 'current scope' to be the symbol table with the supplied name.
      If we are not currently within a tree of scoping regions then a
      new entry is created in the internal dict of symbol tables. If there
      is an existing tree then a new table is created and added to the
      bottom.

      :param str name: name of the scoping region.
      :param node: the node of the parse tree associated with this region.
      :type node: Optional[:py:class:`fparser.two.utils.Base`]



   .. py:method:: exit_scope()

      Marks the end of the processing of the current scoping unit. Since
      we are exiting the current scoping region, the new 'current scoping
      region' will be its parent.

      :raises SymbolTableError: if there is no current scope from which to                                   exit.



   .. py:method:: remove(name)

      Removes the named symbol table and any descendants it may have.
      When searching for the named table, the current scope takes priority
      followed by the list of top-level symbol tables.

      :param str name: the name of the symbol table to remove (not case                          sensitive).
      :raises SymbolTableError: if the named symbol table is not in the             current scope or in the list of top-level symbol tables.




.. py:class:: SymbolTable(name, parent=None, checking_enabled=False, node=None)

   Class implementing a single symbol table.

   Since this functionality is not yet fully mature, checks that new symbols
   don't clash with existing symbols are disabled by default.
   Once #201 is complete it is planned to switch this so that the checks
   are instead enabled by default.

   :param str name: the name of this scope. Will be the name of the
       associated module or routine.
   :param parent: the symbol table within which this one is nested (if any).
   :type parent: :py:class:`fparser.two.symbol_table.SymbolTable.Symbol`
   :param bool checking_enabled: whether or not validity checks are
       performed for symbols added to the table.
   :param node: the node in the parse tree associated with this table.
   :type node: Optional[:py:class:`fparser.two.utils.Base`]

   :raises TypeError: if the supplied node is of the wrong type.


   .. py:class:: Symbol

      Bases: :py:obj:`tuple`


      .. py:attribute:: name


      .. py:attribute:: primitive_type



   .. py:attribute:: _name


   .. py:attribute:: _data_symbols


   .. py:attribute:: _modules


   .. py:attribute:: _parent
      :value: None



   .. py:property:: parent

      :returns: the parent symbol table (scoping region) that contains                   this one (if any).
      :rtype: :py:class:`fparser.two.symbol_table.SymbolTable` or NoneType



   .. py:attribute:: _node
      :value: None



   .. py:attribute:: _checking_enabled
      :value: False



   .. py:attribute:: _children
      :value: []



   .. py:method:: __str__()


   .. py:method:: add_data_symbol(name, primitive_type)

      Creates a new Symbol with the specified properties and adds it to
      the symbol table. The supplied name is converted to lower case.

      TODO #201 add support for other symbol properties (kind, shape
      and visibility).

      :param str name: the name of the symbol.
      :param str primitive_type: the primitive type of the symbol.

      :raises TypeError: if any of the supplied parameters are of the                            wrong type.
      :raises SymbolTableError: if the symbol table already contains an
                                entry with the supplied name.



   .. py:method:: add_use_symbols(name, only_list=None, rename_list=None)

      Creates an entry in the table for the USE of a module with the supplied
      name. If no `only_list` is supplied then this USE represents a wildcard
      import of all public symbols in the named module. If the USE statement
      has an ONLY clause but without any named symbols then `only_list`
      should be an empty list.

      A USE can also have one or more rename entries *without* an only list.

      :param str name: the name of the module being imported via a USE. Not             case sensitive.
      :param only_list: if there is an 'only:' clause on the USE statement             then this contains a list of tuples, each holding the local name             of the symbol and its name in the module from which it is             imported. These names are case insensitive.
      :type only_list: Optional[List[Tuple[str, str | NoneType]]]
      :param rename_list: a list of symbols that are renamed from the scope             being imported. Each entry is a tuple containing the name in the             local scope and the corresponding name in the module from which it            is imported. These names are case insensitive.
      :type rename_list: Optional[List[Tuple[str, str]]]




   .. py:method:: lookup(name)

      Lookup the symbol with the supplied name.

      :param str name: the name of the symbol to lookup (not case sensitive).

      :returns: the named symbol.
      :rtype: :py:class:`fparser.two.symbol_table.SymbolTable.Symbol`

      :raises KeyError: if the named symbol cannot be found in this or any                           parent scope.



   .. py:property:: name

      :returns: the name of this symbol table (scoping region).
      :rtype: str



   .. py:property:: node

      :returns: the scoping node (in the parse tree) asssociated with this SymbolTable.
      :rtype: :py:class:`fparser.two.utils.Base`



   .. py:method:: add_child(child)

      Adds a child symbol table (scoping region nested within this one).

      :param child: the nested symbol table.
      :type child: :py:class:`fparser.two.symbol_table.SymbolTable`

      :raises TypeError: if the supplied child is not a SymbolTable.




   .. py:method:: del_child(name)

      Removes the named symbol table.

      :param str name: the name of the child symbol table to delete (not                          case sensitive).

      :raises KeyError: if the named table is not a child of this one.




   .. py:property:: children

      :returns: the child (nested) symbol tables, if any.
      :rtype: list of :py:class:`fparser.two.symbol_table.SymbolTable`



   .. py:property:: root

      :returns: the top-level symbol table that contains the current                   scoping region (symbol table).
      :rtype: :py:class:`fparser.two.symbol_table.SymbolTable`




   .. py:property:: wildcard_imports

      :returns: names of all modules with wildcard imports into this scope or an
                empty list if there are none.
      :rtype: List[Optional[str]]



   .. py:property:: all_symbols_resolved

      :returns: whether all symbols in this scope have been resolved. i.e. if
          there are any wildcard imports or this table is within a submodule
          then there could be symbols we don't have definitions for.
      :rtype: bool



.. py:data:: SYMBOL_TABLES