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

.. py:module:: raesl.compile.typechecking.compdef_relinst_builder

.. autoapi-nested-parse::

   Relation instance type-checking in a component definition.



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

Classes
~~~~~~~

.. autoapisummary::

   raesl.compile.typechecking.compdef_relinst_builder.RelInstArgsBlock
   raesl.compile.typechecking.compdef_relinst_builder.RelInst
   raesl.compile.typechecking.compdef_relinst_builder.RelInstArgGroup
   raesl.compile.typechecking.compdef_relinst_builder.CompDefRelInstBuilder




.. py:class:: RelInstArgsBlock(argkind_tok: raesl.compile.scanner.Token, arg_name_toks: Optional[List[raesl.compile.scanner.Token]] = None)


   A 'block' of arguments of a relation instance. The kind of arguments, and a list
   of argument lines.

   :param argkind_tok: Token indicating the kind of arguments specified in the block.
   :param arg_name_toks: Arguments of the block.


.. py:class:: RelInst(inst_name_tok: raesl.compile.scanner.Token, def_name_tok: raesl.compile.scanner.Token, arg_blocks: Optional[List[RelInstArgsBlock]] = None)


   Relation instance while collecting.

   :param inst_name_tok: Instance name.
   :param def_name_tok: Definition name.
   :param arg_blocks: Blocks with arguments.


.. py:class:: RelInstArgGroup(argkind: str, parameters: List[raesl.compile.ast.relations.RelationDefParameter], arguments: List[raesl.compile.scanner.Token])


   Temporary data storage of parameters and arguments of a single kind.


.. py:class:: CompDefRelInstBuilder(comp_child_builders: raesl.compile.typechecking.compdef_builder.CompDefChildBuilders)


   Collect and check relation instances in a component definition.

   :param comp_child_builders: Storage of child builders for a component definition.

   .. attribute:: relinsts

      Collected relation instances in the component.

   .. attribute:: last_relinst

      Link to last added instance to allow adding instance arguments.

   .. py:method:: new_relinst(inst_name_tok: raesl.compile.scanner.Token, def_name_tok: raesl.compile.scanner.Token)

      Parser found a new relation instance, store it for future extending by
      the parser, and eventual type checking and adding to the surrounding
      component definition.


   .. py:method:: relinst_argheader(argkind_tok: raesl.compile.scanner.Token)

      Parser found a new direction block for a relation instance, collect it.


   .. py:method:: add_relinst_arguments(name_toks: List[raesl.compile.scanner.Token])

      Parser found an argument of a direction-block in a relation instance, store
      it for future checking.


   .. py:method:: finish_comp(comp_def: raesl.compile.ast.components.ComponentDefinition, spec: raesl.compile.ast.specification.Specification)

      Check the collected relation instances, report errors, and add the
      instances to the given component.

      :param comp_def: Component definition to extend with the found relation instances.
                       Also a source of available variables, parameters, and variable groups.
      :param spec: Specification being constructed. Source for types and relation
                   definitions processed previously.


   .. py:method:: _add_relation_instance_names()

      Check whether the relation instances all have unique instance names, else
      report an error.


   .. py:method:: _split_definition_parameters_by_kind(reldef: raesl.compile.ast.relations.RelationDefinition) -> Dict[str, List[raesl.compile.ast.relations.RelationDefParameter]]
      :staticmethod:

      Split the parameters of the definition in 3 groups, 'requiring', 'returning',
      and 'relating'.

      :param reldef: Relation definition to use.

      :returns: Mapping of the parameters in the mentioned 3 groups.


   .. py:method:: _split_instance_arguments_by_kind(relinst: RelInst, reldef: raesl.compile.ast.relations.RelationDefinition, def_parameters: Dict[str, List[raesl.compile.ast.relations.RelationDefParameter]]) -> Optional[List[RelInstArgGroup]]

      Split the argument blocks, and check whether instance and definition agree
      with each other. Report errors if discrepancies are found, and merge argument
      blocks.

      Arguments
          relinst: Relation instance to check.
          def_parameters: Parameters of the definition grouped by argument kind.

      :returns:

                Triplets (kind, parameter-defs, argument tokens) wrapped in RelInstArgGroup
                    instances, or None if a fatal error was found.


   .. py:method:: _group_param_args(argkind: str, parameters: List[raesl.compile.ast.relations.RelationDefParameter], arguments: List[raesl.compile.scanner.Token], relinst: RelInst, reldef: raesl.compile.ast.relations.RelationDefinition) -> Optional[List[List[raesl.compile.scanner.Token]]]

      Group the arguments into pieces such that each parameter has exactly one
      piece. Mostly this means that the first multi-value parameter takes up all
      slack.

      :param argkind: Kind of parameters, one of ('requiring', 'returning', 'relating')
      :param parameters: Parameters of the definition for the argkind.
      :param arguments: Arguments of the instance for the argkind.
      :param relinst: Relation instance.
      :param reldef: Relation definition.

      :returns: None if a fatal error occurred, else grouped arguments.