:py:mod:`raesl.compile.typechecking.ast_builder`
================================================

.. py:module:: raesl.compile.typechecking.ast_builder

.. autoapi-nested-parse::

   Classes to collect and store information from the parsing process, perform checking
   on the information for being correct, and construct an AST as result along with a log of
   found diagnostics.

   The AstBuilder operates at top section level (types, verbs, relation definitions, and
   component definitions). It leaves all the details of each section to dedicated child
   builders (thus creating a highly modular checker), and acts as call dispatcher and
   global controller in the type-checking and ast building process once parsing has
   finished.

   Notable parts in the class are
   - Child builders for each top section part.
   - Diagnostics store shared with all the child builders.
   - Storage of doc-comments in the input for attaching them to the correct parts of the
     produced specification after parsing.
   - Call dispatcher for the child builders that a new top or sub-section has been found,
     allowing them to clean up processing if needed.
   - Entry points for the parser to push found information to the child builders.
   - The 'finish_parse' entry point to perform all type checking, and produce the AST and
     found diagnostics.



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

Classes
~~~~~~~

.. autoapisummary::

   raesl.compile.typechecking.ast_builder.AstBuilder




.. py:class:: AstBuilder(diag_store: raesl.compile.diagnostics.DiagnosticStore)


   Builder to collect information from the parse process, perform type
   checking, and produce an AST and reported diagnostics.

   :param diag_store: Storage for diagnostics while building the AST.

   .. attribute:: doc_distributor

      Object that distributes doc comments to interested elements of
      the specification.

   .. attribute:: section_notify_list

      Builders to notify of a new section.

   .. attribute:: type_builder

      Builder for constructing types.

   .. attribute:: verb_builder

      Builder for constructing verb/prepositions.

   .. attribute:: reldef_builder

      Builder for constructing relations.

   .. attribute:: compdef_builder

      Builder for constructing components.

   .. py:method:: add_typedef(type_name: raesl.compile.scanner.Token, parent_name: Optional[raesl.compile.scanner.Token], enum_spec: Optional[List[raesl.compile.ast.exprs.Value]], unit_spec: Optional[List[raesl.compile.scanner.Token]], ival_spec: Optional[List[Tuple[Optional[raesl.compile.ast.exprs.Value], Optional[raesl.compile.ast.exprs.Value]]]], cons_spec: Optional[raesl.compile.ast.exprs.Value])

      Forward call to type builder.


   .. py:method:: new_bundle_type(bundle_name: raesl.compile.scanner.Token)

      Forward call to type builder.


   .. py:method:: add_bundle_field(field_name: raesl.compile.scanner.Token, type_name: Optional[raesl.compile.scanner.Token])

      Forward call to type builder.


   .. py:method:: add_verbdef(verb_tok: raesl.compile.scanner.Token, prepos_tok: raesl.compile.scanner.Token)

      Forward call to verb definition builder.


   .. py:method:: add_reldef(name: raesl.compile.scanner.Token)

      Forward call to relation definition builder.


   .. py:method:: reldef_param_header(header_tok: raesl.compile.scanner.Token, direction: str)

      Forward call to relation definition builder.


   .. py:method:: reldef_add_param(name: raesl.compile.scanner.Token, type_name: raesl.compile.scanner.Token, multi: bool)

      Forward call to relation definition builder.


   .. py:method:: register_new_section(other_builder)

      Entry point for a child builder to declare interest in receiving
      notifications about new sections in the file.


   .. py:method:: notify_new_section(tok: Optional[raesl.compile.scanner.Token], new_top_section: bool)

      Parser has started a new section, finish all 'in-progress' definitions.

      :param tok: Token indicating the position of the new section. None is used for EOF.
      :param new_top_section: If set, a new type, verbs, or component definition has
                              been found, else a new section within a component has been detected.


   .. py:method:: finish_parse(doc_comments: List[raesl.compile.scanner.Token]) -> Optional[raesl.compile.ast.specification.Specification]

      Finish processing the collected information, that is, perform type checking.

      :param doc_comments: Raw documentation comments rescued from the scanner.