viv-compiler 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

viv_compiler/core/visitor.py

@@ -9,8 +9,8 @@ import copy
 import arpeggio
 import viv_compiler.config
 import viv_compiler.types
-from viv_compiler.types import ExpressionDiscriminator, ReferencePathComponentDiscriminator
-from typing import Any, Optional, TypeGuard
+from viv_compiler.types import ExpressionDiscriminator, ReferencePathComponentDiscriminator, LocalVariable
+from typing import Any, Optional
 
 
 class Visitor(arpeggio.PTNodeVisitor):
@@ -21,24 +21,47 @@ class Visitor(arpeggio.PTNodeVisitor):
         """Visit the <file> node, i.e., the root of the parse tree."""
         ast = {"_includes": [], "tropes": [], "actions": []}
         for child in children:
-            if child["type"] == 'include':
+            if child["_type"] == 'include':
                 ast['_includes'].append(child['value'])
-            elif child["type"] == 'action':
+            elif child["_type"] == 'action':
                 ast['actions'].append(child['value'])
-            elif child["type"] == 'trope':
+            elif child["_type"] == 'trope':
                 ast['tropes'].append(child['value'])
         return ast
 
     @staticmethod
     def visit_include(_, children: Any) -> dict[str, Any]:
         """Visit an <include> node."""
-        return {"type": "include", "value": children[0]}
+        return {"_type": "include", "value": children[0]}
 
     @staticmethod
     def visit_filename(_, children: Any) -> str:
         """Visit a <filename> node."""
         return ''.join(children)
 
+    @staticmethod
+    def visit_trope(_, children: Any) -> dict[str, Any]:
+        """Visit a <trope> node."""
+        if len(children) == 3:
+            name, params, conditions = children
+        else:
+            name, conditions = children
+            params = []
+        trope_definition = {"name": name, "params": params, "conditions": conditions}
+        return {"_type": "trope", "value": trope_definition}
+
+    @staticmethod
+    def visit_trope_params(_, children: Any) -> list[str]:
+        """Visit a <trope_params> node."""
+        return children
+
+    @staticmethod
+    def visit_trope_param(_, children: Any) -> viv_compiler.types.TropeParam:
+        """Visit a <trope_param> node."""
+        role_type, name = children
+        component = {"name": name, "isEntityParam": role_type["_is_entity"]}
+        return component
+
     @staticmethod
     def visit_action(_, children: Any) -> dict[str, Any]:
         """Visit an <action> node."""
@@ -46,7 +69,7 @@ class Visitor(arpeggio.PTNodeVisitor):
         header, body = children
         action_definition.update(header)
         action_definition.update(body)
-        return {"type": "action", "value": action_definition}
+        return {"_type": "action", "value": action_definition}
 
     @staticmethod
     def visit_action_header(_, children: Any) -> dict[str, Any]:
@@ -134,6 +157,12 @@ class Visitor(arpeggio.PTNodeVisitor):
         component = {"type": ExpressionDiscriminator.LIST, "value": children}
         return component
 
+    @staticmethod
+    def visit_tag(_, children: Any) -> viv_compiler.types.StringField:
+        """Visit a <tag> node."""
+        component = {"type": ExpressionDiscriminator.STRING, "value": children[0]}
+        return component
+
     @staticmethod
     def visit_roles(_, children: Any) -> dict[str, Any]:
         """Visit a <roles> node."""
@@ -170,12 +199,19 @@ class Visitor(arpeggio.PTNodeVisitor):
             "precast": False,
             "build": False,
         }
+        marked_entity_role = False
         for child in children:
-            if 'min' in child:
+            if "_is_entity" in child:
+                marked_entity_role = child["_is_entity"]
+            elif "min" in child:
                 component['min'] = child['min']['value']
                 component['max'] = child['max']['value']
             else:
                 component.update(child)
+        if marked_entity_role and component['symbol']:
+            raise ValueError(f"Role '@{component['name']}' has entity prefix but is marked symbol")
+        if not marked_entity_role and not component['symbol']:
+            raise ValueError(f"Role '&{component['name']}' has symbol prefix but is not marked symbol")
         if not (component['item'] or component['action'] or component['location'] or component['symbol']):
             component['character'] = True
         if component['mean'] is not None:
@@ -205,6 +241,11 @@ class Visitor(arpeggio.PTNodeVisitor):
             return {"min": children[0], "max": children[0]}
         return {"min": children[0], "max": children[1]}
 
