:py:mod:`raesl.compile.ast.components` ====================================== .. py:module:: raesl.compile.ast.components .. autoapi-nested-parse:: Component definitions with their contents. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: raesl.compile.ast.components.ComponentDefinition raesl.compile.ast.components.VarParam raesl.compile.ast.components.VariableGroup raesl.compile.ast.components.InstanceArgument raesl.compile.ast.components.ComponentInstance raesl.compile.ast.components.RelationInstance raesl.compile.ast.components.Flow raesl.compile.ast.components.Goal raesl.compile.ast.components.Transformation raesl.compile.ast.components.Design raesl.compile.ast.components.SubClause raesl.compile.ast.components.BehaviorFunction raesl.compile.ast.components.BehaviorCondition raesl.compile.ast.components.BehaviorResult raesl.compile.ast.components.BehaviorCase raesl.compile.ast.components.Need Functions ~~~~~~~~~ .. autoapisummary:: raesl.compile.ast.components.get_doc_comment_comp_elements Attributes ~~~~~~~~~~ .. autoapisummary:: raesl.compile.ast.components.CONSTRAINT raesl.compile.ast.components.REQUIREMENT raesl.compile.ast.components.NeedSubjectTypes .. py:data:: CONSTRAINT :value: 'constraint' .. py:data:: REQUIREMENT :value: 'requirement' .. py:class:: ComponentDefinition(pos_tok: raesl.compile.scanner.Token, name_tok: Optional[raesl.compile.scanner.Token]) Bases: :py:obj:`raesl.compile.ast.comment_storage.DefaultDocStore` ESL component definition. :param pos_tok: Position of the definition. Either the name token or the 'world' token. :param name_tok: Token with the name of the component definition, None means 'world'. .. attribute:: variables Variables of the component definition. .. attribute:: parameters Parameters of the component definition. .. attribute:: var_groups Groups of variables with a name. .. attribute:: component_instances Component instances of the component definition. .. attribute:: needs Needs of the component definition. .. attribute:: goals Goals of the component definition. .. attribute:: transforms Transformations of the component definition. .. attribute:: designs Designs of the component definition. .. attribute:: relations Relation instances of the component definition. .. attribute:: behaviors Behavior functions of the component definition. .. py:class:: VarParam(is_variable: bool, name_tok: raesl.compile.scanner.Token, type_tok: raesl.compile.scanner.Token, is_property: bool = False) Bases: :py:obj:`raesl.compile.ast.comment_storage.DocStore` ESL component definition variable or parameter. :param is_variable: Whether the object represents a variable. :param name_tok: Token with the name of the variable being defined. :param type_tok: Token with the name of the type of the variable being defined. :param is_property: Whether the parameter is a property. .. attribute:: type Type of the variable, if it exists. Set during type checking. .. py:method:: resolve_node(name: str) -> Optional[raesl.compile.ast.nodes.VarNode] Find the varparam (sub) node that matches the dotted 'name'. :param name: Possibly dotted name that should point at an existing sub-node. The empty string denotes 'self'. :returns: The node that matches the name, or None if no such node exists. In the latter case, use 'self.get_error_position(name)' to get an indication where the match fails in the name. .. py:method:: resolve_element(name: str) -> Optional[raesl.compile.ast.comment_storage.DocAddElement] Try to find the documentation element indicated by its (dotted) name. :param name: Name of the element to find. :returns: The documentation element associated with the provided name if it can be resolved. .. py:method:: get_error_position(name: str) Return the index in the given string where an error occurs in resolving the node. :param name: Name of the element to find. :returns: Approximated index in the string where matching the element fails. Returned value has no meaning if resolving a node succeeds. .. py:method:: __repr__() Return repr(self). .. py:class:: VariableGroup(name_tok: raesl.compile.scanner.Token, variablepart_names: List[raesl.compile.scanner.Token]) One variable group in ESL (a named group of variables). It has no documentation comment, as its only purpose is to enable interfacing to child components. As a variable group doesn't need to contain uniquely named variables, their names cannot be used to build a Compound type. Therefore, it just stays a group, and it gets dealt with in component instantiation. :param name_tok: Token with the name of the group being defined. :param variablepart_names: Tokens with possibly dotted name of variable parts in the group. .. attribute:: node Node representing the group, if available. .. py:class:: InstanceArgument(name_tok: raesl.compile.scanner.Token, argnode: Optional[raesl.compile.ast.nodes.Node] = None) Actual argument of a component or relation. :param name_tok: Name of the actual argument. :param argnode: Node of the argument, filled during type checking. .. py:class:: ComponentInstance(inst_name_tok: raesl.compile.scanner.Token, def_name_tok: raesl.compile.scanner.Token) Bases: :py:obj:`raesl.compile.ast.comment_storage.DefaultDocStore` ESL component instance in a component definition. :param inst_name_tok: Token with the name of the component instance. :param def_name_tok: Token withe the name of the component definition to apply. .. attribute:: arguments Arguments of the instance. .. attribute:: compdef Component definition matching the name in 'def_name_tok', if it exists. Set during type checking. .. py:class:: RelationInstance(inst_name_tok: raesl.compile.scanner.Token, def_name_tok: raesl.compile.scanner.Token, arguments: List[List[InstanceArgument]], reldef: Optional[raesl.compile.ast.relations.RelationDefinition]) Bases: :py:obj:`raesl.compile.ast.comment_storage.DefaultDocStore` ESL relation instance in a component definition. :param inst_name_tok: Token with the name of the relation instance. :param def_name_tok: Token withe the name of the relation definition to apply. :param arguments: Arguments of the instance. One element for each parameter, where one element may have several arguments due to the 'one or more' feature. :param reldef: Relation definition of this instance. .. py:class:: Flow(name_tok) Flow in a goal or Transformation. :param name_tok: Dotted name of the flow. .. attribute:: flow_node If not None, node represented by the flow. .. py:class:: Goal(label_tok: raesl.compile.scanner.Token, active: raesl.compile.scanner.Token, doesaux: raesl.compile.scanner.Token, verb: raesl.compile.scanner.Token, flows: List[Flow], prepos: raesl.compile.scanner.Token, passive: raesl.compile.scanner.Token) Bases: :py:obj:`raesl.compile.ast.comment_storage.DefaultDocStore` Goal in an ESL component definition. :param label_tok: Label name of the goal. :param active: Token with the name of the active component. :param doesaux: 'does' or auxiliary word token. :param verb: Verb of the goal. :param flows: Flows of the goal. :param prepos: Token with the preposition word. :param passive: Token with the name of the passive component. .. attribute:: goal_kind Kind of goal, filled after construction. Either 'requirement' or 'constraint' string. .. attribute:: sub_clauses Sub-clauses of the goal. .. attribute:: active_comp If not None, resolved active component instance of the goal. .. attribute:: passive_comp If not None, resolved passive component instance of the goal. .. py:class:: Transformation(label_tok: raesl.compile.scanner.Token, doesaux_tok: raesl.compile.scanner.Token, verb_tok: raesl.compile.scanner.Token, in_flows: List[Flow], prepos_tok: raesl.compile.scanner.Token, out_flows: List[Flow]) Bases: :py:obj:`raesl.compile.ast.comment_storage.DefaultDocStore` Transformation in a component. :param label_tok: Label name of the transformation. :param doesaux_tok: 'does' or aux word token. :param verb_tok: Verb of the transformation. :param in_flows: Inputs required for the transformation. :param prepos_tok: Preposition of the transformation. :param out_flows: Outputs resulting from the transformation. .. attribute:: transform_kind Kind of transformation, filled after construction. Either 'requirement' or 'constraint' string. .. attribute:: sub_clauses Sub-clauses of the transformation. .. py:class:: Design(label_tok: raesl.compile.scanner.Token, expr: raesl.compile.ast.exprs.Expression) Bases: :py:obj:`raesl.compile.ast.comment_storage.DefaultDocStore` Design rule in a component. :param label_tok: Name of the design rule. :param expr: Condition expressed in the design. .. attribute:: design_kind Kind of the design, filled in after construction. Contains either 'requirement' or 'constraint'. .. attribute:: sub_clauses Sub-clauses of the design. .. py:class:: SubClause(label_tok: raesl.compile.scanner.Token, expr: raesl.compile.ast.exprs.Expression) Subclause in a goal, transformation, or behavior. :param label_tok: Name of the subclause. :param expr: Expression describing the subclause. .. py:class:: BehaviorFunction(behavior_kind: str, name_tok: raesl.compile.scanner.Token) Bases: :py:obj:`raesl.compile.ast.comment_storage.DefaultDocStore` One function specifying some behavior. :param behavior_kind: Kind of behavior. Either 'requirement' or 'constraint'. :param name_tok: Name of the behavior. .. attribute:: cases Behavior cases. .. attribute:: default_results Results that hold when none of the cases applies. None means there is no default result. .. py:class:: BehaviorCondition(name_tok: raesl.compile.scanner.Token, comparison: Union[raesl.compile.ast.exprs.Disjunction, raesl.compile.ast.exprs.RelationComparison]) A condition of a case. .. py:class:: BehaviorResult(name_tok: raesl.compile.scanner.Token, result: raesl.compile.ast.exprs.Comparison) A result of a case. .. py:class:: BehaviorCase(name_tok: raesl.compile.scanner.Token, conditions: List[BehaviorCondition], results: List[BehaviorResult]) A set of desired behavioral results given a set of conditions. :param name_tok: Name of the behavior case. :param conditions: Conditions that should hold for the case to apply. :param results: Results that should hold when the case applies. .. py:data:: NeedSubjectTypes .. py:class:: Need(label_tok: raesl.compile.scanner.Token, subject_tok: raesl.compile.scanner.Token, description: str) Bases: :py:obj:`raesl.compile.ast.comment_storage.DefaultDocStore` Informal need in ESL. :param label_tok: Token with the name of the label. :param subject_tok: Token with the name of the subject of the need. :param description: Description of the need. .. attribute:: subject If not None, subject of the need. .. py:function:: get_doc_comment_comp_elements(comp: ComponentDefinition) -> Generator[raesl.compile.ast.comment_storage.DocStore, None, None] Retrieve the component elements interested in getting documentation comments from the input. This includes the component itself, so you can add documentation to it in its 'comments' section. :param comp: Component definition to search. :returns: Generator yielding interested elements.