vex-ast 0.2.4__py3-none-any.whl → 0.2.6__py3-none-any.whl

vex_ast/registry/README.md

@@ -1,29 +1,107 @@
-# VEX AST Registry Package (vex_ast.registry)
-
-This package manages the registration and organization of VEX V5 Robot Python language features, including functions, objects, and other elements.
-
-Purpose
-
-The registry provides a centralized system for defining and accessing information about VEX-specific language constructs. This information is used by the parser, type checker, and other tools to understand and process VEX code.
-
-Structure
-
-The package is organized into several modules:
-
-*   `categories.py`: Defines categories for organizing registry entries.
-*   `language_map.py`: Maps VEX language features to their Python equivalents.
-*   `registry.py`: Implements the core registry logic.
-*   `signature.py`: Defines the structure for function signatures.
-*   `simulation_behavior.py`: Specifies how VEX features should behave in a simulation environment.
-*   `validation.py`: Provides validation rules for registry entries.
-*   `functions/`: Contains submodules for specific function categories (e.g., drivetrain, motor, sensors).
-
-Key Concepts
-
-*   Registration: VEX language features are registered with the registry, providing metadata about their syntax, semantics, and simulation behavior.
-*   Organization: The registry organizes features into categories and subcategories for easy access and management.
-*   Validation: Registry entries are validated to ensure consistency and correctness.
-
-Usage
-
-The registry is used internally by the VEX AST parser and other tools. It is not typically accessed directly by users.
+# VEX AST Registry Package (vex_ast.registry)
+
+This package manages the registration and organization of VEX V5 Robot Python language features, including functions, objects, and their semantic behaviors.
+
+## Purpose
+
+The registry provides a centralized system for defining and accessing information about VEX-specific language constructs. It powers intelligent parsing, type checking, and simulation capabilities by maintaining a comprehensive database of VEX functions and their properties.
+
+## Architecture
+
+### Core Components
+
+*   `categories.py`: Implements the dual-axis categorization system
+    - `VexCategory`: Defines what a component is (MOTOR, SENSOR, DISPLAY, etc.)
+    - `BehaviorType`: Defines what a component does (CONTROL, READ, CONFIG, etc.)
+    - `SubCategory`: Provides granular classification within categories
+    - `FunctionCategorizer`: Intelligent categorization based on name and description
+
+*   `api.py`: Clean API layer for registry access
+    - Abstracts internal implementation details
+    - Provides intuitive query methods
+    - Maintains backward compatibility
+
+*   `registry.py`: Core registry implementation
+    - Thread-safe singleton pattern
+    - Efficient lookup structures
+    - Category/behavior indexing
+
+*   `signature.py`: Function signature system
+    - Parameter definitions and validation
+    - Return type tracking
+    - Language mapping (Python/C++)
+
+### Function Organization
+
+Functions are registered using a multi-dimensional classification:
+
+```
+Component → Category (what it is) → Behavior (what it does) → Subcategory (specific role)
+Example: motor.spin → MOTOR → CONTROL → MOTOR_SPIN
+```
+
+## Usage
+
+### Basic Registry Access
+
+```python
+from vex_ast.registry.api import registry_api
+
+# Get functions by category
+motor_functions = registry_api.get_functions_by_category(VexCategory.MOTOR)
+
+# Get functions by behavior
+control_functions = registry_api.get_functions_by_behavior(BehaviorType.CONTROL)
+
+# Combined queries
+motor_control = registry_api.get_functions_by_category_and_behavior(
+    VexCategory.MOTOR, 
+    BehaviorType.CONTROL
+)
+
+# Validate function calls
+valid, error = registry_api.validate_call("motor.spin", args, kwargs)
+```
+
+### Function Registration
+
+```python
+from vex_ast.registry.signature import VexFunctionSignature, VexFunctionParameter
+from vex_ast.registry.categories import VexCategory, BehaviorType
+
+# Define function signature
+signature = VexFunctionSignature(
+    name="spin",
+    return_type=VOID,
+    parameters=[
+        VexFunctionParameter("direction", DIRECTION_TYPE),
+        VexFunctionParameter("velocity", FLOAT, 50.0),
+        VexFunctionParameter("units", VELOCITY_UNITS, "RPM")
+    ],
+    description="Spin the motor in the specified direction",
+    category=VexCategory.MOTOR,
+    behavior=BehaviorType.CONTROL,
+    python_name="spin",
+    cpp_name="spin",
+    object_type=MOTOR,
+    method_name="spin"
+)
+
+# Register the function
+registry.register_function(signature)
+```
+
+## Backward Compatibility
+
+The registry maintains full backward compatibility with legacy systems:
+- `SimulationCategory` enum is preserved and mapped to new categories
+- Old API methods continue to work
+- Automatic conversion between old and new category systems
+
+## Extension Points
+
+Extend the registry by:
+1. Adding new `VexCategory` values
+2. Defining new `BehaviorType` entries
+3. Creating custom `SubCategory` classifications
+4. Implementing specialized validation logic

vex_ast/registry/__init__.py

@@ -1,51 +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'
-]
+"""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

@@ -1,155 +1,190 @@
-"""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()
+"""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 VexCategory, BehaviorType, 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: VexCategory) -> 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_behavior(self, behavior: BehaviorType) -> List[VexFunctionSignature]:
+        """Get all functions with a specific behavior type.
+        
+        Args:
+            behavior: The behavior type
+            
+        Returns:
+            List of function signatures with the behavior type
+        """
+        return self._registry.get_functions_by_behavior(behavior)
+    
+    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[VexCategory]:
+        """Get all available function categories.
+        
+        Returns:
+            List of function categories
+        """
+        return list(VexCategory)
+    
+    def get_behaviors(self) -> List[BehaviorType]:
+        """Get all available behavior types.
+        
+        Returns:
+            List of behavior types
+        """
+        return list(BehaviorType)
+    
+    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)
+    
+    def get_functions_by_category_and_behavior(self, 
+                                             category: VexCategory,
+                                             behavior: BehaviorType) -> List[VexFunctionSignature]:
+        """Get all functions with a specific category and behavior.
+        
+        Args:
+            category: The function category
+            behavior: The behavior type
+            
+        Returns:
+            List of function signatures with the category and behavior
+        """
+        category_funcs = self.get_functions_by_category(category)
+        behavior_funcs = self.get_functions_by_behavior(behavior)
+        return list(set(category_funcs) & set(behavior_funcs))
+
+# Singleton instance
+registry_api = RegistryAPI()