vex-ast 0.1.0__py3-none-any.whl

vex_ast/registry/__init__.py

@@ -0,0 +1,51 @@
+"""Registry package for VEX AST functions and types."""
+
+from .registry import registry, VexFunctionRegistry
+from .signature import (
+    VexFunctionSignature, 
+    VexFunctionParameter, 
+    ParameterMode,
+    SimulationCategory
+)
+from .categories import (
+    FunctionCategory, 
+    SubCategory,
+    categorizer
+)
+from .language_map import language_mapper
+from .validation import validator
+from .simulation_behavior import SimulationBehavior
+from .api import registry_api, RegistryAPI
+
+# Initialize registry with default values
+def initialize():
+    """Initialize the registry with all VEX functions"""
+    from .functions.initialize import initialize_registry
+    initialize_registry()
+
+__all__ = [
+    # Legacy direct access (deprecated)
+    'registry',
+    'VexFunctionRegistry',
+    
+    # Preferred API access
+    'registry_api',
+    'RegistryAPI',
+    
+    # Common types and enums
+    'VexFunctionSignature',
+    'VexFunctionParameter',
+    'ParameterMode',
+    'SimulationCategory',
+    'SimulationBehavior',
+    'FunctionCategory',
+    'SubCategory',
+    
+    # Utility objects
+    'categorizer',
+    'language_mapper',
+    'validator',
+    
+    # Functions
+    'initialize'
+]

vex_ast/registry/api.py

@@ -0,0 +1,155 @@
+"""API layer for the VEX function registry.
+
+This module provides a clean API for accessing the VEX function registry,
+hiding implementation details and providing a more stable interface.
+"""
+
+from typing import Dict, List, Optional, Union, Tuple, Any, Set
+
+from .registry import registry, VexFunctionRegistry
+from .signature import VexFunctionSignature, SimulationCategory
+from .categories import FunctionCategory, SubCategory
+from ..types.base import VexType
+
+class RegistryAPI:
+    """API layer for the VEX function registry."""
+    
+    def __init__(self, registry_instance: VexFunctionRegistry = None):
+        """Initialize with a registry instance or use the singleton."""
+        self._registry = registry_instance or registry
+    
+    def get_function(self, name: str, language: str = "python") -> Optional[VexFunctionSignature]:
+        """Get a function signature by name.
+        
+        Args:
+            name: The function name
+            language: The language to use for name resolution ("python" or "cpp")
+            
+        Returns:
+            The function signature if found, None otherwise
+        """
+        return self._registry.get_function(name, language)
+    
+    def get_method(self, object_type: Union[VexType, str], 
+                  method_name: str) -> Optional[VexFunctionSignature]:
+        """Get a method signature for an object type and method name.
+        
+        Args:
+            object_type: The object type or type name
+            method_name: The method name
+            
+        Returns:
+            The method signature if found, None otherwise
+        """
+        return self._registry.get_method(object_type, method_name)
+    
+    def get_functions_by_category(self, category: FunctionCategory) -> List[VexFunctionSignature]:
+        """Get all functions in a category.
+        
+        Args:
+            category: The function category
+            
+        Returns:
+            List of function signatures in the category
+        """
+        return self._registry.get_functions_by_category(category)
+    
+    def get_functions_by_subcategory(self, subcategory: SubCategory) -> List[VexFunctionSignature]:
+        """Get all functions in a subcategory.
+        
+        Args:
+            subcategory: The function subcategory
+            
+        Returns:
+            List of function signatures in the subcategory
+        """
+        return self._registry.get_functions_by_subcategory(subcategory)
+    
+    def get_functions_by_simulation(self, 
+                                  sim_category: SimulationCategory) -> List[VexFunctionSignature]:
+        """Get all functions with a specific simulation category.
+        
+        Args:
+            sim_category: The simulation category
+            
+        Returns:
+            List of function signatures with the simulation category
+        """
+        return self._registry.get_functions_by_simulation(sim_category)
+    
+    def validate_call(self, function_name: str, 
+                     args: List[Any],
+                     kwargs: Dict[str, Any],
+                     language: str = "python") -> Tuple[bool, Optional[str]]:
+        """Validate a function call.
+        
+        Args:
+            function_name: The function name
+            args: The positional arguments
+            kwargs: The keyword arguments
+            language: The language to use for name resolution
+            
+        Returns:
+            A tuple of (valid, error_message)
+        """
+        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],
+                           kwargs: Dict[str, Any]) -> Tuple[bool, Optional[str]]:
+        """Validate a method call on an object.
+        
+        Args:
+            object_type: The object type or type name
+            method_name: The method name
+            args: The positional arguments
+            kwargs: The keyword arguments
+            
+        Returns:
+            A tuple of (valid, error_message)
+        """
+        return self._registry.validate_method_call(object_type, method_name, args, kwargs)
+    
+    def get_all_functions(self) -> List[VexFunctionSignature]:
+        """Get all registered functions.
+        
+        Returns:
+            List of all function signatures
+        """
+        return self._registry.get_all_functions()
+    
+    def get_function_names(self) -> Set[str]:
+        """Get all registered function names.
+        
+        Returns:
+            Set of function names
+        """
+        return {func.name for func in self.get_all_functions()}
+    
+    def get_categories(self) -> List[FunctionCategory]:
+        """Get all available function categories.
+        
+        Returns:
+            List of function categories
+        """
+        return list(FunctionCategory)
+    
+    def get_subcategories(self) -> List[SubCategory]:
+        """Get all available function subcategories.
+        
+        Returns:
+            List of function subcategories
+        """
+        return list(SubCategory)
+    
+    def get_simulation_categories(self) -> List[SimulationCategory]:
+        """Get all available simulation categories.
+        
+        Returns:
+            List of simulation categories
+        """
+        return list(SimulationCategory)
+
+# Singleton instance
+registry_api = RegistryAPI()

