vex-ast 0.1.0__py3-none-any.whl

vex_ast/registry/signature.py

@@ -0,0 +1,143 @@
+from typing import Optional, List, Dict, Any, Union, Callable, Tuple
+from enum import Enum, auto
+from ..types.base import VexType, VOID, ANY
+
+class ParameterMode(Enum):
+    """Parameter passing modes"""
+    VALUE = auto()      # Pass by value
+    REFERENCE = auto()  # Pass by reference
+    OUTPUT = auto()     # Output parameter
+
+class VexFunctionParameter:
+    """Represents a parameter in a VEX function signature"""
+    
+    def __init__(self, 
+                 name: str, 
+                 type_: VexType, 
+                 default_value: Optional[Any] = None,
+                 mode: ParameterMode = ParameterMode.VALUE,
+                 description: str = ""):
+        self.name = name
+        self.type = type_
+        self.default_value = default_value
+        self.mode = mode
+        self.description = description
+        self.is_optional = default_value is not None
+    
+    def __str__(self) -> str:
+        mode_str = ""
+        if self.mode == ParameterMode.REFERENCE:
+            mode_str = "&"
+        elif self.mode == ParameterMode.OUTPUT:
+            mode_str = "*"
+            
+        default_str = ""
+        if self.is_optional:
+            default_str = f" = {self.default_value}"
+            
+        return f"{self.type}{mode_str} {self.name}{default_str}"
+
+class SimulationCategory(Enum):
+    """Categories for simulation behavior"""
+    MOTOR_CONTROL = auto()
+    SENSOR_READING = auto()
+    DISPLAY_OUTPUT = auto()
+    TIMING_CONTROL = auto()
+    COMPETITION = auto()
+    CONFIGURATION = auto()
+    CALCULATION = auto()
+    EVENT_HANDLING = auto()
+    OTHER = auto()
+
+SimulationBehaviorFunc = Callable[..., Any]
+
+class VexFunctionSignature:
+    """Represents the signature of a VEX function"""
+    
+    def __init__(self, 
+                 name: str, 
+                 return_type: VexType = VOID,
+                 parameters: List[Union[VexFunctionParameter, Tuple[str, str, Optional[Any]]]] = None,
+                 description: str = "",
+                 category: SimulationCategory = SimulationCategory.OTHER,
+                 simulation_behavior: Optional[SimulationBehaviorFunc] = None,
+                 python_name: Optional[str] = None,
+                 cpp_name: Optional[str] = None,
+                 object_type: Optional[VexType] = None,
+                 method_name: Optional[str] = None):
+        self.name = name
+        self.return_type = return_type
+        
+        # Convert tuple parameters to VexFunctionParameter objects
+        processed_params = []
+        if parameters:
+            for param in parameters:
+                if isinstance(param, VexFunctionParameter):
+                    processed_params.append(param)
+                elif isinstance(param, tuple) and len(param) >= 2:
+                    # Extract tuple values
+                    param_name = param[0]
+                    param_type = param[1]
+                    default_value = param[2] if len(param) > 2 else None
+                    processed_params.append(VexFunctionParameter(
+                        name=param_name,
+                        type_=param_type,
+                        default_value=default_value
+                    ))
+        
+        self.parameters = processed_params
+        self.description = description
+        self.category = category
+        self.simulation_behavior = simulation_behavior
+        self.python_name = python_name or name
+        self.cpp_name = cpp_name or name
+        self.object_type = object_type  # For methods, this is the class type
+        self.method_name = method_name  # For methods, this is the method name
+        
+        
+        # Validate there are no duplicate parameter names
+        param_names = [param.name for param in self.parameters]
+        if len(param_names) != len(set(param_names)):
+            raise ValueError(f"Duplicate parameter names in function {name}")
+        
+        # Ensure optional parameters come after required parameters
+        has_optional = False
+        for param in self.parameters:
+            if param.is_optional:
+                has_optional = True
+            elif has_optional:
+                raise ValueError(f"Required parameter after optional parameter in function {name}")
+    
+    def __str__(self) -> str:
+        params_str = ", ".join(str(param) for param in self.parameters)
+        return f"{self.return_type} {self.name}({params_str})"
+    
+    def validate_arguments(self, 
+                          args: List[Any], 
+                          kwargs: Dict[str, Any]) -> Tuple[bool, Optional[str]]:
+        """Validate function arguments against this signature"""
+        # Check if we have too many positional arguments
+        if len(args) > len(self.parameters):
+            return False, f"Too many positional arguments for {self.name}"
+        
+        # Check if we have unknown keyword arguments
+        param_names = {param.name for param in self.parameters}
+        for kwarg_name in kwargs:
+            if kwarg_name not in param_names:
+                return False, f"Unknown keyword argument '{kwarg_name}' for {self.name}"
+        
+        # Check if we have the required number of arguments
+        required_params = [p for p in self.parameters if not p.is_optional]
+        if len(args) + len(kwargs) < len(required_params):
+            return False, f"Missing required arguments for {self.name}"
+        
+        # Check if we have duplicate arguments
+        args_used = min(len(args), len(self.parameters))
+        for i in range(args_used):
+            param_name = self.parameters[i].name
+            if param_name in kwargs:
+                return False, f"Duplicate argument '{param_name}' for {self.name}"
+        
+        # TODO: Add type checking for arguments
+        
+        return True, None

