vex-ast 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

vex_ast/registry/functions/timing.py

@@ -0,0 +1,104 @@
+from ..registry import registry
+from ..signature import VexFunctionSignature, VexFunctionParameter, ParameterMode, SimulationCategory
+from ...types.base import VOID, ANY
+from ...types.primitives import INT, FLOAT, BOOL
+from ...types.enums import TIME_UNITS
+from ...types.objects import TIMER
+
+def register_timing_functions():
+    """Register timing-related functions in the registry"""
+    
+    # Global wait function
+    wait_params = [
+        VexFunctionParameter("time", FLOAT, description="Time to wait"),
+        VexFunctionParameter("units", TIME_UNITS, "MSEC", description="Time units")
+    ]
+    
+    wait_signature = VexFunctionSignature(
+        name="wait",
+        return_type=VOID,
+        parameters=wait_params,
+        description="Wait for a specified amount of time",
+        category=SimulationCategory.TIMING_CONTROL,
+        python_name="wait",
+        cpp_name="wait"
+    )
+    
+    registry.register_function(wait_signature)
+    
+    # Timer functions
+    
+    # Timer.time() method
+    time_params = [
+        VexFunctionParameter("units", TIME_UNITS, "MSEC", description="Time units")
+    ]
+    
+    time_signature = VexFunctionSignature(
+        name="time",
+        return_type=FLOAT,
+        parameters=time_params,
+        description="Get the current time of the timer",
+        category=SimulationCategory.TIMING_CONTROL,
+        python_name="time",
+        cpp_name="time",
+        object_type=TIMER,
+        method_name="time"
+    )
+    
+    registry.register_function(time_signature)
+    
+    # Timer.clear() method
+    clear_signature = VexFunctionSignature(
+        name="clear",
+        return_type=VOID,
+        parameters=[],
+        description="Clear the timer",
+        category=SimulationCategory.TIMING_CONTROL,
+        python_name="clear",
+        cpp_name="clear",
+        object_type=TIMER,
+        method_name="clear"
+    )
+    
+    registry.register_function(clear_signature)
+    
+    # Timer.reset() method
+    reset_signature = VexFunctionSignature(
+        name="reset",
+        return_type=VOID,
+        parameters=[],
+        description="Reset the timer",
+        category=SimulationCategory.TIMING_CONTROL,
+        python_name="reset",
+        cpp_name="reset",
+        object_type=TIMER,
+        method_name="reset"
+    )
+    
+    registry.register_function(reset_signature)
+    
+    # Timer.event() method
+    event_params = [
+        VexFunctionParameter("callback", ANY, description="Callback function to execute"),
+        VexFunctionParameter("delay", FLOAT, description="Time delay before callback execution"),
+        VexFunctionParameter("units", TIME_UNITS, "MSEC", description="Time units")
+    ]
+    
+    event_signature = VexFunctionSignature(
+        name="event",
+        return_type=VOID,
+        parameters=event_params,
+        description="Register a callback function to be called after a delay",
+        category=SimulationCategory.EVENT_HANDLING,
+        python_name="event",
+        cpp_name="event",
+        object_type=TIMER,
+        method_name="event"
+    )
+    
+    registry.register_function(event_signature)
+    
+    # Add more timing functions as needed...
+
+if __name__ == "__main__":
+    register_timing_functions()

vex_ast/types/README.md

@@ -0,0 +1,26 @@
+# VEX AST Types Package (vex_ast.types)
+
+This package defines the type system used for the VEX V5 Robot Python language.
+
+Purpose
+
+The type system provides a way to represent and reason about the types of values in VEX code. This information is used for type checking, code optimization, and other purposes.
+
+Structure
+
+The package is organized into several modules:
+
+*   `base.py`: Defines base classes for types.
+*   `enums.py`: Defines enums for different type categories.
+*   `objects.py`: Defines classes for representing objects.
+*   `primitives.py`: Defines classes for representing primitive types (e.g., int, float, string, boolean).
+*   `type_checker.py`: Implements the type checking logic.
+
+Key Concepts
+
+*   Types: Represent the kind of value that a variable or expression can have.
+*   Type checking: The process of verifying that the types in a program are consistent.
+
+Usage
+
+The type system is used internally by the VEX AST parser, type checker, and other tools. It is not typically accessed directly by users.

vex_ast/types/__init__.py