vex_ast/registry/categories.py

@@ -0,0 +1,136 @@
+from enum import Enum, auto
+from typing import Set, Dict, List, Optional, Tuple
+
+class FunctionCategory(Enum):
+    """Categories for VEX functions"""
+    MOTOR = auto()             # Motor control functions
+    DRIVETRAIN = auto()        # Drivetrain control functions
+    SENSOR = auto()            # Sensor reading functions
+    DISPLAY = auto()           # Display output functions
+    TIMING = auto()            # Timing control functions
+    COMPETITION = auto()       # Competition control functions
+    CONTROLLER = auto()        # Controller input functions
+    BRAIN = auto()             # Brain functions
+    UTILITY = auto()           # Utility functions
+    EVENT = auto()             # Event handling
+    OTHER = auto()             # Other functions
+
+class SubCategory(Enum):
+    """Subcategories for more fine-grained classification"""
+    # Motor subcategories
+    MOTOR_SPIN = auto()
+    MOTOR_STOP = auto()
+    MOTOR_CONFIGURATION = auto()
+    MOTOR_MEASUREMENT = auto()
+    
+    # Drivetrain subcategories
+    DRIVE_MOVEMENT = auto()
+    DRIVE_TURN = auto()
+    DRIVE_CONFIGURATION = auto()
+    
+    # Sensor subcategories
+    DISTANCE_SENSOR = auto()
+    INERTIAL_SENSOR = auto()
+    ROTATION_SENSOR = auto()
+    OPTICAL_SENSOR = auto()
+    VISION_SENSOR = auto()
+    LIMIT_SWITCH = auto()
+    BUMPER = auto()
+    GPS_SENSOR = auto()
+    
+    # Display subcategories
+    SCREEN_DRAWING = auto()
+    SCREEN_TEXT = auto()
+    SCREEN_CLEARING = auto()
+    
+    # Timing subcategories
+    WAIT = auto()
+    TIMER = auto()
+    
+    # Competition subcategories
+    COMPETITION_STATUS = auto()
+    COMPETITION_CONTROL = auto()
+    
+    # Controller subcategories
+    BUTTON_INPUT = auto()
+    JOYSTICK_INPUT = auto()
+    CONTROLLER_SCREEN = auto()
+    CONTROLLER_RUMBLE = auto()
+    
+    # Brain subcategories
+    BRAIN_BATTERY = auto()
+    BRAIN_SCREEN = auto()
+    BRAIN_BUTTONS = auto()
+    BRAIN_SD_CARD = auto()
+    
+    # Utility subcategories
+    MATH = auto()
+    RANDOM = auto()
+    COLOR = auto()
+    
+    # Event subcategories
+    CALLBACK = auto()
+    EVENT_REGISTRATION = auto()
+    
+    # Other subcategories
+    SYSTEM = auto()
+    DEBUGGING = auto()
+
+class FunctionCategorizer:
+    """Utility for categorizing VEX functions"""
+    
+    def __init__(self):
+        self.category_patterns: Dict[FunctionCategory, List[str]] = {
+            FunctionCategory.MOTOR: ["motor", "spin", "velocity", "torque", "efficiency"],
+            FunctionCategory.DRIVETRAIN: ["drive", "turn", "drivetrain"],
+            FunctionCategory.SENSOR: ["sensor", "distance", "inertial", "rotation", "optical", "vision", "limit", "bumper", "gps"],
+            FunctionCategory.DISPLAY: ["display", "print", "draw", "screen", "clear"],
+            FunctionCategory.TIMING: ["wait", "sleep", "delay", "timer"],
+            FunctionCategory.COMPETITION: ["competition", "autonomous", "driver"],
+            FunctionCategory.CONTROLLER: ["controller", "button", "joystick", "rumble"],
+            FunctionCategory.BRAIN: ["brain", "battery"],
+            FunctionCategory.UTILITY: ["random", "math", "color"],
+            FunctionCategory.EVENT: ["event", "callback", "when", "register"],
+        }
+        
+        self.subcategory_patterns: Dict[SubCategory, List[str]] = {
+            # Motor subcategories
+            SubCategory.MOTOR_SPIN: ["spin", "rotate"],
+            SubCategory.MOTOR_STOP: ["stop", "brake"],
+            SubCategory.MOTOR_CONFIGURATION: ["set_", "configure"],
+            SubCategory.MOTOR_MEASUREMENT: ["current", "temperature", "velocity", "position"],
+            
+            # Additional subcategory patterns can be added as needed
+        }
+    
+    def categorize_function(self, 
+                           function_name: str, 
+                           description: str = "") -> Tuple[FunctionCategory, Optional[SubCategory]]:
+        """Categorize a function based on its name and description"""
+        function_name = function_name.lower()
+        description = description.lower()
+        
+        # Try to find the main category
+        category = FunctionCategory.OTHER
+        for cat, patterns in self.category_patterns.items():
+            for pattern in patterns:
+                if pattern in function_name or pattern in description:
+                    category = cat
+                    break
+            if category != FunctionCategory.OTHER:
+                break
+        
+        # Try to find the subcategory
+        subcategory = None
+        for subcat, patterns in self.subcategory_patterns.items():
+            for pattern in patterns:
+                if pattern in function_name or pattern in description:
+                    subcategory = subcat
+                    break
+            if subcategory:
+                break
+        
+        return category, subcategory
+
+# Singleton instance
+categorizer = FunctionCategorizer()