+    @staticmethod
+    def visit_binding_type(_, children: Any) -> dict[str, bool]:
+        """Visit a <binding_type> node."""
+        return {"_is_entity": children[0] == "@"}
+
     @staticmethod
     def visit_role_name(_, children: Any) -> dict[str, str]:
         """Visit a <role_name> node."""
@@ -347,31 +388,6 @@ class Visitor(arpeggio.PTNodeVisitor):
         # Move the 'bindings' field from the options component to the top level of the reaction value
         reaction_object['bindings'] = reaction_object['options']['bindings']
         del reaction_object['options']['bindings']
-        # Validate the shape of the reaction value
-        def _is_reaction_value(obj) -> "TypeGuard[viv_compiler.types.ReactionValue]":
-            if not isinstance(obj, dict):
-                return False
-            if not {"actionName", "bindings", "options"} <= set(obj):
-                return False
-            if not isinstance(obj.get("actionName"), str):
-                return False
-            bindings = obj.get("bindings")
-            if not isinstance(bindings, list):
-                return False
-            for b in bindings:
-                if not (isinstance(b, dict) and b.get("type") == "binding" and isinstance(b.get("value"), dict)):
-                    return False
-                v = b["value"]
-                if not (isinstance(v.get("role"), str) and "entity" in v):
-                    return False
-            options = obj.get("options")
-            if not isinstance(options, dict):
-                return False
-            if "bindings" in options:
-                return False
-            return True
-        if not _is_reaction_value(reaction_object):
-            raise ValueError(f"Malformed reaction generated by Visitor: {reaction_object!r}")
         # Package up the component and return it
         reaction_value: viv_compiler.types.ReactionValue = reaction_object  # type: ignore[assignment]
         component: viv_compiler.types.Reaction = {"type": ExpressionDiscriminator.REACTION, "value": reaction_value}
@@ -388,14 +404,14 @@ class Visitor(arpeggio.PTNodeVisitor):
         return {"bindings": children}
 
     @staticmethod
-    def visit_binding(_, children: Any) -> viv_compiler.types.ReactionBinding | viv_compiler.types.Loop:
+    def visit_binding(_, children: Any) -> viv_compiler.types.ReactionRoleBindings:
         """Visit a <binding> node."""
-        # Support both (name ":" reference) and the 'loop' alternative per the grammar
-        if len(children) == 1:
-            if isinstance(children[0], dict) and children[0].get("type") == ExpressionDiscriminator.LOOP:
-                return children[0]
-        role_name, entity_to_bind = children
-        component = {"type": ExpressionDiscriminator.BINDING, "value": {"role": role_name, "entity": entity_to_bind}}
+        role_type, role_name, candidate_expression = children
+        component = {
+            "role": role_name,
+            "isEntityRole": role_type["_is_entity"],
+            "candidates": candidate_expression,
+        }
         return component
 
     @staticmethod
@@ -524,21 +540,20 @@ class Visitor(arpeggio.PTNodeVisitor):
     @staticmethod
     def visit_time(_, children: Any) -> dict[str, Any]:
         """Visit a <time> node."""
-        period = children[-1]  # AM or PM
         raw_hour = int(children[0])
-        hour = (raw_hour % 12) + (12 if period.upper() == 'PM' else 0)
-        if len(children) == 2:  # Only the hour was provided
-            component = {
-                "type": "time",
-                "hour": hour,
-                "minute": 0
-            }
-        else:
-            component = {
-                "type": "time",
-                "hour": hour,
-                "minute": int(children[1])
-            }
+        minute = int(children[1]) if len(children) > 1 and children[1].isdigit() else 0
+        if children[-1].upper() in ("AM", "PM"):  # 12-hour form
+            period = children[-1].upper()
+            if not 1 <= raw_hour <= 12:
+                raise ValueError(f"Invalid hour in 12-hour time: {raw_hour}")
+            hour = (raw_hour % 12) + (12 if period == "PM" else 0)
+        else:  # 24-hour form
+            if not 0 <= raw_hour <= 23:
+                raise ValueError(f"Invalid hour in 24-hour time: {raw_hour}")
+            hour = raw_hour
+        if not 0 <= minute <= 59:
+            raise ValueError(f"Invalid minute in time: {minute}")
+        component = {"type": "time", "hour": hour, "minute": minute}
         return component
 
     @staticmethod
@@ -559,12 +574,15 @@ class Visitor(arpeggio.PTNodeVisitor):
         if children[0] == "join":
             join_saliences = True
             children = children[1:]