vex_ast/registry/simulation_behavior.py

@@ -0,0 +1,9 @@
+# vex_ast/registry/simulation_behavior.py
+from enum import Enum, auto
+
+class SimulationBehavior(Enum):
+    """Categories of simulation behaviors for VEX functions"""
+    AFFECTS_MOTOR = "AFFECTS_MOTOR"
+    READS_SENSOR = "READS_SENSOR"
+    AFFECTS_TIMING = "AFFECTS_TIMING"
+    AFFECTS_DISPLAY = "AFFECTS_DISPLAY"

vex_ast/registry/validation.py

@@ -0,0 +1,44 @@
+from typing import Dict, List, Optional, Set, Tuple, Any, Union
+from ..types.base import VexType
+from ..types.type_checker import type_checker
+from .registry import registry, VexFunctionRegistry
+from .signature import VexFunctionSignature, VexFunctionParameter
+
+class FunctionCallValidator:
+    """Validates function calls against the registry"""
+    
+    def __init__(self, registry: VexFunctionRegistry = registry):
+        self.registry = registry
+    
+    def validate_call(self, 
+                    function_name: str, 
+                    args: List[Any] = None,
+                    kwargs: Dict[str, Any] = None,
+                    language: str = "python") -> Tuple[bool, Optional[str]]:
+        """Validate a function call"""
+        args = args or []
+        kwargs = kwargs or {}
+        return self.registry.validate_call(function_name, args, kwargs, language)
+    
+    def validate_method_call(self,
+                           object_type: Union[VexType, str],
+                           method_name: str,
+                           args: List[Any] = None,
+                           kwargs: Dict[str, Any] = None) -> Tuple[bool, Optional[str]]:
+        """Validate a method call on an object"""
+        args = args or []
+        kwargs = kwargs or {}
+        return self.registry.validate_method_call(object_type, method_name, args, kwargs)
+    
+    def validate_ast_function_call(self, function_call_node: Any) -> Tuple[bool, Optional[str]]:
+        """Validate a function call AST node"""
+        # This would need to be implemented based on the actual AST node structure
+        # For now, just a placeholder showing the interface
+        function_name = function_call_node.function.name
+        args = [arg.value for arg in function_call_node.args]
+        kwargs = {kw.name: kw.value for kw in function_call_node.keywords}
+        
+        return self.validate_call(function_name, args, kwargs)
+
+# Singleton instance
+validator = FunctionCallValidator()

vex_ast/serialization/__init__.py

@@ -0,0 +1,37 @@
+"""
+Serialization package for VEX AST.
+
+This package provides functionality for serializing and deserializing AST nodes
+to and from JSON format, as well as generating JSON schema for the AST structure.
+"""
+
+from .json_serializer import (
+    SerializationVisitor,
+    serialize_ast_to_dict,
+    serialize_ast_to_json
+)
+from .json_deserializer import (
+    DeserializationFactory,
+    deserialize_ast_from_dict,
+    deserialize_ast_from_json
+)
+from .schema import (
+    generate_ast_schema,
+    export_schema_to_file
+)
+
+__all__ = [
+    # Serialization
+    "SerializationVisitor",
+    "serialize_ast_to_dict",
+    "serialize_ast_to_json",
+    
+    # Deserialization
+    "DeserializationFactory",
+    "deserialize_ast_from_dict",
+    "deserialize_ast_from_json",
+    
+    # Schema
+    "generate_ast_schema",
+    "export_schema_to_file"
+]

vex_ast/serialization/json_deserializer.py