vex_ast/registry/language_map.py

@@ -0,0 +1,78 @@
+from typing import Dict, Set, List, Optional, Tuple
+
+class LanguageMapper:
+    """Utility for mapping between Python and C++ function names"""
+    
+    def __init__(self):
+        self.python_to_cpp: Dict[str, str] = {}
+        self.cpp_to_python: Dict[str, str] = {}
+        
+        # Common pattern transformations
+        # Python: snake_case, C++: camelCase or PascalCase
+        self.python_patterns = {
+            "set_": "set",
+            "get_": "get",
+            "is_": "is",
+            "has_": "has",
+        }
+    
+    def register_mapping(self, python_name: str, cpp_name: str) -> None:
+        """Register a mapping between Python and C++ function names"""
+        self.python_to_cpp[python_name] = cpp_name
+        self.cpp_to_python[cpp_name] = python_name
+    
+    def get_cpp_name(self, python_name: str) -> Optional[str]:
+        """Get the C++ name for a Python function name"""
+        # Direct lookup
+        if python_name in self.python_to_cpp:
+            return self.python_to_cpp[python_name]
+        
+        # Try pattern matching
+        for py_pattern, cpp_pattern in self.python_patterns.items():
+            if python_name.startswith(py_pattern):
+                # Convert snake_case to camelCase
+                rest = python_name[len(py_pattern):]
+                parts = rest.split('_')
+                camel_case = parts[0] + ''.join(part.capitalize() for part in parts[1:])
+                return cpp_pattern + camel_case.capitalize()
+        
+        # Default: convert snake_case to camelCase
+        parts = python_name.split('_')
+        return parts[0] + ''.join(part.capitalize() for part in parts[1:])
+    
+    def get_python_name(self, cpp_name: str) -> Optional[str]:
+        """Get the Python name for a C++ function name"""
+        # Direct lookup
+        if cpp_name in self.cpp_to_python:
+            return self.cpp_to_python[cpp_name]
+        
+        # Try to convert camelCase to snake_case
+        result = ''
+        for char in cpp_name:
+            if char.isupper() and result:
+                result += '_'
+            result += char.lower()
+        return result
+
+# Singleton instance
+language_mapper = LanguageMapper()
+
+# Register common VEX function mappings
+common_mappings = {
+    # Motor functions
+    "spin": "spin",
+    "stop": "stop",
+    "set_velocity": "setVelocity",
+    "set_stopping": "setStopping",
+    
+    # Drivetrain functions
+    "drive": "drive",
+    "turn": "turn",
+    "drive_for": "driveFor",
+    "turn_for": "turnFor",
+    
+    # Add more mappings as needed
+}
+
+for py_name, cpp_name in common_mappings.items():
+    language_mapper.register_mapping(py_name, cpp_name)