-        default_value_expression = children[0]
-        body = children[1] if len(children) > 1 else []
+        local_variable, body = None, []
+        if len(children) == 1:  # Default only
+            default_value_expression = children[0]
+        else:
+            local_variable, default_value_expression, body = children
         component = {
             "saliences": {
                 "default": default_value_expression,
-                "variable": viv_compiler.config.SALIENCES_VARIABLE_NAME,
+                "variable": local_variable,
                 "body": body,
             }
         }
@@ -589,12 +607,15 @@ class Visitor(arpeggio.PTNodeVisitor):
         if children[0] == "join":
             join_associations = True
             children = children[1:]
-        default_value_expression = children[0]
-        body = children[1] if len(children) > 1 else []
+        local_variable, body = None, []
+        if len(children) == 1:  # Default only
+            default_value_expression = children[0]
+        else:
+            local_variable, default_value_expression, body = children
         component = {
             "associations": {
                 "default": default_value_expression,
-                "variable": viv_compiler.config.ASSOCIATIONS_VARIABLE_NAME,
+                "variable": local_variable,
                 "body": body,
             }
         }
@@ -757,10 +778,20 @@ class Visitor(arpeggio.PTNodeVisitor):
     @staticmethod
     def visit_loop(_, children: Any) -> viv_compiler.types.Loop:
         """Visit a <loop> node."""
-        iterable_reference, variable_name, loop_body = children
+        iterable_reference, loop_variable, loop_body = children
         component = {
             "type": ExpressionDiscriminator.LOOP,
-            "value": {"iterable": iterable_reference, "variable": variable_name['name'], "body": loop_body}
+            "value": {"iterable": iterable_reference, "variable": loop_variable, "body": loop_body}
+        }
+        return component
+
+    @staticmethod
+    def visit_local_variable(_, children: Any) -> LocalVariable:
+        """Visit a <local_variable> node."""
+        _, binding_type, name = children
+        component = {
+            "name": name,
+            "isEntityVariable": binding_type["_is_entity"]
         }
         return component
 
@@ -937,69 +968,76 @@ class Visitor(arpeggio.PTNodeVisitor):
         return children
 
     @staticmethod
-    def visit_reference(
-        _, children: Any
-    ) -> viv_compiler.types.EntityReference | viv_compiler.types.LocalVariableReference:
-        return children[0]
-
-    @staticmethod
-    def visit_role_anchored_reference(_, children: Any) -> viv_compiler.types.EntityReference:
-        """Visit a <role_anchored_reference> node."""
-        # Determine the anchor role name
-        if "globalVariable" in children[0]:
-            # If the reference is anchored in a global variable, expand the `$` anchor. `$` is really
-            # just syntactic sugar for `@this.scratch.`, which means any reference anchored in a global
+    def visit_reference(_, children: Any) -> viv_compiler.types.EntityReference | viv_compiler.types.SymbolReference:
+        """Visit a <reference> node."""
+        is_symbol_reference = False
+        anchor_is_local_variable = False
+        if children[0] == "$":
+            # If the reference is anchored in a scratch variable, expand the `$` anchor. `$` is really
+            # just syntactic sugar for `@this.scratch.`, which means any reference anchored in a scratch
             # variable is in fact an entity reference anchored in a role name.
-            anchor = viv_compiler.config.GLOBAL_VARIABLE_REFERENCE_ANCHOR
+            children = children[1:]
+            if children[0] == "&":
+                # We will ignore the symbol sigil here, because ultimately that refers to the type of
+                # the scratch variable, not the anchor, which is always entity data.
+                pass
+            children = children[1:]
+            anchor = viv_compiler.config.SCRATCH_VARIABLE_REFERENCE_ANCHOR
             path = [
-                *viv_compiler.config.GLOBAL_VARIABLE_REFERENCE_PATH_PREFIX,
+                *viv_compiler.config.SCRATCH_VARIABLE_REFERENCE_PATH_PREFIX,
                 {
                     "type": ReferencePathComponentDiscriminator.REFERENCE_PATH_COMPONENT_PROPERTY_NAME,
-                    "name": children[0]["name"],
+                    "name": children[0],
                 }
             ]
             path += children[1] if len(children) > 1 else []
-        else:
-            anchor = children[0]["name"]
+        elif children[0] == "_":
+            anchor_is_local_variable = True
+            children = children[1:]
+            if children[0] == "&":
+                is_symbol_reference = True
+            children = children[1:]
+            anchor = children[0]
+            path = children[1] if len(children) > 1 else []
+        else:  # Bare reference to a role, e.g., `@foo` or `&bar`
+            if children[0] == "&":
+                is_symbol_reference = True
+            children = children[1:]
+            anchor = children[0]
             path = children[1] if len(children) > 1 else []