@@ -0,0 +1,264 @@
+"""
+JSON deserialization for AST nodes.
+
+This module provides functionality to convert JSON data back to AST nodes.
+"""
+
+import json
+from typing import Any, Dict, List, Optional, Type, Union, cast
+
+from ..ast.interfaces import IAstNode
+from ..parser.factory import NodeFactory
+from ..utils.source_location import SourceLocation
+from ..utils.errors import ErrorHandler
+
+
+class DeserializationFactory:
+    """
+    Factory for deserializing JSON data back to AST nodes.
+    
+    This class uses the NodeFactory to create AST nodes from serialized data,
+    handling the reconstruction of the node hierarchy and parent-child relationships.
+    """
+    
+    def __init__(self, error_handler: Optional[ErrorHandler] = None):
+        """
+        Initialize the deserialization factory.
+        
+        Args:
+            error_handler: Optional error handler for reporting deserialization issues
+        """
+        self.node_factory = NodeFactory(error_handler)
+        self.error_handler = error_handler
+    
+    def deserialize_node(self, data: Dict[str, Any]) -> IAstNode:
+        """
+        Deserialize a dictionary representation back to an AST node.
+        
+        Args:
+            data: Dictionary representation of an AST node
+            
+        Returns:
+            The reconstructed AST node
+            
+        Raises:
+            ValueError: If the data is invalid or missing required fields
+        """
+        # Extract node type
+        if "type" not in data:
+            raise ValueError("Missing 'type' field in node data")
+            
+        node_type = data["type"]
+        
+        # Create source location if present
+        location = None
+        if "location" in data:
+            location = self._deserialize_location(data["location"])
+        
+        # Dispatch to appropriate creation method based on node type
+        method_name = f"_create_{node_type.lower()}"
+        if hasattr(self, method_name):
+            create_method = getattr(self, method_name)
+            node = create_method(data, location)
+        else:
+            # Fallback to generic creation if no specific method exists
+            node = self._create_generic_node(node_type, data, location)
+            
+        return node
+    
+    def _deserialize_location(self, data: Dict[str, Any]) -> SourceLocation:
+        """
+        Deserialize a dictionary to a SourceLocation object.
+        
+        Args:
+            data: Dictionary representation of a source location
+            
+        Returns:
+            A SourceLocation object
+        """
+        return SourceLocation(
+            line=data["line"],
+            column=data["column"],
+            end_line=data.get("end_line"),
+            end_column=data.get("end_column"),
+            filename=data.get("filename")
+        )
+    
+    def _deserialize_value(self, value: Any) -> Any:
+        """
+        Deserialize a value based on its type.
+        
+        Args:
+            value: The value to deserialize
+            
+        Returns:
+            The deserialized value
+        """
+        # Handle None
+        if value is None:
+            return None
+            
+        # Handle dictionaries (potentially nested nodes)
+        if isinstance(value, dict) and "type" in value:
+            return self.deserialize_node(value)
+            
+        # Handle lists of values
+        if isinstance(value, list):
+            return [self._deserialize_value(item) for item in value]
+            
+        # Handle dictionaries (not nodes)
+        if isinstance(value, dict):
+            return {k: self._deserialize_value(v) for k, v in value.items()}
+            
+        # Return basic types as-is
+        return value
+    
+    def _create_generic_node(self, node_type: str, data: Dict[str, Any], 
+                            location: Optional[SourceLocation]) -> IAstNode:
+        """
+        Generic node creation when no specific method exists.
+        
+        Args:
+            node_type: The type of node to create
+            data: Dictionary representation of the node
+            location: Optional source location
+            
+        Returns:
+            The created AST node
+            
+        Raises:
+            ValueError: If the node type is not supported
+        """
+        # Map of node types to factory methods
+        factory_methods = {
+            # Literals
+            "NumberLiteral": self.node_factory.create_number_literal,
+            "StringLiteral": self.node_factory.create_string_literal,
+            "BooleanLiteral": self.node_factory.create_boolean_literal,
+            "NoneLiteral": self.node_factory.create_none_literal,
+            
+            # Expressions
+            "Identifier": self.node_factory.create_identifier,
+            "VariableReference": self.node_factory.create_variable_reference,
+            "AttributeAccess": self.node_factory.create_attribute_access,
+            "BinaryOperation": self.node_factory.create_binary_operation,
+            "UnaryOperation": self.node_factory.create_unary_operation,
+            "FunctionCall": self.node_factory.create_function_call,
+            "KeywordArgument": self.node_factory.create_keyword_argument,
+            
+            # Statements
+            "ExpressionStatement": self.node_factory.create_expression_statement,
+            "Assignment": self.node_factory.create_assignment,
+            "IfStatement": self.node_factory.create_if_statement,
+            "WhileLoop": self.node_factory.create_while_loop,
+            "ForLoop": self.node_factory.create_for_loop,
+            "FunctionDefinition": self.node_factory.create_function_definition,
+            "ReturnStatement": self.node_factory.create_return_statement,
+            "BreakStatement": self.node_factory.create_break_statement,
+            "ContinueStatement": self.node_factory.create_continue_statement,
+            
+            # VEX-specific nodes
+            "VexAPICall": self.node_factory.create_vex_api_call,
+            "MotorControl": self.node_factory.create_motor_control,
+            "SensorReading": self.node_factory.create_sensor_reading,
+            "TimingControl": self.node_factory.create_timing_control,
+            "DisplayOutput": self.node_factory.create_display_output,
+            
+            # Core
+            "Program": self.node_factory.create_program,
+        }
+        
+        if node_type not in factory_methods:
+            raise ValueError(f"Unsupported node type: {node_type}")
+            
+        # Extract and deserialize attributes
+        kwargs = {}
+        for key, value in data.items():
+            if key not in ["type", "location"]:
+                kwargs[key] = self._deserialize_value(value)
+                
+        # Create the node using the appropriate factory method
+        factory_method = factory_methods[node_type]
+        
+        # Special handling for certain node types
+        if node_type == "Program":
+            return factory_method(kwargs.get("body", []), location)
+        elif node_type in ["NumberLiteral", "StringLiteral", "BooleanLiteral"]:
+            return factory_method(kwargs.get("value"), location)
+        elif node_type == "NoneLiteral":
+            return factory_method(location)
+        elif node_type == "Identifier":
+            return factory_method(kwargs.get("name", ""), location)
+        
+        # For other node types, pass all kwargs and location
+        # This is a simplified approach; in a real implementation,
+        # you would need to handle each node type specifically
+        try:
+            return factory_method(**kwargs, location=location)
+        except TypeError as e:
+            # If the factory method doesn't accept the kwargs, report an error
+            if self.error_handler:
+                self.error_handler.report_error(f"Failed to create {node_type}: {str(e)}")
+            raise ValueError(f"Failed to deserialize {node_type}: {str(e)}")
+    
+    # Specific node creation methods for complex cases
+    
+    def _create_program(self, data: Dict[str, Any], 
+                       location: Optional[SourceLocation]) -> IAstNode:
+        """Create a Program node from serialized data."""
+        body = [self._deserialize_value(stmt) for stmt in data.get("body", [])]
+        return self.node_factory.create_program(body, location)
+    
+    def _create_functioncall(self, data: Dict[str, Any], 
+                            location: Optional[SourceLocation]) -> IAstNode:
+        """Create a FunctionCall node from serialized data."""
+        function = self._deserialize_value(data.get("function"))
+        args = [self._deserialize_value(arg) for arg in data.get("args", [])]
+        keywords = [self._deserialize_value(kw) for kw in data.get("keywords", [])]
+        return self.node_factory.create_function_call(function, args, keywords, location)
+    
+    def _create_ifstatement(self, data: Dict[str, Any], 
+                           location: Optional[SourceLocation]) -> IAstNode:
+        """Create an IfStatement node from serialized data."""
+        test = self._deserialize_value(data.get("test"))
+        body = [self._deserialize_value(stmt) for stmt in data.get("body", [])]
+        orelse = None
+        if "orelse" in data:
+            orelse_data = data["orelse"]
+            if isinstance(orelse_data, list):
+                orelse = [self._deserialize_value(stmt) for stmt in orelse_data]
+            else:
+                orelse = self._deserialize_value(orelse_data)
+        return self.node_factory.create_if_statement(test, body, orelse, location)
+
+
+def deserialize_ast_from_dict(data: Dict[str, Any], 
+                             error_handler: Optional[ErrorHandler] = None) -> IAstNode:
+    """
+    Create an AST from a dictionary representation.
+    
+    Args:
+        data: Dictionary representation of an AST
+        error_handler: Optional error handler for reporting deserialization issues
+        
+    Returns:
+        The reconstructed AST
+    """
+    factory = DeserializationFactory(error_handler)
+    return factory.deserialize_node(data)
+
+
+def deserialize_ast_from_json(json_str: str, 
+                             error_handler: Optional[ErrorHandler] = None) -> IAstNode:
+    """
+    Create an AST from a JSON string.
+    
+    Args:
+        json_str: JSON string representation of an AST
+        error_handler: Optional error handler for reporting deserialization issues
+        
+    Returns:
+        The reconstructed AST
+    """
+    data = json.loads(json_str)
+    return deserialize_ast_from_dict(data, error_handler)