@@ -0,0 +1,140 @@
+"""
+Types package for VEX AST.
+
+This package provides type definitions and type checking functionality for VEX AST.
+"""
+
+from .base import (
+    VexType,
+    VoidType,
+    AnyType,
+    TypeRegistry,
+    VOID,
+    ANY,
+    type_registry
+)
+
+from .primitives import (
+    PrimitiveType,
+    IntegerType,
+    FloatType,
+    BooleanType,
+    StringType,
+    INT,
+    FLOAT,
+    BOOL,
+    STRING
+)
+
+from .objects import (
+    ObjectType,
+    MOTOR,
+    MOTOR_GROUP,
+    DRIVETRAIN,
+    BRAIN,
+    CONTROLLER,
+    INERTIAL,
+    DISTANCE,
+    ROTATION,
+    OPTICAL,
+    GPS,
+    ELECTROMAGNETIC,
+    BRAIN_BATTERY,
+    BRAIN_SCREEN,
+    BRAIN_LCD,
+    COMPETITION,
+    TIMER,
+    BUMPER,
+    LIMIT_SWITCH,
+    ENCODER,
+    SONAR,
+    GYRO,
+    PNEUMATIC,
+    VISION
+)
+
+from .enums import (
+    EnumType,
+    DIRECTION_TYPE,
+    TURN_TYPE,
+    BRAKE_TYPE,
+    VELOCITY_UNITS,
+    ROTATION_UNITS,
+    TIME_UNITS,
+    DISTANCE_UNITS,
+    CURRENT_UNITS,
+    TORQUE_UNITS,
+    TEMPERATURE_UNITS,
+    ANALOG_UNITS
+)
+
+from .type_checker import (
+    TypeChecker,
+    type_checker as check_type_compatibility
+)
+
+__all__ = [
+    # Base types
+    "VexType",
+    "VoidType",
+    "AnyType",
+    "TypeRegistry",
+    "VOID",
+    "ANY",
+    "type_registry",
+    
+    # Primitive types
+    "PrimitiveType",
+    "IntegerType",
+    "FloatType",
+    "BooleanType",
+    "StringType",
+    "INT",
+    "FLOAT",
+    "BOOL",
+    "STRING",
+    
+    # Object types
+    "ObjectType",
+    "MOTOR",
+    "MOTOR_GROUP",
+    "DRIVETRAIN",
+    "BRAIN",
+    "CONTROLLER",
+    "INERTIAL",
+    "DISTANCE",
+    "ROTATION",
+    "OPTICAL",
+    "GPS",
+    "ELECTROMAGNETIC",
+    "BRAIN_BATTERY",
+    "BRAIN_SCREEN",
+    "BRAIN_LCD",
+    "COMPETITION",
+    "TIMER",
+    "BUMPER",
+    "LIMIT_SWITCH",
+    "ENCODER",
+    "SONAR",
+    "GYRO",
+    "PNEUMATIC",
+    "VISION",
+    
+    # Enum types
+    "EnumType",
+    "DIRECTION_TYPE",
+    "TURN_TYPE",
+    "BRAKE_TYPE",
+    "VELOCITY_UNITS",
+    "ROTATION_UNITS",
+    "TIME_UNITS",
+    "DISTANCE_UNITS",
+    "CURRENT_UNITS",
+    "TORQUE_UNITS",
+    "TEMPERATURE_UNITS",
+    "ANALOG_UNITS",
+    
+    # Type checking
+    "TypeChecker",
+    "check_type_compatibility"
+]

vex_ast/types/base.py