+        if is_symbol_reference:
+            component_type = ExpressionDiscriminator.SYMBOL_REFERENCE
+        else:
+            component_type = ExpressionDiscriminator.ENTITY_REFERENCE
         component = {
-            "type": ExpressionDiscriminator.ENTITY_REFERENCE,
+            "type": component_type,
             "value": {
-                "anchor": anchor,  # The name of the role anchoring this entity reference
-                "path": path,  # Sequence of components constituting a property path
+                "local": anchor_is_local_variable,
+                "anchor": anchor,
+                "path": path,
             }
         }
         return component
 
     @staticmethod
-    def visit_local_variable_anchored_reference(_, children: Any) -> viv_compiler.types.LocalVariableReference:
-        """Visit a <local_variable_anchored_reference> node."""
-        anchor = children[0]["name"]
-        path = children[1] if len(children) > 1 else []
-        component = {
-            "type": ExpressionDiscriminator.LOCAL_VARIABLE_REFERENCE,
-            "value": {
-                "anchor": anchor,  # The name of the local variable anchoring this reference
-                "path": path,  # Sequence of components constituting a property path
-            }
-        }
-        return component
+    def visit_entity_sigil(node: Any, _) -> Any:
+        """Visit an <entity_sigil> node."""
+        return node
 
     @staticmethod
-    def visit_role_reference(_, children: Any) -> dict[str, str]:
-        """Visit a <role_reference> node."""
-        name = children[0]
-        return {"name": name}
+    def visit_symbol_sigil(node: Any, _) -> Any:
+        """Visit a <symbol_sigil> node."""
+        return node
 
     @staticmethod
-    def visit_local_variable_reference(_, children: Any):
-        """Visit a <local_variable_reference> node."""
-        return {"name": children[0]}
+    def visit_scratch_variable_sigil(node: Any, _) -> Any:
+        """Visit a <scratch_variable_sigil> node."""
+        return node
 
     @staticmethod
-    def visit_global_variable_reference(_, children: Any):
-        """Visit a <global_variable_reference> node."""
-        return {"globalVariable": True, "name": children[0]}
+    def visit_local_variable_sigil(node: Any, _) -> Any:
+        """Visit a <local_variable_sigil> node."""
+        return node
 
     @staticmethod
     def visit_reference_path(_, children: Any) -> list[viv_compiler.types.ReferencePathComponent]:
@@ -1093,7 +1131,7 @@ class Visitor(arpeggio.PTNodeVisitor):
         if len(children) > 1:
             additive_inverse_present = children[0] == "-"
         token = children[-1]
-        unscaled = token[:2] == "##"  # As opposed to '#', which yields an scaled enum
+        unscaled = token[:2] == "##"  # As opposed to '#', which yields a scaled enum
         name = token.lstrip('#')
         component = {
             "type": ExpressionDiscriminator.ENUM,
@@ -1170,35 +1208,12 @@ class Visitor(arpeggio.PTNodeVisitor):
         component = {"type": ExpressionDiscriminator.NULL_TYPE, "value": None}
         return component
 
-    @staticmethod
-    def visit_tag(_, children: Any) -> viv_compiler.types.StringField:
-        """Visit a <tag> node."""
-        component = {"type": ExpressionDiscriminator.STRING, "value": children[0]}
-        return component
-
     @staticmethod
     def visit_eval_fail_safe_marker(_, __: Any) -> viv_compiler.types.EvalFailSafeField:
         """Visit an <eval_fail_safe_marker> node."""
         component = {"type": ExpressionDiscriminator.EVAL_FAIL_SAFE}
         return component
 
-    @staticmethod
-    def visit_trope(_, children: Any) -> dict[str, Any]:
-        """Visit a <trope> node."""
-        if len(children) == 3:
-            name, role_names, conditions = children
-        else:
-            name, conditions = children
-            role_names = []
-        component_value = {"name": name, "params": role_names, "conditions": conditions}
-        component = {"type": "trope", "value": component_value}
-        return component
-
-    @staticmethod
-    def visit_trope_role_names(_, children: Any) -> list[str]:
-        """Visit a <trope_role_names> node."""
-        return children
-
     @staticmethod
     def visit_trope_fit_expression(_, children: Any) -> viv_compiler.types.TropeFitExpression:
         """Visit a <trope_fit_expression> node."""