vex_ast/serialization/json_serializer.py

@@ -0,0 +1,148 @@
+"""
+JSON serialization for AST nodes.
+
+This module provides functionality to convert AST nodes to JSON format.
+"""
+
+import json
+from typing import Any, Dict, List, Optional, Union, cast
+
+from ..ast.interfaces import IAstNode
+from ..visitors.base import AstVisitor
+from ..utils.source_location import SourceLocation
+
+
+class SerializationVisitor(AstVisitor[Dict[str, Any]]):
+    """
+    Visitor that converts AST nodes to dictionary representations.
+    
+    This visitor traverses the AST and converts each node to a dictionary
+    that can be serialized to JSON. The dictionaries include node type
+    information and all relevant attributes.
+    """
+    
+    def generic_visit(self, node: IAstNode) -> Dict[str, Any]:
+        """
+        Default serialization logic for all node types.
+        
+        Args:
+            node: The AST node to serialize
+            
+        Returns:
+            A dictionary representation of the node
+        """
+        # Get the node's class name for type information
+        node_type = node.__class__.__name__
+        
+        # Start with basic node information
+        result = {
+            "type": node_type,
+        }
+        
+        # Add source location if available
+        if node.location:
+            result["location"] = self._serialize_location(node.location)
+        
+        # Add all attributes from the node
+        attributes = node.get_attributes()
+        for name, value in attributes.items():
+            # Skip internal attributes and parent reference
+            if name.startswith('_'):
+                continue
+                
+            # Handle different attribute types
+            result[name] = self._serialize_attribute(value)
+            
+        return result
+    
+    def _serialize_location(self, location: SourceLocation) -> Dict[str, Any]:
+        """
+        Serialize a source location to a dictionary.
+        
+        Args:
+            location: The source location to serialize
+            
+        Returns:
+            A dictionary representation of the source location
+        """
+        result = {
+            "line": location.line,
+            "column": location.column,
+        }
+        
+        if location.end_line is not None:
+            result["end_line"] = location.end_line
+            
+        if location.end_column is not None:
+            result["end_column"] = location.end_column
+            
+        if location.filename:
+            result["filename"] = location.filename
+            
+        return result
+    
+    def _serialize_attribute(self, value: Any) -> Any:
+        """
+        Serialize an attribute value based on its type.
+        
+        Args:
+            value: The attribute value to serialize
+            
+        Returns:
+            A serialized representation of the value
+        """
+        # Handle None
+        if value is None:
+            return None
+            
+        # Handle AST nodes
+        if isinstance(value, IAstNode):
+            return self.visit(value)
+            
+        # Handle lists of values
+        if isinstance(value, list):
+            return [self._serialize_attribute(item) for item in value]
+            
+        # Handle dictionaries
+        if isinstance(value, dict):
+            return {k: self._serialize_attribute(v) for k, v in value.items()}
+            
+        # Handle basic types (strings, numbers, booleans)
+        if isinstance(value, (str, int, float, bool)):
+            return value
+            
+        # Handle Operator enum values
+        if hasattr(value, '__module__') and 'operators' in value.__module__ and hasattr(value, 'value'):
+            return value.value
+            
+        # For other types, convert to string
+        return str(value)
+
+
+def serialize_ast_to_dict(ast: IAstNode) -> Dict[str, Any]:
+    """
+    Convert an AST node to a dictionary representation.
+    
+    Args:
+        ast: The AST node to serialize
+        
+    Returns:
+        A dictionary representation of the AST
+    """
+    visitor = SerializationVisitor()
+    return visitor.visit(ast)
+
+
+def serialize_ast_to_json(ast: IAstNode, indent: Optional[int] = None) -> str:
+    """
+    Convert an AST node to a JSON string.
+    
+    Args:
+        ast: The AST node to serialize
+        indent: Optional indentation level for pretty-printing
+        
+    Returns:
+        A JSON string representation of the AST
+    """
+    data = serialize_ast_to_dict(ast)
+    return json.dumps(data, indent=indent)