vex_ast/registry/registry.py

@@ -0,0 +1,153 @@
+from typing import Dict, List, Optional, Set, Tuple, Any, Union
+from enum import Enum
+from .signature import VexFunctionSignature, VexFunctionParameter, SimulationCategory
+from ..types.base import VexType
+from .categories import FunctionCategory, SubCategory, categorizer
+from .language_map import language_mapper
+from .simulation_behavior import SimulationBehavior
+
+class VexFunctionRegistry:
+    """Registry for storing and retrieving VEX function signatures"""
+    
+    _instance = None
+    
+    @classmethod
+    def register(cls, signature: VexFunctionSignature) -> None:
+        """Static method to register a function signature in the registry"""
+        instance = cls()
+        instance.register_function(signature)
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(VexFunctionRegistry, cls).__new__(cls)
+            cls._instance._initialize()
+        return cls._instance
+    
+    def _initialize(self) -> None:
+        """Initialize the registry"""
+        self.functions: Dict[str, VexFunctionSignature] = {}
+        self.functions_by_category: Dict[FunctionCategory, List[VexFunctionSignature]] = {}
+        self.functions_by_subcategory: Dict[SubCategory, List[VexFunctionSignature]] = {}
+        self.functions_by_simulation: Dict[SimulationCategory, List[VexFunctionSignature]] = {}
+        self.method_map: Dict[Tuple[str, str], VexFunctionSignature] = {}  # (object_type, method_name) -> signature
+        
+        # Initialize category dictionaries
+        for category in FunctionCategory:
+            self.functions_by_category[category] = []
+        
+        for subcategory in SubCategory:
+            self.functions_by_subcategory[subcategory] = []
+        
+        for sim_category in SimulationCategory:
+            self.functions_by_simulation[sim_category] = []
+    
+    def register_function(self, signature: VexFunctionSignature) -> None:
+        """Register a function signature in the registry"""
+        # Register by name
+        self.functions[signature.name] = signature
+        
+        # Register Python and C++ name variations
+        if signature.python_name and signature.python_name != signature.name:
+            self.functions[signature.python_name] = signature
+        
+        if signature.cpp_name and signature.cpp_name != signature.name:
+            self.functions[signature.cpp_name] = signature
+        
+        # Register by simulation category
+        self.functions_by_simulation[signature.category].append(signature)
+        
+        # Categorize function
+        category, subcategory = categorizer.categorize_function(
+            signature.name, signature.description
+        )
+        
+        # Register by category
+        self.functions_by_category[category].append(signature)
+        
+        # Register by subcategory if available
+        if subcategory:
+            self.functions_by_subcategory[subcategory].append(signature)
+        
+        # Register as method if applicable
+        if signature.object_type and signature.method_name:
+            key = (signature.object_type.name, signature.method_name)
+            self.method_map[key] = signature
+    
+    def get_function(self, 
+                    name: str, 
+                    language: str = "python") -> Optional[VexFunctionSignature]:
+        """Get a function signature by name"""
+        # Try direct lookup
+        if name in self.functions:
+            return self.functions[name]
+        
+        # Try language-specific lookup
+        if language == "cpp":
+            python_name = language_mapper.get_python_name(name)
+            if python_name and python_name in self.functions:
+                return self.functions[python_name]
+        elif language == "python":
+            cpp_name = language_mapper.get_cpp_name(name)
+            if cpp_name and cpp_name in self.functions:
+                return self.functions[cpp_name]
+        
+        return None
+    
+    def get_method(self, 
+                  object_type: Union[VexType, str], 
+                  method_name: str) -> Optional[VexFunctionSignature]:
+        """Get a method signature for an object type and method name"""
+        type_name = object_type.name if hasattr(object_type, 'name') else str(object_type)
+        key = (type_name, method_name)
+        return self.method_map.get(key)
+    
+    def get_functions_by_category(self, category: FunctionCategory) -> List[VexFunctionSignature]:
+        """Get all functions in a category"""
+        return self.functions_by_category.get(category, [])
+    
+    def get_functions_by_subcategory(self, subcategory: SubCategory) -> List[VexFunctionSignature]:
+        """Get all functions in a subcategory"""
+        return self.functions_by_subcategory.get(subcategory, [])
+    
+    def get_functions_by_simulation(self, 
+                                  sim_category: SimulationCategory) -> List[VexFunctionSignature]:
+        """Get all functions with a specific simulation category"""
+        return self.functions_by_simulation.get(sim_category, [])
+    
+    def validate_call(self, 
+                     function_name: str, 
+                     args: List[Any],
+                     kwargs: Dict[str, Any],
+                     language: str = "python") -> Tuple[bool, Optional[str]]:
+        """Validate a function call"""
+        # Get the function signature
+        signature = self.get_function(function_name, language)
+        if not signature:
+            return False, f"Unknown function: {function_name}"
+        
+        # Validate arguments
+        return signature.validate_arguments(args, kwargs)
+    
+    def validate_method_call(self,
+                           object_type: Union[VexType, str],
+                           method_name: str,
+                           args: List[Any],
+                           kwargs: Dict[str, Any]) -> Tuple[bool, Optional[str]]:
+        """Validate a method call on an object"""
+        # Get the method signature
+        signature = self.get_method(object_type, method_name)
+        if not signature:
+            type_name = object_type.name if hasattr(object_type, 'name') else str(object_type)
+            return False, f"Unknown method {method_name} for type {type_name}"
+        
+        # Validate arguments
+        return signature.validate_arguments(args, kwargs)
+    
+    def get_all_functions(self) -> List[VexFunctionSignature]:
+        """Get all registered functions"""
+        # Use set to remove duplicates since a function can be registered multiple times
+        # with different names
+        return list(set(self.functions.values()))
+
+# Singleton instance
+registry = VexFunctionRegistry()