@@ -0,0 +1,84 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional, Union, List, Type, Set, TypeVar, Generic
+
+class VexType(ABC):
+    """Base abstract class for all VEX types"""
+    
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the canonical name of this type"""
+        pass
+    
+    @abstractmethod
+    def is_compatible_with(self, other: 'VexType') -> bool:
+        """Check if this type is compatible with another type"""
+        pass
+    
+    @abstractmethod
+    def __str__(self) -> str:
+        """String representation of the type"""
+        pass
+    
+    def __eq__(self, other) -> bool:
+        if not isinstance(other, VexType):
+            return False
+        return self.name == other.name
+
+class VoidType(VexType):
+    """Represents the void type (no return value)"""
+    
+    @property
+    def name(self) -> str:
+        return "void"
+    
+    def is_compatible_with(self, other: VexType) -> bool:
+        return isinstance(other, VoidType)
+    
+    def __str__(self) -> str:
+        return "void"
+
+class AnyType(VexType):
+    """Represents any type (for generic functions)"""
+    
+    @property
+    def name(self) -> str:
+        return "any"
+    
+    def is_compatible_with(self, other: VexType) -> bool:
+        return True  # Any type is compatible with all types
+    
+    def __str__(self) -> str:
+        return "any"
+
+class TypeRegistry:
+    """Global registry of types to ensure type uniqueness"""
+    
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(TypeRegistry, cls).__new__(cls)
+            cls._instance._types = {}
+        return cls._instance
+    
+    def register_type(self, type_: VexType) -> None:
+        """Register a type in the registry"""
+        self._types[type_.name] = type_
+    
+    def get_type(self, name: str) -> Optional[VexType]:
+        """Get a type by name"""
+        return self._types.get(name)
+    
+    def get_all_types(self) -> List[VexType]:
+        """Get all registered types"""
+        return list(self._types.values())
+
+# Singleton instances
+VOID = VoidType()
+ANY = AnyType()
+
+# Global registry
+type_registry = TypeRegistry()
+type_registry.register_type(VOID)
+type_registry.register_type(ANY)

vex_ast/types/enums.py

@@ -0,0 +1,97 @@
+from typing import Dict, List, Any, Optional, Set
+from .base import VexType, type_registry
+from .primitives import StringType, IntegerType, INT
+
+class EnumType(VexType):
+    """Represents a VEX enum type"""
+    
+    def __init__(self, name: str, values: Dict[str, Any] = None):
+        self._name = name
+        self._values = values or {}
+        type_registry.register_type(self)
+    
+    @property
+    def name(self) -> str:
+        return self._name
+    
+    @property
+    def values(self) -> Dict[str, Any]:
+        return self._values.copy()
+    
+    def is_compatible_with(self, other: VexType) -> bool:
+        """Enums are compatible with themselves or with integers"""
+        return isinstance(other, EnumType) and self.name == other.name or isinstance(other, IntegerType)
+    
+    def __str__(self) -> str:
+        return f"enum {self._name}"
+    
+    def add_value(self, name: str, value: Any) -> None:
+        """Add a value to the enum"""
+        self._values[name] = value
+    
+    def is_valid_value(self, value: Any) -> bool:
+        """Check if a value is valid for this enum"""
+        return value in self._values.values() or value in self._values
+
+# Create VEX enum types
+DIRECTION_TYPE = EnumType("DirectionType", {
+    "FORWARD": 0,
+    "REVERSE": 1
+})
+
+TURN_TYPE = EnumType("TurnType", {
+    "LEFT": 0,
+    "RIGHT": 1
+})
+
+BRAKE_TYPE = EnumType("BrakeType", {
+    "COAST": 0,
+    "BRAKE": 1,
+    "HOLD": 2
+})
+
+VELOCITY_UNITS = EnumType("VelocityUnits", {
+    "PCT": 0,       # Percentage
+    "RPM": 1,       # Revolutions per minute
+    "DPS": 2        # Degrees per second
+})
+
+ROTATION_UNITS = EnumType("RotationUnits", {
+    "DEG": 0,       # Degrees
+    "REV": 1,       # Revolutions
+    "RAW": 2        # Raw data
+})
+
+TIME_UNITS = EnumType("TimeUnits", {
+    "SEC": 0,       # Seconds
+    "MSEC": 1       # Milliseconds
+})
+
+DISTANCE_UNITS = EnumType("DistanceUnits", {
+    "MM": 0,        # Millimeters
+    "IN": 1         # Inches
+})
+
+CURRENT_UNITS = EnumType("CurrentUnits", {
+    "AMP": 0        # Amperes
+})
+
+TORQUE_UNITS = EnumType("TorqueUnits", {
+    "NM": 0,        # Newton meters
+    "INLB": 1       # Inch pounds
+})
+
+TEMPERATURE_UNITS = EnumType("TemperatureUnits", {
+    "CELSIUS": 0,
+    "FAHRENHEIT": 1
+})
+
+ANALOG_UNITS = EnumType("AnalogUnits", {
+    "PCT": 0,       # Percentage
+    "EIGHTBIT": 1,  # 8-bit (0-255)
+    "TENBIT": 2,    # 10-bit (0-1023)
+    "TWELVEBIT": 3, # 12-bit (0-4095)
+    "MV": 4         # Millivolts
+})
+
+# Add more VEX enum types as needed

vex_ast/types/objects.py

@@ -0,0 +1,64 @@
+from typing import Optional, List, Dict, Any, Set, TYPE_CHECKING
+from .base import VexType, type_registry
+
+# Use TYPE_CHECKING to avoid circular imports
+if TYPE_CHECKING:
+    from ..registry.signature import VexFunctionSignature
+
+class ObjectType(VexType):
+    """Base class for all VEX object types (motors, sensors, etc.)"""
+    
+    def __init__(self, name: str, methods: Dict[str, 'VexFunctionSignature'] = None):
+        self._name = name
+        self._methods = methods or {}
+        type_registry.register_type(self)
+    
+    @property
+    def name(self) -> str:
+        return self._name
+    
+    @property
+    def methods(self) -> Dict[str, Any]:  # Use Any instead of forward reference
+        return self._methods
+    
+    def add_method(self, method_name: str, signature: Any) -> None:  # Use Any instead of forward reference
+        """Add a method to this object type"""
+        self._methods[method_name] = signature
+    
+    def get_method(self, method_name: str) -> Optional[Any]:  # Use Any instead of forward reference
+        """Get a method by name"""
+        return self._methods.get(method_name)
+    
+    def is_compatible_with(self, other: VexType) -> bool:
+        """Objects are compatible only with the same type"""
+        return isinstance(other, ObjectType) and self.name == other.name
+    
+    def __str__(self) -> str:
+        return self._name
+
+# VEX object types - define basic types here, methods will be added later
+MOTOR = ObjectType("Motor")
+MOTOR_GROUP = ObjectType("MotorGroup")
+DRIVETRAIN = ObjectType("Drivetrain")
+BRAIN = ObjectType("Brain")
+CONTROLLER = ObjectType("Controller")
+INERTIAL = ObjectType("Inertial")
+DISTANCE = ObjectType("Distance")
+ROTATION = ObjectType("Rotation")
+OPTICAL = ObjectType("Optical")
+GPS = ObjectType("GPS")
+ELECTROMAGNETIC = ObjectType("Electromagnetic")
+BRAIN_BATTERY = ObjectType("BrainBattery")
+BRAIN_SCREEN = ObjectType("BrainScreen")
+BRAIN_LCD = ObjectType("BrainLcd")
+COMPETITION = ObjectType("Competition")
+TIMER = ObjectType("Timer")
+BUMPER = ObjectType("Bumper")
+LIMIT_SWITCH = ObjectType("LimitSwitch")
+ENCODER = ObjectType("Encoder")
+SONAR = ObjectType("Sonar")
+GYRO = ObjectType("Gyro")
+PNEUMATIC = ObjectType("Pneumatic")
+VISION = ObjectType("Vision")
+
+# Add additional object types as needed

vex_ast/types/primitives.py

@@ -0,0 +1,69 @@
+from typing import Optional, Union, List, Set, Dict, Any
+from .base import VexType, type_registry
+
+class PrimitiveType(VexType):
+    """Base class for primitive types like int, float, string, etc."""
+    
+    def __init__(self, name: str):
+        self._name = name
+        type_registry.register_type(self)
+    
+    @property
+    def name(self) -> str:
+        return self._name
+    
+    def __str__(self) -> str:
+        return self._name
+
+class NumericType(PrimitiveType):
+    """Base class for numeric types"""
+    
+    def is_compatible_with(self, other: VexType) -> bool:
+        """Numeric types are compatible with other numeric types"""
+        return isinstance(other, NumericType)
+
+class IntegerType(NumericType):
+    """Integer type"""
+    
+    def __init__(self):
+        super().__init__("int")
+    
+    def is_compatible_with(self, other: VexType) -> bool:
+        """Integers are compatible with numeric types"""
+        return isinstance(other, NumericType)
+
+class FloatType(NumericType):
+    """Float type"""
+    
+    def __init__(self):
+        super().__init__("float")
+    
+    def is_compatible_with(self, other: VexType) -> bool:
+        """Floats are compatible with numeric types"""
+        return isinstance(other, NumericType)
+
+class BooleanType(PrimitiveType):
+    """Boolean type"""
+    
+    def __init__(self):
+        super().__init__("bool")
+    
+    def is_compatible_with(self, other: VexType) -> bool:
+        """Booleans are only compatible with booleans"""
+        return isinstance(other, BooleanType)
+
+class StringType(PrimitiveType):
+    """String type"""
+    
+    def __init__(self):
+        super().__init__("string")
+    
+    def is_compatible_with(self, other: VexType) -> bool:
+        """Strings are only compatible with strings"""
+        return isinstance(other, StringType)
+
+# Singleton instances
+INT = IntegerType()
+FLOAT = FloatType()
+BOOL = BooleanType()
+STRING = StringType()

vex_ast/types/type_checker.py

@@ -0,0 +1,32 @@
+from typing import Optional, Any, List, Dict, Union, Tuple
+from .base import VexType, ANY
+from .primitives import INT, FLOAT, BOOL, STRING
+
+class TypeChecker:
+    """Utility for checking type compatibility"""
+    
+    def is_compatible(self, value_type: VexType, expected_type: VexType) -> bool:
+        """Check if value_type is compatible with expected_type"""
+        # Any type is compatible with anything
+        if expected_type == ANY:
+            return True
+            
+        return value_type.is_compatible_with(expected_type)
+    
+    def get_python_type(self, value: Any) -> Optional[VexType]:
+        """Convert a Python value to a VEX type"""
+        if value is None:
+            return None
+        if isinstance(value, bool):
+            return BOOL
+        if isinstance(value, int):
+            return INT
+        if isinstance(value, float):
+            return FLOAT
+        if isinstance(value, str):
+            return STRING
+        # Complex objects would need additional mapping logic
+        return None
+
+# Singleton instance
+type_checker = TypeChecker()

vex_ast/utils/README.md

@@ -0,0 +1,39 @@
+Utilities (vex_ast.utils)
+
+This directory contains utility modules that provide supporting functionality for the VEX AST parser and other components.
+
+Purpose
+
+These modules encapsulate common tasks and data structures needed across the vex_ast package, promoting code reuse and separation of concerns.
+
+Modules
+
+Error Handling (errors.py):
+
+ErrorType: An enum defining categories of errors (e.g., PARSER_ERROR, SEMANTIC_ERROR).
+
+Error: A class representing a single error instance, containing the type, message, optional source location, and optional suggestion.
+
+ErrorHandler: A central class for collecting and managing errors encountered during parsing or AST processing. It allows registering observers and can optionally raise exceptions immediately upon error detection.
+
+VexAstError, VexSyntaxError: Custom exception classes for AST-related errors, with VexSyntaxError specifically for parsing issues.
+
+Importance: Provides a robust way to handle and report problems found in the source code or during AST processing, crucial for user feedback and debugging.
+
+Source Location (source_location.py):
+
+SourceLocation: A dataclass representing a position or span within the original source code file. It includes line and column numbers (and optionally end line/column and filename).
+
+Importance: Allows AST nodes and errors to be linked back to their origin in the source code, which is essential for accurate error reporting, debugging tools, and source mapping.
+
+Usage
+
+These utilities are primarily used internally by other parts of the vex_ast package:
+
+The PythonParser uses the ErrorHandler to report syntax errors or issues during AST conversion. It uses SourceLocation to tag generated AST nodes with their origin.
+
+AST Node classes store SourceLocation objects.
+
+Visitors might use the ErrorHandler if they perform analysis that detects semantic errors.
+
+Error messages often include the string representation of a SourceLocation.

vex_ast/utils/__init__.py

@@ -0,0 +1,38 @@
+"""
+Utilities package for VEX AST.
+
+This package provides utility functions and classes for working with the AST.
+"""
+
+from .errors import (
+    ErrorHandler,
+    ErrorType,
+    VexSyntaxError,
+    VexAstError,
+    Error
+)
+from .source_location import (
+    SourceLocation,
+)
+from .type_definitions import (
+    NodeType,
+    VisitorType,
+    TransformerType
+)
+
+__all__ = [
+    # Error handling
+    "ErrorHandler",
+    "ErrorType",
+    "VexSyntaxError",
+    "VexAstError",
+    "Error",
+    
+    # Source location
+    "SourceLocation",
+    
+    # Type definitions
+    "NodeType",
+    "VisitorType",
+    "TransformerType"
+]